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