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

## 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/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/test-plan.md` voor het volledige testplan.

## Database

![ERD](./docs/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/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/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/functional.md)
- [Technische architectuur](docs/architecture.md)
- [Backlog](docs/backlog.md)
- [Agent-instructie audit](docs/agent-instruction-audit.md)