janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/README.md
Janpeter Visser 7e45bbdbc0
docs: AI-optimized docs restructure (Phases 1–8) (#61) 
* docs(dialog-pattern): add generic entity-dialog spec

Introduceert docs/patterns/dialog.md als bron-of-truth voor elke
create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende
dataobject. Bevat 14 secties: uitgangspunten, stack, component-
architectuur, layout, validatie, drielaagse demo-policy, submission,
dialog-gedrag, theming, footer, triggers/URL-state, per-entiteit
profile-template, out-of-scope, en een verificatie-checklist.

Registreert het patroon in CLAUDE.md "Implementatiepatronen"-tabel
zodat Claude (en mensen) de spec verplicht raadplegen voor elke
nieuwe dialog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(dialog-pattern): convert task spec + add pbi/story entity-profiles

Reduceert docs/scrum4me-task-dialog.md van 507 naar ~140 regels: alle
gedeelde regels verhuisd naar docs/patterns/dialog.md, dit document
bevat nu alleen Task-specifieke velden, URL-pattern, status-veld,
server actions, triggers en bewuste out-of-scope-keuzes.

Voegt twee nieuwe entity-profielen toe voor bestaande dialogen:
- docs/scrum4me-pbi-dialog.md (PbiDialog: state-based, code+title-rij,
  PbiStatusSelect, geen delete in v1)
- docs/scrum4me-story-dialog.md (StoryDialog: state-based, header met
  status/priority badges, inline activity-log, demo-readonly-fallback,
  inline-delete-confirm i.p.v. AlertDialog)

Beide profielen documenteren expliciet de "Bekende gaps t.o.v.
generieke spec" zodat opvolgende PR's de afwijkingen kunnen
rechtzetten of bewust kunnen accorderen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Added pdevelopment docs

* docs(plans): add docs-restructure plan for AI-optimized lookup

Audit of existing 39 doc files (~10.700 lines) and a phased restructure
proposal aimed at minimising the tokens an AI agent has to read to find
the right reference. Captures resolved decisions on language (English),
ADR template (Nygard default with MADR escape-hatch), index generator
(node script), and folder taxonomy. Proposal status — fase 1 to follow.

* docs(adr): add ADR scaffolding (templates, README, meta-ADR)

Set up docs/adr/ as the canonical home for architecture decisions:

- templates/nygard.md — default four-section format (Status, Context,
  Decision, Consequences) for one-way-door decisions.
- templates/madr.md — MADR v4 with YAML front-matter and explicit
  Considered Options for decisions where rejected alternatives matter.
- README.md — naming convention (NNNN-kebab-case), template-selection
  guidance (Nygard default; MADR for auth, queue mechanics, agent
  integration), status lifecycle, and ADR roster.
- 0000-record-architecture-decisions.md — meta-ADR establishing the
  practice itself, in Nygard format.

Backfilling existing implicit decisions (base-ui-over-radix, float
sort_order, demo-user three-layer policy, etc.) is fase 6 of the
docs-restructure plan.

* feat(docs): add docs index generator + initial INDEX.md

scripts/generate-docs-index.mjs walks docs/**/*.md, parses YAML
front-matter (or first H1 fallback) and a Nygard-style ## Status
section, then writes docs/INDEX.md with grouped tables for ADRs,
Specs, Plans (with archive subsection), Patterns, and Other.

Pure Node 20 (no external deps); idempotent — running it twice
produces byte-identical output. Excludes adr/templates/, the ADR
README, INDEX.md itself, and any *_*.md sidecar file.

Wire-up:
- package.json: docs:index → node scripts/generate-docs-index.mjs

Initial run indexed 35 docs across the existing structure; the
generated INDEX.md is committed so the table is reviewable in the
PR before hooking generation into a pre-commit step.

* chore: ignore Obsidian vault and personal sidecar files

Add .obsidian/ (Obsidian vault config) and _*.md (personal sidecar
notes) to .gitignore so the docs/ tree can serve as canonical source
of truth while still being usable as an Obsidian vault for personal
authoring. The docs index generator already excludes the same _*.md
pattern from INDEX.md.

* docs(plans): add PBI bulk-create spec for docs-restructure

Machine-parseable spec for an executor that calls the scrum4me MCP
(create_pbi → create_story → create_task) to seed the docs-restructure
work into the DB.

- Section 1 (Context) is the PBI description; serves as task-context
  via mcp__scrum4me__get_claude_context.
- Section 2 lists the 6 resolved decisions (English, MD3+styling
  merged, solo-paneel merged, .Plans archived, Nygard ADR default,
  node index script).
- Section 3 records what already shipped on this branch so the
  executor doesn't duplicate the ADR scaffolding or index generator.
- Section 4 carries the structured YAML graph: 1 PBI, 8 stories
  (one per phase), 39 tasks. product_id is REPLACE_ME — fill before
  running.
- YAML validated with PyYAML; field schema sanity-checked.

* docs(junk-cleanup): remove stub patterns/test.md

* docs(junk-cleanup): archive .Plans/ to docs/plans/archive/

* docs(front-matter): add YAML front-matter to docs/ root

* docs(front-matter): add YAML front-matter to patterns/

* docs(front-matter): add YAML front-matter to plans + agent files

* docs(index): regenerate INDEX.md after front-matter pass

* docs(naming): drop scrum4me- prefix from doc filenames

* docs(naming): lowercase API.md and MD3 filenames

* docs(naming): rename plan file to kebab-case ASCII

* docs(naming): rename middleware.md to proxy.md (next 16)

* docs(naming): polish CLAUDE.md doc-index after renames

* docs(taxonomy): scaffold topical folders under docs/

* docs(taxonomy): move spec files into docs/specs/

* docs(taxonomy): move design/api/qa/backlog/assets into folders

* docs(taxonomy): move agent-instruction-audit into decisions/

* docs(split): break architecture.md into 6 topical files

* docs(split): merge solo-paneel-spec into specs/functional.md

* docs(split): merge md3-color-scheme into design/styling

* docs(trim): extract branch/commit rules into runbook

* docs(trim): extract MCP integration into runbook

* docs(adr): add 0001-base-ui-over-radix

* docs(adr): add 0002-float-sort-order

* docs(adr): add 0003-one-branch-per-milestone

* docs(adr): add 0004-status-enum-mapping

* docs(adr): add 0005-iron-session-over-nextauth

* docs(adr): add 0006-demo-user-three-layer-policy

* docs(adr): add 0007-claude-question-channel-design

* docs(adr): add 0008-agent-instructions-in-claude-md + update README index

* docs(index): regenerate after ADR 0001-0008

* docs(glossary): add docs/glossary.md

* chore(docs): regenerate INDEX.md in pre-commit hook

* docs(readme): link INDEX + glossary + agent instructions

* feat(docs): add doc-link checker script

* chore(docs): wire docs:check-links and docs npm scripts

* ci(docs): block merge on broken doc links

* docs(links): fix broken cross-references after restructure

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 03:21:59 +02:00

291 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Scrum4Me – Agile Project Management Tool
## Portfolio samenvatting
Scrum4Me is een moderne fullstack webapplicatie voor agile projectmanagement.
De applicatie is gebouwd als portfolio-project om mijn vaardigheden in moderne softwareontwikkeling, cloud deployment en AI-assisted development te demonstreren.
## Doel
Veel teams missen overzicht en flexibiliteit in agile workflows.
Scrum4Me biedt een lichtgewicht, web-based oplossing voor het beheren van sprints, taken en teamprocessen.
## Mijn rol
- Architectuur en ontwerp
- Fullstack development (frontend + backend)
- Database ontwerp
- Implementatie van authenticatie en API's
- CI/CD en deployment
- AI-assisted development workflow
## Functionaliteiten
- Agile dashboards en product backlogs
- PBI-, story-, sprint- en taakbeheer
- Authenticatie en gebruikersbeheer
- Teamtoegang via eigenaar of gekoppelde Developer
- API tokens voor externe integraties
- REST API voor Claude Code workflows
- Drag-and-drop interactie voor planning
- Story-activiteitenlog voor plannen, testresultaten en commits
- Profielfoto, bio en rolbeheer
## Technologie stack
- Next.js 16 (App Router)
- React 19
- TypeScript
- Prisma ORM
- PostgreSQL (Neon)
- iron-session en bcryptjs
- Zustand
- dnd-kit
- Tailwind CSS en shadcn/ui
- Sharp voor avatarverwerking
- Vercel Analytics
- Vercel hosting
- GitHub Actions / CI-CD
## Documentation
- [docs/INDEX.md](docs/INDEX.md) — generated index of all docs (front-matter driven)
- [docs/glossary.md](docs/glossary.md) — domain terms (PBI, Story, MCP-job, etc.)
- [CLAUDE.md](CLAUDE.md) / [AGENTS.md](AGENTS.md) — agent instructions
## Architectuur (kort)
- Frontend en backend via Next.js App Router
- Server Components voor data loading
- Server Actions voor UI-mutaties
- Route Handlers voor de externe REST API
- Database via Prisma + PostgreSQL
- Auth via versleutelde sessiecookies
- Producttoegang via eigenaar of `product_members`
- Deployment via Vercel met Neon als database
## Live demo
Voeg hier je Vercel link toe.
## Screenshots
Voeg hier screenshots toe van dashboard, product backlog, sprint planning en instellingen.
## Wat ik geleerd heb
- Werken met moderne fullstack architectuur in Next.js
- Databaseontwerp met Prisma en PostgreSQL
- Server Actions combineren met REST API Route Handlers
- Beveiliging van cross-user en cross-scope toegang
- AI-assisted development integreren in een eigen workflow
- Cloud deployment en verificatie via Vercel
- Documentatie en agent-instructies verbeteren op basis van code review
## Toekomstige verbeteringen
- Multi-user samenwerking verder uitbreiden
- Notificaties
- Performance optimalisatie
- Uitbreiding AI-functionaliteit
- Meer integratietests voor autorisatie en API-flows
## Repository
https://github.com/madhura68/Scrum4Me
---
## Technische aanvulling
Deze sectie bevat de praktische projectinformatie die nodig is om de app lokaal te draaien, te deployen en veilig door te ontwikkelen.
### Lokale setup
1. Installeer dependencies:
```bash
npm ci
```
2. Maak lokale environment variabelen:
```bash
cp .env.example .env.local
```
Vul daarna `DATABASE_URL` en `SESSION_SECRET` in. `DIRECT_URL` is optioneel lokaal, maar handig voor migraties in cloudomgevingen.
3. Synchroniseer of migreer de database:
```bash
npx prisma db push
```
4. Genereer Prisma Client en de ERD:
```bash
npm run db:erd
```
Deze command voert lokaal `prisma generate` uit. Daardoor worden zowel de Prisma Client als `docs/assets/erd.svg` opnieuw opgebouwd.
In CI en deployment wordt bewust alleen de Prisma Client gegenereerd met `prisma generate --generator client`. Het ERD-diagram gebruikt Mermaid/Puppeteer en wordt daarom niet in GitHub Actions of Vercel gegenereerd.
5. Seed testdata indien nodig:
```bash
npx prisma db seed
```
6. Start de app:
```bash
npm run dev
```
### Testing
**Unit tests (Vitest, geen database vereist):**
```bash
npm test
```
Verwacht: alle 69 tests slagen, 0 failures.
**API curl-tests (vereist lopende dev server + API token):**
```bash
# Zie scripts/README.md voor setup-instructies
bash scripts/test-api.sh
```
De curl-tests dekken alle 7 API-endpoints: auth (401), demo-blokkering (403), inputvalidatie (400) en happy paths. Zie `docs/qa/api-test-plan.md` voor het volledige testplan.
## Database
![ERD](./docs/assets/erd.svg)
De databasevisualisatie wordt lokaal gegenereerd uit `prisma/schema.prisma` via `prisma-erd-generator`.
Handmatige generatie:
```bash
npm run db:erd
```
Tijdens lokale development draait `npm run dev` naast Next.js ook `npm run db:erd:watch`. Bij wijzigingen in `prisma/schema.prisma` wordt `docs/assets/erd.svg` automatisch opnieuw gegenereerd.
Gebruik `npx prisma db push` alleen om het schema naar de database te synchroniseren. Gebruik `npm run db:erd` om lokaal Prisma Client en de ERD te genereren. Gebruik in CI uitsluitend `npx prisma generate --generator client`.
De app draait standaard op `http://localhost:3000`.
### Scripts
```bash
npm run dev # lokale development server
npm run lint # ESLint
npm test # Vitest test suite
npm run build # productiebuild zoals Vercel die verwacht
npm run db:erd # Prisma Client + docs/assets/erd.svg genereren
```
### Environment variables
Zie [.env.example](.env.example).
| Variabele | Verplicht | Doel |
|---|---:|---|
| `DATABASE_URL` | Ja | PostgreSQL connection string voor Prisma |
| `DIRECT_URL` | Nee | Directe Neon connection string voor migraties |
| `SESSION_SECRET` | Ja | Minimaal 32 tekens; gebruikt door iron-session |
| `NODE_ENV` | Nee | Wordt door Node/Vercel gezet |
Vercel Analytics gebruikt geen project-specifieke environment variabele in deze app; de component staat in `app/layout.tsx`.
## Commit Guidelines
We follow a strict commit structure to keep the project maintainable and reviewable.
### Rules
- 1 commit = 1 logical change
- Do not mix:
- features + docs
- features + config
- schema + UI
- Keep commits small and focused
- Prefer multiple small commits over one large commit
### Commit format
We use a simplified conventional commit style:
- feat: new feature
- fix: bug fix
- docs: documentation only
- chore: config / tooling / cleanup
- refactor: code improvement without behavior change
### Examples
Good:
```bash
feat(db): add user profile fields
feat(api): add avatar upload endpoint
feat(ui): add profile editor
docs: document profile feature
```
Bad:
```bash
feat: add profile + update docs + fix config
```
### API-overzicht
Alle API-endpoints vereisen:
```http
Authorization: Bearer <token>
```
| Methode | Endpoint | Doel |
|---|---|---|
| `GET` | `/api/products` | Actieve producten waarvoor de tokengebruiker eigenaar of teamlid is |
| `GET` | `/api/products/:id/next-story` | Volgende story uit de actieve sprint |
| `GET` | `/api/sprints/:id/tasks?limit=10` | Eerste taken van een sprint |
| `PATCH` | `/api/stories/:id/tasks/reorder` | Taakvolgorde aanpassen; alle IDs moeten bij de story horen |
| `POST` | `/api/stories/:id/log` | Implementatieplan, testresultaat of commit vastleggen |
| `PATCH` | `/api/tasks/:id` | Taakstatus of implementatieplan bijwerken |
| `POST` | `/api/todos` | Todo aanmaken binnen een productcontext |
### Security-regels
- Server Actions en Route Handlers vertrouwen nooit op losse client-ID's zonder scope-check.
- Producttoegang loopt via eigenaar of `product_members`.
- Bulk-mutaties valideren eerst dat alle IDs bij dezelfde toegankelijke parent horen.
- Denormalized fields zoals `story.product_id` worden afgeleid van de database-parent, niet van form-data.
- Demo-gebruikers krijgen 403 op schrijfoperaties.
### Deployment
De productieomgeving is gericht op Vercel + Neon.
1. Zet `DATABASE_URL`, eventueel `DIRECT_URL`, en `SESSION_SECRET` in Vercel.
2. Zorg dat de Neon-database gemigreerd is.
3. Push naar `main`; Vercel deployt automatisch.
4. Controleer na deployment:
- login en dashboard
- `/api/products` met een API-token
- avatar-upload
- Vercel Analytics in het Vercel dashboard
### Documentatie
- [Functionele specificatie](docs/specs/functional.md)
- [Technische architectuur](docs/architecture.md)
- [Backlog](docs/backlog/index.md)
- [Agent-instructie audit](docs/decisions/agent-instructions-history.md)
Reference in a new issue View git blame Copy permalink