florian.wilde/code-vorlage
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: rebuild template — Tailwind v4, Docker self-hosting, passkey auth

Browse Source 
Toolchain fixes (all previously broken):
- npm run lint: next lint was removed in Next 16 -> eslint with flat config
- .eslintrc.json was ignored by ESLint 9 -> eslint.config.mjs
- npm test / test:e2e exited 1 with no tests -> passWithNoTests
- Vitest scanned tests/ and would have run Playwright specs -> scoped to src/
- Playwright targeted Mobile Safari while docs installed only chromium
- reuseExistingServer silently tested a foreign server on :3000 -> E2E_PORT
- 11 high-severity vulns -> npm audit fix
- deny rule Read(**/.env*) also blocked .env.example -> precise patterns

Stack changes:
- Tailwind v3 -> v4 (CSS-first, no tailwind.config.ts, tw-animate-css)
- shadcn regenerated for v4; 33 components -> 6 core, bundled radix-ui
- Supabase removed entirely; data layer is now chosen per project
- Vercel removed; Docker Compose self-hosting with scripts/update.sh
- Better Auth + passkey plugin as the binding auth standard
- ThemeProvider and Sonner mounted; dark mode and toasts now actually work

Workflow system:
- Sub-agents wired: /frontend, /backend, /qa delegate to .claude/agents
- Checklists folded into their SKILL.md; one file per skill
- Rules rewritten: DB-agnostic backend, passkey security, v4 frontend
- Spec language settled as German, skill instructions English
This commit is contained in:
Florian Wilde
2026-08-09 00:48:50 +02:00
parent a8b196e92b
commit b0c4e9e9b9
101 changed files with 3651 additions and 7695 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/backend/SKILL.md
+54 -85
View File
@@ -1,113 +1,82 @@
---
name: backend
description: Build APIs, database schemas, and server-side logic with Supabase. Use after frontend is built.
argument-hint: "feature-spec-path"
description: Build route handlers, data access and Better Auth passkey flows. Use after frontend is built.
argument-hint: "PROJ-X or feature-spec-path"
user-invocable: true
---
# Backend Developer
# Backend
## Role
You are an experienced Backend Developer. You read feature specs + tech design and implement APIs, database schemas, and server-side logic using Supabase and Next.js.
You own the server-side phase for one feature. You do the interview and the review
with the user; the **Backend Developer** sub-agent does the implementation.
## Before Starting
1. Read `features/INDEX.md` for project context
2. Read the feature spec referenced by the user (including Tech Design section)
3. Check existing APIs: `git ls-files src/app/api/`
4. Check existing database patterns: `git log --oneline -S "CREATE TABLE" -10`
5. Check existing lib files: `ls src/lib/`
## 1. Load context
## Workflow
1. Read `features/INDEX.md`
2. Read the feature spec — Tech Design and the Technical Decisions table
3. `git ls-files src/app/api/` and `ls src/lib/`
### 1. Read Feature Spec + Design
- Understand the data model from Solution Architect
- Identify tables, relationships, and RLS requirements
- Identify API endpoints needed
**If the Tech Design does not name a data layer:**
> "Im Tech Design steht noch nicht, wo die Daten liegen sollen. Diese Vorlage bringt
> bewusst keine Datenbank mit — das entscheidet `/architecture` pro Projekt.
> Lass uns das dort klären, bevor ich Schema-Code schreibe."
→ Stop.
### 2. Ask Technical Questions
Use `AskUserQuestion` for:
- What permissions are needed? (Owner-only vs shared access)
- How do we handle concurrent edits?
- Do we need rate limiting for this feature?
- What specific input validations are required?
## 2. Clarify the open technical questions
### 3. Create Database Schema
- Write SQL for new tables in Supabase SQL Editor
- Enable Row Level Security on EVERY table
- Create RLS policies for all CRUD operations
- Add indexes on performance-critical columns (WHERE, ORDER BY, JOIN)
- Use foreign keys with ON DELETE CASCADE where appropriate
One at a time, each with a recommendation:
### 4. Create API Routes
- Create route handlers in `/src/app/api/`
- Implement CRUD operations
- Add Zod input validation on all POST/PUT endpoints
- Add proper error handling with meaningful messages
- Always check authentication (verify user session)
- Who may read and write these records? (owner only, shared, role-based)
- What happens on concurrent edits — last write wins, or conflict detection?
- Which validation rules beyond the obvious types?
- Does this feature need rate limiting?
- Does it need authentication? If yes: Better Auth with the passkey plugin is the
standard — see `.claude/rules/security.md`. Passkey primary, password only as a
fallback.
### 5. Connect Frontend
- Update frontend components to use real API endpoints
- Replace any mock data or localStorage with API calls
- Handle loading and error states
## 3. Set status
### 6. Write Integration Tests
For each API route created, write a Vitest integration test in `src/app/api/[route]/[route].test.ts`:
- Test the happy path (valid input → expected response)
- Test validation errors (invalid input → 400 with error message)
- Test authentication (unauthenticated request → 401)
- Test authorization (wrong user → 403)
- Run tests: `npm test`
Update `features/INDEX.md` and the spec header to **In Progress**. Verify by
re-reading.
### 7. User Review
- Walk user through the API endpoints created
- Show test results
- Ask: "Do the APIs work correctly? Any edge cases to test?"
## 4. Delegate implementation
## Context Recovery
If your context was compacted mid-task:
1. Re-read the feature spec you're implementing
2. Re-read `features/INDEX.md` for current status
3. Run `git diff` to see what you've already changed
4. Run `git ls-files src/app/api/` to see current API state
5. Continue from where you left off - don't restart or duplicate work
Invoke the **Backend Developer** sub-agent with:
- the spec path
- the data-layer decision from the Tech Design
- the answers from step 2
- which frontend components need wiring to real endpoints
## Output Format Examples
Wait for its report. Do not implement in parallel yourself.
### Database Migration
```sql
CREATE TABLE tasks (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
title TEXT NOT NULL,
status TEXT CHECK (status IN ('todo', 'in_progress', 'done')) DEFAULT 'todo',
created_at TIMESTAMPTZ DEFAULT NOW()
);
## 5. Review with the user
ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
Walk through the endpoints created and the test results, then:
> "Funktionieren die Endpunkte so? Fällt dir ein Randfall ein, den wir noch testen sollten?"
CREATE POLICY "Users see own tasks" ON tasks
FOR SELECT USING (auth.uid() = user_id);
Iterate by sending follow-up instructions to the same sub-agent.
CREATE INDEX idx_tasks_user_id ON tasks(user_id);
CREATE INDEX idx_tasks_status ON tasks(status);
```
## 6. Wrap up
## Production References
- See [database-optimization.md](../../../docs/production/database-optimization.md) for query optimization
- See [rate-limiting.md](../../../docs/production/rate-limiting.md) for rate limiting setup
## Checklist
See [checklist.md](checklist.md) for the full implementation checklist.
After completion, update tracking files:
- [ ] Feature spec updated with implementation notes
- [ ] `features/INDEX.md` status updated to "In Progress"
Verify before declaring done:
- [ ] `npm test`, `npm run lint`, `npm run typecheck`, `npm run build` pass
- [ ] Zod validation on every write endpoint
- [ ] Session checked in every handler; ownership scoped inside the query
- [ ] If auth: passkey is the primary flow
- [ ] Indexes on filtered/sorted columns, list queries bounded
- [ ] Every new env var is in `.env.example`
- [ ] No secrets in source
- [ ] Frontend wired to real endpoints, mock data removed
- [ ] Spec updated with implementation notes (written **and** re-read)
- [ ] `features/INDEX.md` status is In Progress
- [ ] User approved
## Handoff
After completion:
> "Backend is done! Next step: Run `/qa` to test this feature against its acceptance criteria."
## Git Commit
> "Backend steht. Nächster Schritt: `/qa` zum Testen gegen die Acceptance Criteria."
## Commit
```
feat(PROJ-X): Implement backend for [feature name]
```
.claude/skills/backend/checklist.md
-33
View File
@@ -1,33 +0,0 @@
# Backend Implementation Checklist
## Core Checklist
- [ ] Checked existing tables/APIs via git before creating new ones
- [ ] Database tables created in Supabase
- [ ] Row Level Security enabled on ALL new tables
- [ ] RLS policies created for SELECT, INSERT, UPDATE, DELETE
- [ ] Indexes created on performance-critical columns
- [ ] Foreign keys set with appropriate ON DELETE behavior
- [ ] All planned API endpoints implemented in `/src/app/api/`
- [ ] Authentication verified (no access without valid session)
- [ ] Input validation with Zod on all POST/PUT requests
- [ ] Meaningful error messages with correct HTTP status codes
- [ ] No TypeScript errors in API routes
- [ ] All endpoints tested manually
- [ ] No hardcoded secrets in source code
- [ ] Frontend connected to real API endpoints
- [ ] User has reviewed and approved
## Verification (run before marking complete)
- [ ] `npm run build` passes without errors
- [ ] All acceptance criteria from feature spec addressed in API
- [ ] All API endpoints return correct status codes (test with curl or browser)
- [ ] `features/INDEX.md` status updated to "In Progress"
- [ ] Code committed to git
## Performance Checklist
- [ ] All frequently filtered columns have indexes
- [ ] No N+1 queries (use Supabase joins instead of loops)
- [ ] All list queries use `.limit()`
- [ ] Zod validation on all write endpoints
- [ ] Slow queries cached where appropriate (optional for MVP)
- [ ] Rate limiting on public-facing APIs (optional for MVP)