bd7478861b
* docs(PBI-58): add developer manual chapters under docs/manual/ Adds a 7-file English-language manual targeted at new human contributors: index, overview, statuses & transitions (with mermaid state diagrams), git workflow, MCP integration, docker, and troubleshooting. The manual is the *map* — it cross-references existing runbooks/ADRs/architecture docs rather than duplicating their content. Regenerates docs/INDEX.md and validates with check-doc-links.mjs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(PBI-58): add markdown rendering deps + manual:build script Adds mermaid, rehype-slug, rehype-autolink-headings for the in-app /manual page. Wires manual:build into prebuild so production builds always regenerate the chapter TOC. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-58): codegen script for in-app manual TOC scripts/build-manual.mjs walks docs/manual/, parses YAML front-matter, strips it from the body, and emits lib/manual.generated.ts with a typed ManualEntry[] containing slug, title, description, filePath, and the embedded markdown body. Pure Node 20, mirrors generate-docs-index.mjs. Inlining the markdown at build time keeps runtime serverless functions free of filesystem reads, which avoids whole-project NFT tracing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-58): /manual route renders developer manual chapters in-app Catch-all route at app/(app)/manual/[[...slug]]/page.tsx with generateStaticParams covering every TOC entry. Server-side MarkdownView uses react-markdown with remark-gfm, rehype-slug, and rehype-autolink-headings; mermaid code blocks are routed to a client-only MermaidBlock that dynamic-imports mermaid on mount. ManualSidebar (client) reads the typed TOC and highlights the active chapter via usePathname. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-58): add Manual link to main nav bar Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
99 lines
5.1 KiB
Markdown
99 lines
5.1 KiB
Markdown
---
|
||
title: "Overview"
|
||
status: active
|
||
audience: [contributor]
|
||
language: en
|
||
last_updated: 2026-05-07
|
||
when_to_read: "First chapter — start here for the elevator pitch and project structure."
|
||
---
|
||
|
||
# 01 — Overview
|
||
|
||
## What is Scrum4Me?
|
||
|
||
Scrum4Me is a **desktop-first fullstack web app for solo developers and small Scrum teams** who manage multiple software projects in parallel. It models the Scrum hierarchy explicitly (Product → PBI → Story → Task), supports Sprints with split-screen drag-and-drop planning, and integrates Claude Code as an automated implementation worker — every result the agent produces is logged back into the originating story.
|
||
|
||
The app is deployable to **Vercel + Neon** (default) and can run **fully local** via the worker container. A built-in demo user has read-only access; Product Owners add Developers by username, and those Developers gain write access to that product's stories, tasks, and sprints.
|
||
|
||
## Entity hierarchy
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Product["Product<br/>(per repo)"]
|
||
Idea["Idea<br/>(pre-PBI staging)"]
|
||
PBI["PBI<br/>(Product Backlog Item)"]
|
||
Story["Story"]
|
||
Task["Task"]
|
||
Sprint["Sprint<br/>(cross-cutting)"]
|
||
|
||
Product --> Idea
|
||
Idea -.->|"AI-grilled & planned"| PBI
|
||
Product --> PBI
|
||
PBI --> Story
|
||
Story --> Task
|
||
Sprint -.->|"contains stories<br/>denormalised on tasks"| Story
|
||
Sprint -.-> Task
|
||
```
|
||
|
||
- **Product** — one row per repo. `repo_url`, `definition_of_done`, members.
|
||
- **Idea** — pre-PBI staging entity introduced in M12. Goes through `IDEA_GRILL` (AI Q&A loop) and `IDEA_MAKE_PLAN` jobs to produce a structured plan that can be turned into a PBI tree.
|
||
- **PBI** — a Product Backlog Item. Has `priority` (1–4) and `sort_order` (float, see [`docs/patterns/sort-order.md`](../patterns/sort-order.md)).
|
||
- **Story** — a unit of value under a PBI; has acceptance criteria. Lives in the backlog (`OPEN`) until added to a sprint.
|
||
- **Task** — the smallest unit; has an `implementation_plan` consumed by the Claude worker. `sprint_id` is denormalised from the parent story for query efficiency.
|
||
- **Sprint** — cross-cutting time-box. Stories are added to a sprint; tasks inherit `sprint_id`. Sprint execution has two modes: `PER_TASK` and `SPRINT_BATCH` — see [`docs/architecture/sprint-execution-modes.md`](../architecture/sprint-execution-modes.md).
|
||
|
||
For status lifecycles of each entity, see [02 — Statuses & Transitions](./02-statuses-and-transitions.md).
|
||
|
||
## Stack
|
||
|
||
| Layer | Technology |
|
||
|---|---|
|
||
| Framework | Next.js 16 (App Router) + React 19 |
|
||
| Language | TypeScript (strict) |
|
||
| Styling | Tailwind CSS + shadcn/ui + Material Design 3 tokens via [`app/styles/theme.css`](../../app/styles/theme.css) |
|
||
| Client state | Zustand + dnd-kit |
|
||
| Database | Prisma v7 + PostgreSQL (Neon) |
|
||
| Auth | iron-session + bcryptjs |
|
||
| Utilities | Zod, Sonner, Sharp, Vercel Analytics |
|
||
| Hosting | Vercel (app), Neon (DB), Mac/NAS Docker (worker) |
|
||
|
||
For the rationale behind each choice and the technologies we explicitly **don't** use, see [`docs/architecture/overview.md`](../architecture/overview.md).
|
||
|
||
## Repository layout
|
||
|
||
```
|
||
Scrum4Me/
|
||
├── app/ # Next.js App Router routes
|
||
│ ├── (app)/ # authenticated desktop UI
|
||
│ ├── (auth)/ # login, register, demo
|
||
│ ├── (mobile)/ # /m/* mobile shell (3 screens)
|
||
│ ├── api/ # REST route handlers (Claude integration)
|
||
│ └── styles/ # MD3 token CSS
|
||
├── components/ # shared UI components
|
||
├── lib/ # server/client utilities
|
||
│ └── task-status.ts # the ONLY place DB↔API enum mapping happens
|
||
├── prisma/ # schema + migrations
|
||
├── docs/ # this manual + ADRs, runbooks, patterns, specs
|
||
└── scripts/ # codegen, seeders, link checkers
|
||
```
|
||
|
||
The `*-server.ts` filename suffix marks server-only modules (DB, Node APIs). They must never be imported into a client component — see the hardstop in [`CLAUDE.md`](../../CLAUDE.md#hardstop-regels).
|
||
|
||
For a deeper structural breakdown including stores, realtime channels, and the job queue, see [`docs/architecture/project-structure.md`](../architecture/project-structure.md).
|
||
|
||
## Glossary refresh
|
||
|
||
A few terms used throughout this manual that often differ from "generic Scrum" usage:
|
||
|
||
- **PBI** — Product Backlog Item. Not "Feature" or "Epic".
|
||
- **Story** — A unit of work under a PBI. Not "Ticket" or "Issue".
|
||
- **Sprint Goal** — The narrative for a sprint. Not "Objective".
|
||
- **Worker** — A Claude Code agent claiming jobs from the Scrum4Me queue (M13).
|
||
- **Demo user** — A read-only built-in user; writes return `403`. See [`docs/adr/0006-demo-user-three-layer-policy.md`](../adr/0006-demo-user-three-layer-policy.md).
|
||
- **Idea** — Pre-PBI staging artefact (M12). Has its own state machine; see [02](./02-statuses-and-transitions.md#idea).
|
||
|
||
The complete glossary lives at [`docs/glossary.md`](../glossary.md).
|
||
|
||
## What's next
|
||
|
||
→ [02 — Statuses & Transitions](./02-statuses-and-transitions.md) covers how each entity moves through its lifecycle, with state-machine diagrams.
|