Scrum4Me/docs/manual/01-overview.md

title	status	audience	language	last_updated	when_to_read
Overview	active	contributor	en	2026-05-07	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

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).
• 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.

For status lifecycles of each entity, see 02 — Statuses & Transitions.

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
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.

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.

For a deeper structural breakdown including stores, realtime channels, and the job queue, see docs/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.
• Idea — Pre-PBI staging artefact (M12). Has its own state machine; see 02.

The complete glossary lives at docs/glossary.md.

What's next

→ 02 — Statuses & Transitions covers how each entity moves through its lifecycle, with state-machine diagrams.