# req-planner

## What This Is

A standalone requirements management tool with interactive graph visualization, hierarchical decomposition, TMCS quality gates, and code traceability. Built as a general-purpose planning tool that connects to any repository. Used by a single developer to decompose project goals into traceable, testable requirements organized as a DAG.

## Core Value

Every requirement is traceable from abstract goal to code-level leaf with quality validation at every level — the requirements graph IS the code graph.

## Current Milestone: v2.0 Multi-Tenancy & User Accounts

**Goal:** Replace single shared password with individual user accounts, per-user workspaces, role-based access control, and project sharing.

**Target features:**
- User registration and login (individual accounts)
- Per-user project ownership and workspaces
- Role-based access control (owner, editor, viewer)
- Project sharing and collaboration

## Requirements

### Validated

<!-- Shipped in v1.0 and confirmed working -->

- ✓ Hierarchical requirement decomposition (pillars → requirements → sub-requirements → leaves) — v1.0
- ✓ Interactive DAG graph with Cytoscape.js + dagre layout — v1.0
- ✓ Semantic zoom (4 detail levels) — v1.0
- ✓ TMCS quality gates with auto/manual validation — v1.0
- ✓ Measurable gate enforcement (forced false without test spec) — v1.0
- ✓ Cross-pillar satisfaction links — v1.0
- ✓ Password-based authentication with JWT — v1.0
- ✓ Full CRUD for requirements, projects, links, layouts — v1.0
- ✓ Edit history with version snapshots and restore — v1.0
- ✓ Named graph layouts (save/load/default) — v1.0
- ✓ Canvas undo (Ctrl+Z, 20-state stack) — v1.0
- ✓ Dashboard with statistics — v1.0
- ✓ Gitea issue integration fields — v1.0
- ✓ Focus mode (shallow + deep) with state preservation — v1.0
- ✓ Multi-shortcut graph interactions (Click, Shift, Alt, Ctrl, Right-click) — v1.0
- ✓ Gitea badge on graph nodes — v1.0
- ✓ Detail panel with inline editing, history, links — v1.0

### Active

<!-- Current scope — v2.0 Multi-Tenancy & User Accounts -->

(Defining requirements)

### Out of Scope

- Real-time collaborative editing — complexity too high for v2, consider v3
- OAuth/SSO providers — email/password sufficient initially
- Mobile app — web-first

## Context

- Backend: Python 3.12+, FastAPI, SQLAlchemy 2.0, SQLite
- Frontend: Angular 17, Cytoscape.js, RxJS, SCSS dark theme
- Database: SQLite at data/planner.db with 5 tables (requirement_nodes, cross_pillar_links, projects, requirement_history, graph_layouts)
- Current auth: single shared password with JWT tokens (24h expiry)
- Gitea instance at theres-a-git-in-this-tea.andrewawesomo.net for issue tracking
- Currently single-user — all data shared, no user isolation

## Constraints

- **Tech stack**: Must stay FastAPI + Angular + SQLite — no database migration
- **Backwards compatible**: Existing data must survive the migration
- **Self-hosted**: Runs on user's own infrastructure, no cloud dependencies

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| SQLite over PostgreSQL | Single-user simplicity, zero config | ✓ Good |
| JWT over sessions | Stateless, works with SPA | ✓ Good |
| Cytoscape.js for graph | Mature, supports semantic zoom | ✓ Good |
| localStorage for transient state | Fast, no backend round-trips | ✓ Good |
| Backend DB for durable state | Survives cache clear, device-independent | ✓ Good |
| Single password auth | Quick to implement for v1 | ⚠️ Revisit — replacing in v2 |

---
*Last updated: 2026-03-18 after v1.0 release*