# SoloPM — Overview & Master Index

SoloPM is a self-hostable project management system for **solo developers and small teams (fewer than 10 users per instance/team)**. It is deliberately small: no sprints, no custom workflows, no permission matrices, no multi-tenancy. Any user in the instance can be added to any project; the whole instance *is* the team.

This `plans/` directory is the complete build specification. It was designed from two references: a prior partial attempt ("first iteration": schema + prose specs + Vue shell) and Taiga (feature-mined, enterprise surface dropped). All product decisions here are final — build agents must not relitigate them (rationale lives in [17-decisions.md](17-decisions.md)).

## How to use these plans

- Every buildable/verifiable item in these files is a markdown checkbox (`- [ ]`).
- **When you complete an item, edit the file and mark it `- [x]`.** Both AI build agents and the human owner use these checkboxes as the single source of progress truth.
- Do not check items you did not verify. Partial work stays unchecked.
- Work proceeds in phases ([16-phases.md](16-phases.md)). Each phase names the spec files it needs; read those plus `00`, `01`, `02` before starting.

## Locked stack

- **Backend**: Go — chi (router), pgx (Postgres driver), sqlc (type-safe queries from SQL), golang-migrate (migrations), alexedwards/scs (sessions). No ORM, no framework.
- **Frontend**: Vue 3 + TypeScript, Vite, Pinia, Vue Router, Tailwind CSS, pnpm. Soft UI design system ([14-design-system.md](14-design-system.md)).
- **Database**: PostgreSQL 16+. **Search**: Meilisearch. **Email**: SMTP.
- **Deployment**: one Go binary embedding the built SPA via `go:embed`; runs bare with env config, or via reference docker-compose (app + postgres + meilisearch). See [15-deployment.md](15-deployment.md).

## Reading order

| Order | File | What it covers |
|---|---|---|
| 1 | [00-overview.md](00-overview.md) | This file — product scope, index, progress |
| 2 | [01-architecture.md](01-architecture.md) | Repo layout, layering, config, conventions |
| 3 | [02-data-model.md](02-data-model.md) | Complete Postgres schema |
| 4 | [03-domain-events.md](03-domain-events.md) | Event outbox, jobs, consumers |
| 5 | [04-api.md](04-api.md) | API conventions + full route index |
| 6 | [05-auth.md](05-auth.md) | Sessions, OAuth, personal access tokens |
| 7 | [06-projects.md](06-projects.md) | Projects, members, labels, dependencies |
| 8 | [07-issues-epics.md](07-issues-epics.md) | Issues, sub-issues, blockers, epics, kanban ranks |
| 9 | [08-collaboration.md](08-collaboration.md) | Comments, attachments, links, wiki, markdown, watchers |
| 10 | [09-notifications-realtime.md](09-notifications-realtime.md) | Bell/inbox, email, SSE |
| 11 | [10-search.md](10-search.md) | Meilisearch indexes + sync |
| 12 | [11-integrations.md](11-integrations.md) | Incoming/outgoing webhooks, export |
| 13 | [12-retention.md](12-retention.md) | Soft deletes, culling job |
| 14 | [13-frontend.md](13-frontend.md) | Routes, pages, stores, components |
| 15 | [14-design-system.md](14-design-system.md) | Visual tokens + component recipes |
| 16 | [15-deployment.md](15-deployment.md) | Build pipeline, compose, ops |
| 17 | [16-phases.md](16-phases.md) | Phased roadmap + acceptance criteria |
| 18 | [17-decisions.md](17-decisions.md) | Decision log (rationale, non-negotiables) |

## Glossary

- **Issue** — the unit of work. Has a per-project sequential number (`#N`), optional parent issue (sub-issue), optional epic, optional assignee.
- **Epic** — a project-scoped grouping of issues for larger initiatives, with color, status, and progress (issue counts + story-point rollup).
- **Watcher** — a user subscribed to an issue's changes. Auto-watch happens on create/assign/comment/mention; **muted** means "never auto-rewatch me".
- **System user** — reserved user id 1; performs automated actions (webhook automation). Cannot log in.
- **Zombie user** — reserved user id 2 ("Deleted User"); inherits records orphaned by user culling.
- **Audit log** — immutable record of every mutation; source of all activity feeds.
- **Outbox / events table** — transactional record of domain events, fanned out to notifications, SSE, search sync, and outgoing webhooks.
- **Culling** — the scheduled hard-delete job that erases soft-deleted rows (and their disk files) after `CULL_AFTER_DAYS`.
- **PAT** — personal access token (`solopm_…`) for API/CLI auth.

## What "done" looks like

A user runs `docker compose up` (or the bare binary against their own Postgres/Meilisearch), registers (first account becomes admin), creates a project, invites teammates, and manages epics and issues through a list view and a drag-and-drop kanban board. Comments, mentions, attachments, and wiki pages work with markdown; `@mention` and `#N` cross-links resolve. A second browser sees changes live via SSE, the bell shows notifications, emails arrive per user preference. Search (Cmd+K) finds anything in the user's projects. Merged PRs on GitHub/Gitea that say `closes #N` complete issues automatically; outgoing webhooks notify external URLs; projects export to JSON/CSV. Soft-deleted data is culled on schedule, files included.

## Progress

### Phases (see [16-phases.md](16-phases.md) for detail)

- [ ] Phase 0 — Foundation (scaffold, config, migrations wiring, SPA shell, compose, healthz)
- [ ] Phase 1 — Auth & users
- [ ] Phase 2 — Event backbone & audit log
- [ ] Phase 3 — Projects core
- [ ] Phase 4 — Issues & epics
- [ ] Phase 5 — Views (frontend core)
- [ ] Phase 6 — Collaboration
- [ ] Phase 7 — Notifications & real-time
- [ ] Phase 8 — Search
- [ ] Phase 9 — Integrations
- [ ] Phase 10 — Retention & hardening

### Spec files authored

- [x] 00-overview.md
- [x] 01-architecture.md
- [x] 02-data-model.md
- [x] 03-domain-events.md
- [x] 04-api.md
- [x] 05-auth.md
- [x] 06-projects.md
- [x] 07-issues-epics.md
- [x] 08-collaboration.md
- [x] 09-notifications-realtime.md
- [x] 10-search.md
- [x] 11-integrations.md
- [x] 12-retention.md
- [x] 13-frontend.md
- [x] 14-design-system.md
- [x] 15-deployment.md
- [x] 16-phases.md
- [x] 17-decisions.md