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