Update documentation for Non-Linear project: clarify the layered architecture, detail post-alpha features including artifact nodes and code connections, and refine agent integration specifications. Adjust scope and roadmap to reflect changes in project milestones and validation goals.
This commit is contained in:
Cнесарев Максим
parent
eae312a635
commit
79a7277ad9
@ -40,8 +40,8 @@ Software projects are easier to conceptualize top-down using graphs. Traditional
|
||||
## Design Principles
|
||||
|
||||
1. **Graph is the spine.** The decomposition tree defines project structure. Everything else — views, permissions, agent navigation — derives from graph position.
|
||||
2. **Four layers, one topology.** The graph is organized as four independent overlays on a shared spatial structure — like layers in a GIS. Layer 1 (Structure) is the component skeleton. Layer 2 (Work) is issues and coordination. Layer 3 (Code Connections) is technical dependencies between components. Layer 4 (Artifacts) is external context — docs, designs, media. Each layer answers a different question, has its own update cadence, and can be toggled independently in the UI and agent API.
|
||||
3. **Three node types.** Components are the skeleton (stable, map to code). Issues are the work (flow through statuses, get assigned). Artifacts are the context (docs, designs, screenshots attached to any node). Cleaner than untyped depth-as-type.
|
||||
2. **Four layers, one topology.** The graph is organized as four independent overlays on a shared spatial structure — like layers in a GIS. Layer 1 (Structure) is the component skeleton. Layer 2 (Work) is issues and coordination. Layer 3 (Code Connections) is technical dependencies between components. Layer 4 (Artifacts) is external context — docs, designs, media. Each layer answers a different question, has its own update cadence, and can be toggled independently in the UI and agent API. Alpha ships Layers 1+2 only; Layers 3 and 4 are introduced post-alpha.
|
||||
3. **Three node types (full vision).** Components are the skeleton (stable, map to code). Issues are the work (flow through statuses, get assigned). Artifacts are the context (docs, designs, screenshots attached to any node). Cleaner than untyped depth-as-type. Alpha ships with Components + Issues only; Artifacts are introduced post-alpha when attachment workflows are validated.
|
||||
4. **Code is the skeleton.** Connect your repos, infer the component tree. The fastest path from "nothing" to "structured project" is through code you already have. Code analysis also feeds Layer 3 — import graphs and API calls become visible dependency edges.
|
||||
5. **Agents are first-class actors.** Not assistants bolted on — agents have accounts, roles, permissions, and can traverse the graph independently. Agents can scope their view to specific layers — a triage agent sees only Layer 2, an impact analysis agent sees Layers 1+3.
|
||||
6. **Granular trust.** The permission system is policy-based from day one. Roles are convenience bundles over a granular engine, not hardcoded ceilings.
|
||||
|
||||
@ -20,7 +20,7 @@ The layers share the same spatial structure but carry different information. Lay
|
||||
|
||||
## Node Types
|
||||
|
||||
The graph has three node types: **components**, **issues**, and **artifacts**. Components form the skeleton (Layer 1); issues are work attached to that skeleton (Layer 2); artifacts are external context attached to any node (Layer 4).
|
||||
The graph has three node types: **components**, **issues**, and **artifacts**. Components form the skeleton (Layer 1); issues are work attached to that skeleton (Layer 2); artifacts are external context attached to any node (Layer 4). Alpha ships with components and issues only; artifacts are introduced post-alpha.
|
||||
|
||||
### Component Node
|
||||
|
||||
@ -62,7 +62,7 @@ An issue represents work to be done — a task, bug, feature, spike. Issues atta
|
||||
| `created_by` | actor_id | Creator (user or agent) |
|
||||
| `cycle_id` | cycle_id? | Current cycle membership |
|
||||
|
||||
### Artifact Node (Layer 4)
|
||||
### Artifact Node (Layer 4 — post-alpha)
|
||||
|
||||
An artifact represents external context — a document, design file, screenshot, or link — attached to any component or issue.
|
||||
|
||||
@ -223,9 +223,9 @@ These connect issues to other issues and describe work-level relationships.
|
||||
| `duplicates` | A is a duplicate of B | Directed | Issue → Issue |
|
||||
| `relates_to` | General work association | Undirected | Issue ↔ Issue |
|
||||
|
||||
### Layer 3: Code Connection Links
|
||||
### Layer 3: Code Connection Links (post-alpha)
|
||||
|
||||
These connect components to other components and describe technical dependencies. They can be auto-inferred from code analysis (import graphs, API routes, shared infrastructure) or declared manually.
|
||||
These connect components to other components and describe technical dependencies. They can be auto-inferred from code analysis (import graphs, API routes, shared infrastructure) or declared manually. Layer 3 is introduced post-alpha once the component skeleton is stable and teams express a need for dependency visibility.
|
||||
|
||||
| Type | Semantics | Directionality | Between |
|
||||
|------|-----------|----------------|---------|
|
||||
@ -241,9 +241,9 @@ Auto-inference sources for Layer 3 links:
|
||||
|
||||
Auto-inferred links are tagged `source: inferred` and can be overridden or dismissed manually.
|
||||
|
||||
### Layer 4: Artifact Attachment Links
|
||||
### Layer 4: Artifact Attachment Links (post-alpha)
|
||||
|
||||
These connect artifacts to the nodes they provide context for. Represented by the `HAS_ARTIFACT` edge in the decomposition tree (see Artifact Node above).
|
||||
These connect artifacts to the nodes they provide context for. Represented by the `HAS_ARTIFACT` edge. Introduced alongside Artifact nodes post-alpha.
|
||||
|
||||
### Backlinks (Inbound Link Surfacing)
|
||||
|
||||
|
||||
@ -4,7 +4,9 @@
|
||||
|
||||
Non-Linear provides two primary graph views, a flat fallback, and a cycle view. The interaction model is keyboard-first with a command palette as the primary navigation method.
|
||||
|
||||
## Layer Visibility
|
||||
> **Alpha ships:** Focus Widget + Flat List/Board + collapsible tree sidebar. The Layered Overview (graph viz), Cycle View, layer toggles, and notification system are post-alpha. See [06a-ALPHA-SCOPE.md](06a-ALPHA-SCOPE.md).
|
||||
|
||||
## Layer Visibility (post-alpha)
|
||||
|
||||
All graph views share a **layer toggle** — a set of controls that determine which of the four data layers are visible. Layers are independent overlays on the same spatial structure; toggling a layer on or off does not change node positions, only what information is rendered.
|
||||
|
||||
@ -46,10 +48,12 @@ When multiple layers are active, each layer contributes distinct visual elements
|
||||
- **Layer 3 (Connections):** Technical dependency edges between components. Drawn as colored directional arrows (distinct color per link type: `imports`, `calls_api`, `depends_on`, `shares_db`).
|
||||
- **Layer 4 (Artifacts):** Small attachment badges on nodes that have artifacts. Clicking a badge opens the artifact list in the detail panel.
|
||||
|
||||
## View 1: Layered Overview
|
||||
## View 1: Layered Overview (post-alpha)
|
||||
|
||||
**Purpose:** See the entire project structure at a glance, organized by abstraction level.
|
||||
|
||||
> **Alpha replacement:** A collapsible tree sidebar provides basic structural navigation. The full graph visualization below is introduced post-alpha.
|
||||
|
||||
**Layout:** Rows arranged by depth in the decomposition tree. Each row represents one abstraction layer.
|
||||
|
||||
```
|
||||
@ -73,9 +77,9 @@ Layer 3: [OAuth flow] [Bar chart component]
|
||||
- **Filtering:** Filter by label, status, assignee. Non-matching nodes dimmed, not hidden (preserving structural context). Filters interact with layer toggles — filtering by status only affects Layer 2 nodes.
|
||||
- **Node coloring:** Status-based by default (Layer 2). In Architecture preset (Layer 3 active, Layer 2 off), components colored by dependency fan-out (how many things depend on them).
|
||||
|
||||
## View 2: Focus Widget
|
||||
## View 2: Focus Widget (alpha)
|
||||
|
||||
**Purpose:** Inspect a single node and its immediate context.
|
||||
**Purpose:** Inspect a single node and its immediate context. Ships in alpha as the primary daily-use view.
|
||||
|
||||
**Layout:** Selected node in center. Parent shown above. Children shown below. Lateral links shown as badges or side panel.
|
||||
|
||||
@ -84,14 +88,14 @@ Layer 3: [OAuth flow] [Bar chart component]
|
||||
- **Breadcrumb navigation:** Full root→node path as clickable segments at the top (e.g., `Project > Backend > Auth > Login Flow > Password Reset`).
|
||||
- **Navigation:** Click any node to make it the new focus ("walking the tree").
|
||||
- **Detail panel:** Full description, comments, change history timeline (compact, filterable by event type).
|
||||
- **Backlinks section:** Inbound lateral links grouped by layer and type. Layer 2 links (blocks, duplicates) and Layer 3 links (depends_on, imports) are shown in separate collapsible groups.
|
||||
- **Artifacts section:** When Layer 4 is active, a dedicated panel lists attached artifacts — thumbnails for images, icons for document links, download buttons for files.
|
||||
- **Code connections section:** When Layer 3 is active, shows inbound/outbound technical dependencies for the focused component with link type and target component name.
|
||||
- **Backlinks section:** Inbound lateral links grouped by type. In alpha: `blocks` and `relates_to` links only. Post-alpha: Layer 2 links (blocks, duplicates) and Layer 3 links (depends_on, imports) shown in separate collapsible groups.
|
||||
- **Artifacts section (post-alpha):** When Layer 4 is active, a dedicated panel lists attached artifacts — thumbnails for images, icons for document links, download buttons for files.
|
||||
- **Code connections section (post-alpha):** When Layer 3 is active, shows inbound/outbound technical dependencies for the focused component with link type and target component name.
|
||||
- **Quick actions:** Change status, assign, add labels, add child, add link, attach artifact.
|
||||
|
||||
## View 3: Flat List / Board (Fallback)
|
||||
## View 3: Flat List / Board (alpha)
|
||||
|
||||
**Purpose:** Quick triage, standup-style review, batch operations.
|
||||
**Purpose:** Quick triage, standup-style review, batch operations. Ships in alpha.
|
||||
|
||||
**Layout:** Standard list or Kanban board (columns = statuses).
|
||||
|
||||
@ -100,9 +104,9 @@ Layer 3: [OAuth flow] [Bar chart component]
|
||||
- **Bulk actions:** Multi-select for status change, assign, add labels.
|
||||
- **Search:** Full-text search across titles and descriptions.
|
||||
|
||||
## View 4: Cycle View
|
||||
## View 4: Cycle View (post-alpha)
|
||||
|
||||
**Purpose:** See current sprint/cycle work across all subtrees.
|
||||
**Purpose:** See current sprint/cycle work across all subtrees. Introduced post-alpha alongside cycles.
|
||||
|
||||
**Layout:** Flat list of current cycle members, grouped by subtree or status.
|
||||
|
||||
@ -127,7 +131,7 @@ Comments use **GitHub-style markdown** with extensions for project references:
|
||||
|
||||
Markdown is sanitized server-side before storage to prevent XSS (see Security in [09-TECH-STACK-AND-ARCHITECTURE.md](09-TECH-STACK-AND-ARCHITECTURE.md)).
|
||||
|
||||
### Reactions
|
||||
### Reactions (post-alpha)
|
||||
|
||||
Emoji reactions on comments — lightweight feedback without noise. Standard set (thumbs up/down, eyes, rocket, heart, etc.) plus custom emoji support deferred.
|
||||
|
||||
@ -154,7 +158,9 @@ The primary navigation and action method:
|
||||
- Context-aware: shows different actions depending on current view and selection
|
||||
- Unified entry point for commands ("change status") and search results ("issues matching 'stripe'")
|
||||
|
||||
### Natural Language Node Creation (from Todoist)
|
||||
### Natural Language Node Creation (post-alpha, from Todoist)
|
||||
|
||||
> **Alpha:** Manual node creation via command palette fields. Natural language parsing is introduced post-alpha.
|
||||
|
||||
Type in the command palette: "Add a bug under Auth > Login flow: password reset emails aren't sending, p0, assign to agent-1"
|
||||
|
||||
@ -163,7 +169,9 @@ Type in the command palette: "Add a bug under Auth > Login flow: password reset
|
||||
- Falls back to inbox if path can't be resolved
|
||||
- Agent can use same syntax via API
|
||||
|
||||
### Plan-Then-Apply
|
||||
### Plan-Then-Apply (post-alpha)
|
||||
|
||||
> **Alpha:** Structural changes show a simple confirmation dialog. Full preview system is introduced post-alpha.
|
||||
|
||||
Structural changes show a preview before committing:
|
||||
|
||||
@ -176,7 +184,9 @@ Structural changes show a preview before committing:
|
||||
|
||||
Users can switch between views freely. The selected node context is preserved — if you're focused on "Login" in the Focus Widget and switch to Layered Overview, "Login" is highlighted/centered.
|
||||
|
||||
## Notifications (Scoped Watching)
|
||||
## Notifications (post-alpha, Scoped Watching)
|
||||
|
||||
> **Alpha:** In-app real-time updates via Centrifugo only. The full notification system (watch scoping, delivery channels, email digests) is introduced post-alpha.
|
||||
|
||||
### Watch Scoping
|
||||
|
||||
|
||||
@ -4,7 +4,9 @@
|
||||
|
||||
Non-Linear uses a granular, policy-based permission system inspired by AWS S3/IAM. The system is built on fine-grained policies from day one. Roles are named bundles of policies — convenience layers, not hardcoded ceilings.
|
||||
|
||||
## Core Concepts
|
||||
> **Alpha ships with three hardcoded roles only:** Owner (all actions), Member (all except delete/manage), Agent (read + comment + change status + triage). The full policy engine described below — custom roles, subtree scoping, per-node policies, resolution order — is introduced post-alpha. The thesis being validated in alpha is "graph structure helps," not "granular permissions work." See [06a-ALPHA-SCOPE.md](06a-ALPHA-SCOPE.md).
|
||||
|
||||
## Core Concepts (post-alpha — full policy engine)
|
||||
|
||||
### Policy
|
||||
|
||||
|
||||
@ -34,7 +34,9 @@ The agent helps human users by analyzing the graph and suggesting actions.
|
||||
|
||||
Governed by the same policy engine as human users. Agents authenticate with API tokens tied to their actor account.
|
||||
|
||||
### Layer Filtering
|
||||
### Layer Filtering (post-alpha)
|
||||
|
||||
> **Alpha:** No layer filtering. All read endpoints return structure + work data (the only data that exists in alpha). The `layers` query parameter is introduced post-alpha when Layers 3 and 4 are available.
|
||||
|
||||
All read endpoints accept an optional `layers` query parameter that controls which data layers are included in the response. This mirrors the UI layer toggles and lets agents scope their view to only the information they need.
|
||||
|
||||
@ -89,7 +91,9 @@ PATCH /api/v1/nodes/{id}/status # Change status
|
||||
PATCH /api/v1/nodes/{id}/parent # Triage: assign parent to inbox item
|
||||
```
|
||||
|
||||
### Write Actions (v0.1 — Layer 4)
|
||||
### Write Actions (v0.1 — Layer 4, post-alpha)
|
||||
|
||||
> **Alpha:** No artifact endpoints. Introduced post-alpha with Layer 4.
|
||||
|
||||
```
|
||||
POST /api/v1/nodes/{id}/artifacts # Attach an artifact (link or file)
|
||||
@ -113,7 +117,9 @@ POST /api/v1/nodes/{id}/connections # Declare a code connection (Layer 3,
|
||||
- The actor has roles/policies assigned via the policy engine
|
||||
- Token scoping: a token can optionally be restricted to a subset of the agent's permissions
|
||||
|
||||
### Pagination
|
||||
### Pagination (post-alpha)
|
||||
|
||||
> **Alpha:** No pagination. Graphs will be small (<500 nodes). All list endpoints return full results. Pagination is introduced post-alpha when projects grow beyond alpha scale.
|
||||
|
||||
All list endpoints use **cursor-based pagination**. Responses include a cursor for the next page and a flag indicating whether more results exist.
|
||||
|
||||
@ -222,7 +228,7 @@ Loop:
|
||||
4. Post comment with rationale
|
||||
```
|
||||
|
||||
### Impact Analysis Agent
|
||||
### Impact Analysis Agent (post-alpha, requires Layer 3)
|
||||
|
||||
```
|
||||
Uses layers: structure + connections (Layer 1 + Layer 3)
|
||||
@ -283,9 +289,9 @@ POST /api/v1/projects/{id}/webhooks
|
||||
| `node.reparented` | 1/2 | Node moved to a different parent |
|
||||
| `node.cycle_added` | 2 | Issue added to a cycle |
|
||||
| `node.deleted` | 1/2 | Node (and subtree) deleted |
|
||||
| `artifact.attached` | 4 | Artifact attached to a node |
|
||||
| `artifact.removed` | 4 | Artifact removed from a node |
|
||||
| `connection.inferred` | 3 | Code connection auto-detected from repo analysis |
|
||||
| `artifact.attached` | 4 | Artifact attached to a node — POST-ALPHA |
|
||||
| `artifact.removed` | 4 | Artifact removed from a node — POST-ALPHA |
|
||||
| `connection.inferred` | 3 | Code connection auto-detected from repo analysis — POST-ALPHA |
|
||||
| `repo.commit_associated` | 1 | Commit auto-associated with a component |
|
||||
|
||||
Webhook subscriptions can filter by layer: `"events": ["layer:3"]` subscribes to all Layer 3 events only.
|
||||
@ -315,7 +321,9 @@ All webhook payloads share a common envelope:
|
||||
|
||||
The `data` field varies by event type. Each event includes the affected node's `node_id` and `short_id` at minimum.
|
||||
|
||||
### Signature Verification
|
||||
### Signature Verification (post-alpha)
|
||||
|
||||
> **Alpha:** No HMAC signatures on webhook payloads. Single delivery attempt, failures logged. Signature verification and retry logic are introduced post-alpha.
|
||||
|
||||
Every webhook request includes an `X-NonLinear-Signature` header containing an HMAC-SHA256 hex digest of the raw request body, computed with the webhook's shared secret:
|
||||
|
||||
@ -325,7 +333,9 @@ X-NonLinear-Signature: sha256=a1b2c3d4e5f6...
|
||||
|
||||
Receivers should verify the signature before processing to confirm authenticity.
|
||||
|
||||
### Delivery & Retry
|
||||
### Delivery & Retry (post-alpha)
|
||||
|
||||
> **Alpha:** Single delivery attempt per event. Failures logged but not retried. The retry and auto-deactivation logic below is introduced post-alpha.
|
||||
|
||||
- Webhooks are delivered asynchronously via the Taskiq worker.
|
||||
- **Timeout:** 10 seconds per delivery attempt.
|
||||
|
||||
@ -1,22 +1,33 @@
|
||||
# Non-Linear: v0.1 Scope & Roadmap
|
||||
# Non-Linear: Scope & Roadmap
|
||||
|
||||
## v0.1 Validation Goal
|
||||
## Milestone Structure
|
||||
|
||||
| Milestone | Purpose |
|
||||
|-----------|---------|
|
||||
| **v0.1-alpha** | Minimum viable validation — see [06a-ALPHA-SCOPE.md](06a-ALPHA-SCOPE.md) |
|
||||
| **v0.1-full** | Complete v0.1 vision (this document) — ships after alpha validates the thesis |
|
||||
| **v0.2** | Expand agent capabilities + cross-project |
|
||||
| **v0.3+** | Integrations & intelligence |
|
||||
|
||||
## v0.1-full Validation Goal
|
||||
|
||||
> Can a team of 3-5 people use this to run an actual project for two weeks without falling back to another tool?
|
||||
|
||||
If yes, the core thesis holds. If they keep opening Linear or a spreadsheet for certain tasks, those gaps tell us what v0.2 needs.
|
||||
|
||||
## v0.1 Scope: What Ships
|
||||
## v0.1-full Scope: What Ships (after alpha validates)
|
||||
|
||||
### Core Data Model
|
||||
|
||||
- **Two node types:** components (skeleton, map to code) and issues (work, flow through statuses)
|
||||
- **Two node types (alpha):** components (skeleton, map to code) and issues (work, flow through statuses). Artifacts (Layer 4) are introduced post-alpha.
|
||||
- **Decomposition tree:** strict parent→child hierarchy, single root per project
|
||||
- **Lateral links:** blocks, blocked_by, relates_to, duplicates, depends_on (inter-component)
|
||||
- **Component health:** derived from children's statuses (no status field on components)
|
||||
- **Single project** (no cross-project features)
|
||||
- **Complete change history:** every mutation is a stored event with actor + timestamp
|
||||
|
||||
> **Alpha note:** Alpha ships `blocks` and `relates_to` only. `duplicates` and `depends_on` (Layer 3) are post-alpha.
|
||||
|
||||
### Repository Integration
|
||||
|
||||
- **Multi-repo support:** connect multiple GitHub/GitLab repos to one project
|
||||
|
||||
157
06a-ALPHA-SCOPE.md
Normal file
157
06a-ALPHA-SCOPE.md
Normal file
@ -0,0 +1,157 @@
|
||||
# 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
|
||||
@ -13,7 +13,7 @@
|
||||
│ State: Pinia │ HTTP: ofetch │ WS: centrifuge-js │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ CROSS-PLATFORM │
|
||||
│ Desktop: Tauri (thin wrapper, no offline) — v0.1 │
|
||||
│ Desktop: Tauri (thin wrapper, no offline) — post-alpha │
|
||||
│ Mobile: Capacitor (responsive web first) — v0.2+ │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ BACKEND │
|
||||
@ -25,8 +25,8 @@
|
||||
│ Postgres — content & metadata (rich text, comments, │
|
||||
│ attachments meta, audit logs, project cfg) │
|
||||
│ Redis — caching, rate limiting │
|
||||
│ Meilisearch — full-text search (issues, comments) │
|
||||
│ MinIO — S3-compatible file storage (attachments) │
|
||||
│ Meilisearch — full-text search (post-alpha) │
|
||||
│ MinIO — S3-compatible file storage (post-alpha) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ REAL-TIME │
|
||||
│ Centrifugo — WebSocket server, live updates, push │
|
||||
@ -35,15 +35,18 @@
|
||||
│ Authentik — OIDC, API tokens, role mgmt, SSO-ready │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ INFRA/OPS │
|
||||
│ Caddy (reverse proxy + TLS) │ Vault (secrets) │
|
||||
│ Prometheus + Grafana (metrics + dashboards) │
|
||||
│ Loki (logs) │ Tempo (traces) │ OpenTelemetry (SDK) │
|
||||
│ Caddy (reverse proxy + TLS) │
|
||||
│ Vault (secrets) — post-alpha │
|
||||
│ Prometheus + Grafana — post-alpha │
|
||||
│ Loki + Tempo + OpenTelemetry — post-alpha │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ DEPLOYMENT │
|
||||
│ Docker Compose (dev + single-node production) │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
> **Alpha infrastructure:** Alpha ships with Neo4j, Postgres, Redis, Centrifugo, Caddy, Authentik, FastAPI, Taskiq worker, and Vue frontend (~10 containers). Meilisearch is replaced by Postgres `tsvector`. MinIO, Vault, and the observability stack (Prometheus/Grafana/Loki/Tempo) are introduced post-alpha. See [06a-ALPHA-SCOPE.md](06a-ALPHA-SCOPE.md) for the full alpha boundary.
|
||||
|
||||
## Data Boundary
|
||||
|
||||
### Neo4j — Graph Topology
|
||||
@ -84,14 +87,18 @@ Each edge type is scoped to a single layer, which enables efficient layer-filter
|
||||
- Rate limiting for agent API
|
||||
- Authentik token validation cache
|
||||
|
||||
### Meilisearch — Search Index
|
||||
### Meilisearch — Search Index (post-alpha)
|
||||
|
||||
> **Alpha:** Full-text search is handled by Postgres `tsvector` in alpha. Meilisearch is introduced post-alpha for typo-tolerant, prefix-aware search across large datasets.
|
||||
|
||||
- Indexes issue titles, descriptions, comments, labels
|
||||
- Fed from both Neo4j and Postgres
|
||||
- Powers command palette search (issues + commands in one result set)
|
||||
- Typo-tolerant, prefix search, filtering by label/status/assignee
|
||||
|
||||
### MinIO — File Storage
|
||||
### MinIO — File Storage (post-alpha)
|
||||
|
||||
> **Alpha:** No file uploads. Links in descriptions suffice for the 2-week validation. MinIO is introduced post-alpha alongside Artifacts (Layer 4).
|
||||
|
||||
- S3-compatible API, self-hosted
|
||||
- Stores attachment files (images, docs)
|
||||
@ -142,7 +149,7 @@ CREATE (i:Issue {
|
||||
updated_at: datetime()
|
||||
})
|
||||
|
||||
// Layer 4: Artifact node
|
||||
// Layer 4: Artifact node — POST-ALPHA
|
||||
CREATE (a:Artifact {
|
||||
id: "uuidv7",
|
||||
title: "Login flow mockup",
|
||||
@ -176,13 +183,13 @@ CREATE (p:Project {
|
||||
(issue)-[:RELATES_TO]->(issue)
|
||||
(issue)-[:DUPLICATES]->(issue)
|
||||
|
||||
// Layer 3: Code connection links (between components)
|
||||
// Layer 3: Code connection links (between components) — POST-ALPHA
|
||||
(component)-[:DEPENDS_ON {source: "manual"}]->(component)
|
||||
(component)-[:IMPORTS {source: "inferred"}]->(component)
|
||||
(component)-[:CALLS_API {source: "inferred"}]->(component)
|
||||
(component)-[:SHARES_DB {source: "manual"}]->(component)
|
||||
|
||||
// Layer 4: Artifact attachments
|
||||
// Layer 4: Artifact attachments — POST-ALPHA
|
||||
(component)-[:HAS_ARTIFACT]->(artifact)
|
||||
(issue)-[:HAS_ARTIFACT]->(artifact)
|
||||
|
||||
@ -245,7 +252,8 @@ class Attachment(SQLModel, table=True):
|
||||
|
||||
class ArtifactContent(SQLModel, table=True):
|
||||
"""Layer 4: external context attached to a component or issue.
|
||||
Topology (HAS_ARTIFACT edge) lives in Neo4j; rich metadata lives here."""
|
||||
Topology (HAS_ARTIFACT edge) lives in Neo4j; rich metadata lives here.
|
||||
POST-ALPHA: introduced alongside Artifact nodes and MinIO."""
|
||||
id: uuid.UUID = Field(primary_key=True) # matches Neo4j Artifact node id
|
||||
title: str
|
||||
kind: str # "link" | "file" | "embed"
|
||||
@ -371,9 +379,9 @@ non-linear-api/
|
||||
│ │ ├── models.py # SQLAlchemy/SQLModel models
|
||||
│ │ ├── descriptions.py # Rich text CRUD
|
||||
│ │ ├── comments.py # Comment thread CRUD
|
||||
│ │ ├── attachments.py # Inline attachment metadata + MinIO upload/download
|
||||
│ │ └── artifacts.py # Layer 4: artifact CRUD (links, files, embeds)
|
||||
│ ├── connections/ # Layer 3: code connection analysis
|
||||
│ │ ├── attachments.py # Inline attachment metadata + MinIO upload/download — POST-ALPHA
|
||||
│ │ └── artifacts.py # Layer 4: artifact CRUD (links, files, embeds) — POST-ALPHA
|
||||
│ ├── connections/ # Layer 3: code connection analysis — POST-ALPHA
|
||||
│ │ ├── inference.py # Auto-infer dependencies from repo analysis
|
||||
│ │ └── manual.py # Manual code connection CRUD
|
||||
│ ├── search/ # Meilisearch integration
|
||||
@ -386,15 +394,15 @@ non-linear-api/
|
||||
│ │ ├── webhooks.py # Deliver webhooks to agent endpoints
|
||||
│ │ ├── indexing.py # Async search index updates
|
||||
│ │ ├── notifications.py # Notification delivery
|
||||
│ │ └── connections.py # Layer 3: periodic code connection inference
|
||||
│ │ └── connections.py # Layer 3: periodic code connection inference — POST-ALPHA
|
||||
│ └── api/v1/ # Route handlers
|
||||
│ ├── nodes.py # CRUD + tree operations
|
||||
│ ├── links.py # Lateral link management (Layer 2 + Layer 3)
|
||||
│ ├── projects.py # Project CRUD
|
||||
│ ├── comments.py # Comment endpoints
|
||||
│ ├── attachments.py # Inline upload/download
|
||||
│ ├── artifacts.py # Layer 4: artifact endpoints
|
||||
│ ├── connections.py # Layer 3: code connection endpoints
|
||||
│ ├── artifacts.py # Layer 4: artifact endpoints — POST-ALPHA
|
||||
│ ├── connections.py # Layer 3: code connection endpoints — POST-ALPHA
|
||||
│ ├── search.py # Search endpoint
|
||||
│ └── agent.py # Agent-specific API surface
|
||||
├── tests/
|
||||
@ -566,7 +574,25 @@ The backend publishes to Centrifugo via its HTTP server API (not through Redis p
|
||||
|
||||
## Docker Compose
|
||||
|
||||
### Development
|
||||
### Alpha (~10 containers)
|
||||
|
||||
```yaml
|
||||
services:
|
||||
api: # FastAPI (uvicorn)
|
||||
frontend: # Vue 3 (Vite)
|
||||
worker: # Taskiq worker (same codebase as api)
|
||||
neo4j: # Graph database
|
||||
postgres: # Relational database
|
||||
redis: # Cache + rate limiting
|
||||
centrifugo: # Real-time WebSocket server
|
||||
caddy: # Reverse proxy + automatic TLS
|
||||
authentik: # Identity provider (server + worker)
|
||||
authentik-db: # Authentik's own Postgres
|
||||
```
|
||||
|
||||
~10 containers. Runs comfortably on 16GB RAM. Search via Postgres `tsvector`.
|
||||
|
||||
### Development (v0.1-full)
|
||||
|
||||
```yaml
|
||||
services:
|
||||
@ -579,13 +605,14 @@ services:
|
||||
meilisearch: # Search engine
|
||||
minio: # Object storage
|
||||
centrifugo: # Real-time WebSocket server
|
||||
caddy: # Reverse proxy + automatic TLS
|
||||
authentik: # Identity provider (server + worker)
|
||||
authentik-db: # Authentik's own Postgres
|
||||
```
|
||||
|
||||
~12 containers. Runs comfortably on 16GB RAM.
|
||||
~13 containers. Runs comfortably on 16GB RAM.
|
||||
|
||||
### Production (Single-Node)
|
||||
### Production (Single-Node, v0.1-full)
|
||||
|
||||
Same Docker Compose topology with production-grade additions:
|
||||
|
||||
@ -613,7 +640,9 @@ Caddy serves as the single entry point for all traffic:
|
||||
|
||||
## Secrets Management
|
||||
|
||||
### HashiCorp Vault (Primary)
|
||||
> **Alpha:** Docker secrets or environment variables. Vault is introduced post-alpha.
|
||||
|
||||
### HashiCorp Vault (post-alpha)
|
||||
|
||||
- All sensitive configuration (database passwords, Authentik client secrets, agent API token signing keys, webhook HMAC secrets, MinIO credentials) stored in Vault.
|
||||
- FastAPI reads secrets from Vault at startup via the `hvac` Python client.
|
||||
@ -623,7 +652,9 @@ Caddy serves as the single entry point for all traffic:
|
||||
|
||||
For simpler deployments that don't want Vault overhead, Docker secrets via compose files are supported. Environment variables as the last resort.
|
||||
|
||||
## Observability
|
||||
## Observability (post-alpha)
|
||||
|
||||
> **Alpha:** Structured JSON logs via `structlog` + `docker logs`. The full observability stack below is introduced post-alpha.
|
||||
|
||||
### Metrics (Prometheus + Grafana)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user