Template
Florian Wilde
b0c4e9e9b9
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
135 lines
3.9 KiB
Markdown
135 lines
3.9 KiB
Markdown
---
|
|
name: architecture
|
|
description: Design PM-friendly technical architecture for a feature. No code, only high-level decisions.
|
|
argument-hint: "PROJ-X or feature-spec-path"
|
|
user-invocable: true
|
|
---
|
|
|
|
# Architecture
|
|
|
|
You translate a feature spec into a design a non-technical stakeholder can follow —
|
|
and you make the binding technical decisions the developers will implement.
|
|
|
|
## Hard rule: no code
|
|
|
|
No SQL, no TypeScript, no API snippets. Describe **what** gets built and **why**,
|
|
never **how** in detail. Structure and plain language only.
|
|
|
|
## 1. Load context
|
|
|
|
1. Read `features/INDEX.md`
|
|
2. Read `docs/PRD.md`
|
|
3. Read the feature spec
|
|
4. `git ls-files src/components/ src/app/api/` — what already exists
|
|
|
|
**If the status is "Roadmap" or no spec file exists:**
|
|
> "PROJ-X hat noch keine Spec. Führe erst `/write-spec PROJ-X` aus — ohne User Stories
|
|
> und Acceptance Criteria kann ich das Design nicht entwerfen."
|
|
→ Stop.
|
|
|
|
## 2. Resolve the open decisions
|
|
|
|
One question at a time, each with a recommendation.
|
|
|
|
### Data layer (decide this first — it shapes everything else)
|
|
|
|
This template deliberately ships **no** database or ORM. Decide per feature:
|
|
|
|
> "Wo sollen die Daten liegen?"
|
|
> Empfehlung: Ohne Nutzerkonten und ohne Gerätewechsel reicht localStorage. Sobald
|
|
> Daten einen Neustart überleben oder zwischen Nutzern geteilt werden müssen, braucht
|
|
> es eine Datenbank im Compose-Stack.
|
|
|
|
If a database is needed, also settle the ORM/driver, and record both in the
|
|
Technical Decisions table. Constraint: it must be self-hostable in the Docker
|
|
Compose stack — no managed-only services.
|
|
|
|
### Authentication
|
|
|
|
> "Braucht dieses Feature angemeldete Nutzer?"
|
|
|
|
If yes, the stack is fixed: **Better Auth with the passkey plugin**, passkey as the
|
|
primary method, password only as a fallback. Do not re-open that choice — note it
|
|
as a dependency and move on.
|
|
|
|
### Remaining questions
|
|
|
|
- Multiple user roles with different permissions?
|
|
- Third-party integrations?
|
|
- Anything with unusual performance or volume characteristics?
|
|
|
|
## 3. Write the design
|
|
|
|
Add a **Tech Design** section to the spec containing:
|
|
|
|
**A) Component structure** — a plain tree of the UI parts:
|
|
```
|
|
Board-Seite
|
|
├── Eingabefeld (neue Aufgabe)
|
|
├── Spalte "Offen"
|
|
│ └── Aufgabenkarte (verschiebbar)
|
|
├── Spalte "Erledigt"
|
|
└── Leerzustand
|
|
```
|
|
|
|
**B) Data model** — in words, no schema:
|
|
```
|
|
Eine Aufgabe hat:
|
|
- eindeutige ID
|
|
- Titel (max. 200 Zeichen)
|
|
- Status (offen / erledigt)
|
|
- Erstellzeitpunkt
|
|
|
|
Gespeichert in: Browser-localStorage (kein Server nötig)
|
|
```
|
|
|
|
**C) Tech decisions** — each justified in language a PM understands
|
|
|
|
**D) Dependencies** — package names with a one-line purpose each
|
|
|
|
## 4. Log the decisions
|
|
|
|
Every meaningful choice goes into the spec's **Technical Decisions** table:
|
|
|
|
```
|
|
| Entscheidung | Begründung | Datum |
|
|
| localStorage statt Datenbank | Keine Nutzerkonten, Daten bleiben gerätelokal | 2026-08-09 |
|
|
```
|
|
|
|
Log at minimum: storage approach, ORM/driver if any, auth yes/no, package choices,
|
|
and anything a future developer would otherwise question.
|
|
|
|
Anything unresolved goes to **Open Questions** as `- [ ]`.
|
|
|
|
## 5. Review
|
|
|
|
Present the design and ask:
|
|
> "Ergibt das Design so Sinn? Irgendwo Fragen oder Bauchschmerzen?"
|
|
|
|
Wait for approval.
|
|
|
|
## 6. Wrap up
|
|
|
|
- [ ] Existing components and APIs checked
|
|
- [ ] Component structure documented, PM-readable
|
|
- [ ] Data model in plain language, no code
|
|
- [ ] Data layer decided and justified
|
|
- [ ] Auth need clarified (Better Auth + passkey if yes)
|
|
- [ ] Dependencies listed
|
|
- [ ] Technical Decisions table filled
|
|
- [ ] Open Questions recorded
|
|
- [ ] Design written into the spec and re-read to verify
|
|
- [ ] `features/INDEX.md` → **Architected**
|
|
- [ ] User approved
|
|
|
|
## Handoff
|
|
|
|
> "Design steht. Nächster Schritt: `/frontend` für die UI-Komponenten."
|
|
> Braucht das Feature einen Server-Teil, folgt `/backend` danach.
|
|
|
|
## Commit
|
|
|
|
```
|
|
docs(PROJ-X): Add technical design for [feature name]
|
|
```
|