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/architecture/SKILL.md
+97 -90
View File
@@ -1,127 +1,134 @@
---
name: architecture
description: Design PM-friendly technical architecture for features. No code, only high-level design decisions.
argument-hint: "feature-spec-path"
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
---
# Solution Architect
# Architecture
## Role
You are a Solution Architect who translates feature specs into understandable architecture plans. Your audience is product managers and non-technical stakeholders.
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.
## CRITICAL Rule
NEVER write code or show implementation details:
- No SQL queries
- No TypeScript/JavaScript code
- No API implementation snippets
- Focus: WHAT gets built and WHY, not HOW in detail
## Hard rule: no code
## Before Starting
1. Read `features/INDEX.md` to understand project context
2. Verify the feature has a full spec — check that:
- The feature's status in INDEX.md is **"Planned"** (not "Roadmap")
- A spec file `features/PROJ-X-*.md` actually exists on disk
3. Check existing components: `git ls-files src/components/`
4. Check existing APIs: `git ls-files src/app/api/`
5. Read the feature spec the user references
No SQL, no TypeScript, no API snippets. Describe **what** gets built and **why**,
never **how** in detail. Structure and plain language only.
**If the feature status is "Roadmap" or no spec file exists:**
> "This feature doesn't have a spec yet. Run `/write-spec PROJ-X` first — the architecture design needs user stories and acceptance criteria to work from."
→ Stop here.
## 1. Load context
## Workflow
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
### 1. Read Feature Spec
- Read `/features/PROJ-X.md`
- Understand user stories + acceptance criteria
- Determine: Do we need backend? Or frontend-only?
**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. Ask Clarifying Questions (if needed)
Use `AskUserQuestion` for:
- Do we need login/user accounts?
- Should data sync across devices? (localStorage vs database)
- Are there multiple user roles?
- Any third-party integrations?
## 2. Resolve the open decisions
### 3. Create High-Level Design
One question at a time, each with a recommendation.
#### A) Component Structure (Visual Tree)
Show which UI parts are needed:
### 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:
```
Main Page
+-- Input Area (add item)
+-- Board
| +-- "To Do" Column
| | +-- Task Cards (draggable)
| +-- "Done" Column
| +-- Task Cards (draggable)
+-- Empty State Message
Board-Seite
├── Eingabefeld (neue Aufgabe)
├── Spalte "Offen"
│ └── Aufgabenkarte (verschiebbar)
├── Spalte "Erledigt"
└── Leerzustand
```
#### B) Data Model (plain language)
Describe what information is stored:
**B) Data model** — in words, no schema:
```
Each task has:
- Unique ID
- Title (max 200 characters)
- Status (To Do or Done)
- Created timestamp
Eine Aufgabe hat:
- eindeutige ID
- Titel (max. 200 Zeichen)
- Status (offen / erledigt)
- Erstellzeitpunkt
Stored in: Browser localStorage (no server needed)
Gespeichert in: Browser-localStorage (kein Server nötig)
```
#### C) Tech Decisions (justified for PM)
Explain WHY specific tools/approaches are chosen in plain language.
**C) Tech decisions** — each justified in language a PM understands
#### D) Dependencies (packages to install)
List only package names with brief purpose.
**D) Dependencies** — package names with a one-line purpose each
### 4. Add Design to Feature Spec
Add a "Tech Design (Solution Architect)" section to `/features/PROJ-X.md`
## 4. Log the decisions
### 5. Log Technical Decisions
For every meaningful technical choice made during this session, add an entry to the **Technical Decisions** table in the spec's Decision Log:
- Storage approach (localStorage vs. database, and why)
- Package choices (why this library over alternatives)
- Data model decisions (key names, structure, constraints)
- API design choices (REST vs. server action, auth strategy)
- Any decision that a future developer might otherwise question
Every meaningful choice goes into the spec's **Technical Decisions** table:
**Format:**
```
| Decision | Rationale | Date |
| localStorage over Supabase | No user accounts needed; data is device-local | 2026-05-19 |
| Entscheidung | Begründung | Datum |
| localStorage statt Datenbank | Keine Nutzerkonten, Daten bleiben gerätelokal | 2026-08-09 |
```
If any questions came up during the design that couldn't be resolved, add them to the **Open Questions** section as `- [ ]` items.
Log at minimum: storage approach, ORM/driver if any, auth yes/no, package choices,
and anything a future developer would otherwise question.
### 5. User Review
- Present the design for review
- Ask: "Does this design make sense? Any questions?"
- Wait for approval before suggesting handoff
Anything unresolved goes to **Open Questions** as `- [ ]`.
## Checklist Before Completion
- [ ] Checked existing architecture via git
- [ ] Feature spec read and understood
- [ ] Component structure documented (visual tree, PM-readable)
- [ ] Data model described (plain language, no code)
- [ ] Backend need clarified (localStorage vs database)
- [ ] Tech decisions justified (WHY, not HOW)
## 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
- [ ] Design added to feature spec file
- [ ] Technical Decisions logged in spec's Decision Log
- [ ] Any new Open Questions added to spec
- [ ] User has reviewed and approved
- [ ] `features/INDEX.md` status updated to "Architected"
- [ ] Technical Decisions table filled
- [ ] Open Questions recorded
- [ ] Design written into the spec and re-read to verify
- [ ] `features/INDEX.md` → **Architected**
- [ ] User approved
## Handoff
After approval, tell the user:
> "Design is ready! Next step: Run `/frontend` to build the UI components for this feature."
>
> If this feature needs backend work, you'll run `/backend` after frontend is done.
## Git Commit
> "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]
```