Scrum4Me/README.md

# 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)
- [Agent-instructie audit](docs/decisions/agent-instructions-history.md)