Madhura68
10c52e8b8f
Vercel detecteert @prisma/client en runt automatisch `prisma generate` zonder --generator filter. Daardoor probeerde de erd-generator op Vercel te draaien en faalde op libnss3.so (puppeteer/Chrome niet beschikbaar in de build container). Cascading: de Prisma-client werd niet ge-update, runtime kreeg oude enum-waarden (ACTIVE i.p.v. OPEN). ERD is dev-only documentatie en niet meer in productie nodig. Generator + dependency + npm scripts + de gegenereerde svg verwijderd. README, prisma-client pattern en architecture docs bijgewerkt. Build script blijft `prisma generate && next build` zodat de client ook bij Vercel build-cache-hits opnieuw wordt gegenereerd.
291 lines
8.9 KiB
Markdown
291 lines
8.9 KiB
Markdown
# 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
|
||
|
||
- [CHANGELOG.md](CHANGELOG.md) — release-historie (Keep a Changelog)
|
||
- [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:
|
||
|
||
```bash
|
||
npx prisma generate
|
||
```
|
||
|
||
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 445 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
|
||
|
||
Het schema staat in `prisma/schema.prisma`; uitgebreide documentatie in [`docs/architecture/data-model.md`](./docs/architecture/data-model.md).
|
||
|
||
Gebruik `npx prisma db push` om schema-wijzigingen naar de database te synchroniseren. `npx prisma generate` (of `prisma generate --generator client` in CI) genereert de Prisma 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
|
||
```
|
||
|
||
### 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 (Prisma `directUrl`) |
|
||
| `SESSION_SECRET` | Ja | Minimaal 32 tekens; gebruikt door iron-session |
|
||
| `CRON_SECRET` | Productie | Bearer-secret voor `/api/cron/*` routes — required als crons aan staan |
|
||
| `NEXT_PUBLIC_VAPID_PUBLIC_KEY` | Nee | VAPID public key voor Web Push — genereer met `npx web-push generate-vapid-keys` |
|
||
| `VAPID_PRIVATE_KEY` | Nee | VAPID private key voor Web Push |
|
||
| `VAPID_SUBJECT` | Nee | Contact URI voor Web Push (bijv. `mailto:admin@example.com`) |
|
||
| `INTERNAL_PUSH_SECRET` | Nee | Bearer-secret voor `/api/internal/push/*` routes (min 32 tekens) |
|
||
| `NEXT_PUBLIC_SENTRY_DSN` | Nee | Sentry DSN — zonder is de SDK een no-op |
|
||
| `SENTRY_ORG` / `SENTRY_PROJECT` / `SENTRY_AUTH_TOKEN` | Nee | Source-map upload tijdens build |
|
||
| `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/health` | Liveness; `?db=1` doet ook een DB-ping (geen auth) |
|
||
| `GET` | `/api/products` | Actieve producten waarvoor de tokengebruiker eigenaar of teamlid is |
|
||
| `GET` | `/api/products/:id/next-story` | Hoogst geprioriteerde open story uit de actieve sprint |
|
||
| `GET` | `/api/products/:id/claude-context` | Bundled product / actieve sprint / next-story (met tasks) / open ideas voor MCP |
|
||
| `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 `implementation_plan` bijwerken |
|
||
| `GET / POST` | `/api/ideas` · `GET / PATCH /api/ideas/:id` | Idea CRUD (M12 — vervangt voormalige `/api/todos`) |
|
||
| `GET` | `/api/jobs/:id/sub-tasks` | `sprint_task_executions` van een SPRINT_IMPLEMENTATION-job |
|
||
| `GET` | `/api/users/:id/avatar` | Avatar van een specifieke gebruiker |
|
||
| `POST / GET` | `/api/profile/avatar` | Eigen avatar uploaden of opvragen |
|
||
|
||
Daarnaast leveren `/api/realtime/{backlog,solo,jobs,notifications}` SSE-streams en zijn er auth-helpers `/api/auth/pair/*` (QR-pairing, M10), interne push-routes onder `/api/internal/push/*`, en cron-handlers (`/api/cron/cleanup-agent-artifacts`, `/api/cron/expire-questions`).
|
||
|
||
### 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)
|