96 lines
6.1 KiB
Markdown
96 lines
6.1 KiB
Markdown
# 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
|