158 lines
5.8 KiB
Markdown
158 lines
5.8 KiB
Markdown
# Non-Linear: v0.1-alpha Scope
|
|
|
|
## Validation Goal
|
|
|
|
> Can a team of 3-5 people use this as their sole tracker for two weeks without falling back to another tool?
|
|
|
|
Ship the smallest thing that tests whether **graph-native structure + repo-inferred skeleton + agent graph traversal** is better than Linear for a small team. Everything else can wait.
|
|
|
|
## What Ships
|
|
|
|
### Data Model
|
|
|
|
- **Two node types:** Components (skeleton, map to code) and Issues (work, flow through statuses)
|
|
- **Decomposition tree:** strict parent→child hierarchy, single root, single project
|
|
- **Lateral links:** `blocks` and `relates_to` only
|
|
- **Statuses:** backlog, todo, in_progress, in_review, done, cancelled (permissive transitions)
|
|
- **Labels:** freeform tags, no enforced taxonomy
|
|
- **Complete change history:** every mutation stored with actor + timestamp
|
|
|
|
No user-facing "layers" concept. The 4-layer architecture is an internal design pattern — in alpha, there is simply structure and work.
|
|
|
|
### Repository Integration
|
|
|
|
This is the differentiator. It must ship.
|
|
|
|
- **Connect repos:** OAuth to GitHub/GitLab, select repos for a project
|
|
- **Skeleton inference:** AI scans repo structure → proposes component tree → user adjusts → skeleton committed
|
|
- **Commit-message linking:** `fixes NL-42` / `refs NL-42` triggers status change or surfaces in activity feed (regex parsing via webhook)
|
|
|
|
### Views
|
|
|
|
Two views, not four:
|
|
|
|
- **Focus widget:** Node + parent + children + breadcrumbs + detail panel + comments + change history. Primary daily-use view.
|
|
- **Flat list / Kanban board:** Issues listed or grouped by status columns. Sorting, filtering by label/assignee/status. Bulk status change.
|
|
|
|
A simple **collapsible tree sidebar** replaces the full layered overview graph visualization.
|
|
|
|
### Interaction
|
|
|
|
- **Command palette (`Cmd+K`):** Fuzzy search across nodes and actions. Non-negotiable for keyboard-first.
|
|
- **Keyboard navigation:** `Alt+↑/↓/←/→` for tree traversal in focus widget.
|
|
- **Confirmation dialogs** for destructive/structural operations (replaces full plan-then-apply previews).
|
|
|
|
### Triage
|
|
|
|
- **Inbox:** Issues without a parent land here. Triage = assign a parent via command palette or drag.
|
|
|
|
### Auth & Permissions
|
|
|
|
- **Authentik OIDC:** Login for humans
|
|
- **API tokens:** Bearer tokens for agents, issued manually
|
|
- **Three hardcoded roles:**
|
|
- Owner — all actions
|
|
- Member — all except delete and manage members
|
|
- Agent — read + comment + change status + triage (assign parent)
|
|
|
|
No policy engine. No subtree scoping. No custom roles.
|
|
|
|
### Agent API
|
|
|
|
**Read operations:**
|
|
|
|
```
|
|
GET /api/v1/nodes/{id}
|
|
GET /api/v1/nodes/{id}/children
|
|
GET /api/v1/nodes/{id}/parent
|
|
GET /api/v1/nodes/{id}/links
|
|
GET /api/v1/nodes/{id}/path
|
|
GET /api/v1/projects/{id}/root
|
|
GET /api/v1/projects/{id}/inbox
|
|
```
|
|
|
|
**Write operations:**
|
|
|
|
```
|
|
POST /api/v1/nodes/{id}/comments
|
|
PATCH /api/v1/nodes/{id}/status
|
|
PATCH /api/v1/nodes/{id}/parent
|
|
```
|
|
|
|
**Queries:**
|
|
|
|
```
|
|
GET /api/v1/projects/{id}/nodes?status=todo&assignee=agent-1&unblocked=true
|
|
```
|
|
|
|
**Webhooks (minimal):** Register URL + events. Single delivery attempt, log failures. No retry logic, no HMAC signatures.
|
|
|
|
### Real-Time
|
|
|
|
- **Centrifugo:** Push status changes, new nodes, new comments to connected clients via `project:{id}` channel.
|
|
|
|
### Comments
|
|
|
|
- Flat comment stream per node. Markdown body. Author + timestamp.
|
|
|
|
### Infrastructure (~10 containers)
|
|
|
|
```
|
|
api (FastAPI + uvicorn)
|
|
frontend (Vue 3 + Vite)
|
|
worker (Taskiq — webhook delivery, skeleton inference)
|
|
neo4j
|
|
postgres
|
|
redis
|
|
centrifugo
|
|
caddy (reverse proxy + automatic TLS)
|
|
authentik (OIDC provider)
|
|
authentik-db (Authentik's Postgres)
|
|
```
|
|
|
|
- **Search:** Postgres `tsvector` full-text search (no Meilisearch)
|
|
- **File storage:** None (no uploads in alpha — links in descriptions suffice)
|
|
- **Secrets:** Environment variables / Docker secrets (no Vault)
|
|
- **Observability:** Structured JSON logs + `docker logs` (no Prometheus/Grafana/Loki/Tempo)
|
|
- **Deployment:** Single Docker Compose file, one machine. Dev = production topology.
|
|
|
|
## What Does NOT Exist in Alpha
|
|
|
|
| Feature | Reason to Defer |
|
|
|---------|----------------|
|
|
| Layer 3 (Code Connections) | Complex inference, unclear daily value until skeleton is stable |
|
|
| Layer 4 (Artifacts) | A URL in the description works for 2 weeks |
|
|
| Layer toggles in UI | No Layer 3/4 data to toggle |
|
|
| Cycles | Time-boxing is nice-to-have, not thesis-critical |
|
|
| Notifications (email/push) | In-app real-time is enough for a co-located/online team |
|
|
| Full policy engine | Not testing permission granularity |
|
|
| Natural language node creation | Manual creation via palette is fast enough |
|
|
| Plan-then-apply previews | Confirmation dialog suffices |
|
|
| Comment reactions | Zero impact on validation |
|
|
| Observability stack | Structured logs are enough |
|
|
| Secrets management (Vault) | Env vars for single-node deployment |
|
|
| Tauri desktop wrapper | Browser-only |
|
|
| Meilisearch | Postgres tsvector is sufficient for small graphs |
|
|
| MinIO / file uploads | Descriptions can link to external files |
|
|
| Pagination | Graphs will be small (<500 nodes) |
|
|
|
|
## Success Criteria
|
|
|
|
- Team uses Non-Linear as sole tracker for 2+ weeks
|
|
- No fallback to Linear/spreadsheet for any workflow
|
|
- At least one repo connected with inferred skeleton
|
|
- Agent produces at least 1 useful action per day
|
|
- Users create trees with 3+ depth levels
|
|
- Command palette action <200ms, view transitions <100ms
|
|
|
|
## After Alpha Validates
|
|
|
|
Features flow from feedback, not speculation:
|
|
|
|
- Users want to attach design files → add Artifacts (Layer 4)
|
|
- Users want dependency visibility → add Code Connections (Layer 3)
|
|
- Agents need subtree isolation → add policy engine
|
|
- Teams are distributed → add notifications (email/push)
|
|
- Graph viz is too limited → build the layered overview
|
|
- Projects grow large → add pagination, Meilisearch, cycles
|