# Non-Linear: Data Model

## Overview

The data model consists of two overlaid graphs on a set of **typed nodes**:

1. **Decomposition Tree** — strict parent→child hierarchy (DAG)
2. **Association Graph** — lateral many-to-many connections with typed edges

These are deliberately separated. The decomposition tree is the *spine* of the product. The association graph is an *overlay* that adds context without defining structure.

## Node Types

The graph has two main node types: **components** and **issues**. Components form the skeleton; issues are work attached to that skeleton.

### Component Node

A component represents a structural part of the system — a service, a module, a package, a directory. Components are relatively stable and map to code structure.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique identifier |
| `short_id` | string | Human-readable ID (`NL-C12`) |
| `type` | enum | Always `component` |
| `title` | string | Component name |
| `description` | text | What this component does (markdown), stored in Postgres |
| `labels` | string[] | Freeform tags (`frontend`, `backend`, `infra`) |
| `owner` | actor_id? | Team or person responsible |
| `parent_id` | node_id? | Parent in decomposition tree |
| `repo_link` | repo_ref? | Linked repository or directory (see Repo Integration) |
| `created_at` | timestamp | Creation time |
| `updated_at` | timestamp | Last modification |

Components can be parents of other components (nesting: service → module → submodule) or parents of issues.

### Issue Node

An issue represents work to be done — a task, bug, feature, spike. Issues attach to components (or to the project root, or live in the inbox).

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique identifier |
| `short_id` | string | Human-readable ID (`NL-42`) |
| `type` | enum | Always `issue` |
| `title` | string | Short descriptive title |
| `description` | text | Detailed description (markdown), stored in Postgres |
| `status` | enum | Current state (see Status below) |
| `labels` | string[] | Freeform tags for orthogonal concerns |
| `assignee` | actor_id? | User or agent assigned |
| `parent_id` | node_id? | Parent in decomposition tree (null = inbox item) |
| `created_at` | timestamp | Creation time |
| `updated_at` | timestamp | Last modification |
| `created_by` | actor_id | Creator (user or agent) |
| `cycle_id` | cycle_id? | Current cycle membership |

### How They Relate

```
Project (root)
├── Component: auth-service          (→ repo: github.com/team/auth)
│   ├── Component: oauth-module      (→ directory: /src/oauth)
│   │   ├── Issue: implement refresh tokens
│   │   └── Issue: fix token expiry bug
│   └── Component: session-manager   (→ directory: /src/sessions)
│       └── Issue: add Redis session store
├── Component: frontend-app          (→ repo: github.com/team/web)
│   ├── Component: dashboard         (→ directory: /src/views/dashboard)
│   └── Component: auth-ui           (→ directory: /src/views/auth)
│       └── Issue: redesign login page
```

Components are the **skeleton** — stable structure that mirrors your codebase. Issues are the **work** — they flow through statuses, get assigned, join cycles. This separation is cleaner than depth-as-type because a component at depth 3 is still a component, not a "task."

### Hierarchy Rules

- Components can be children of: project root, other components
- Issues can be children of: project root, components, other issues (sub-tasks)
- Issues cannot be parents of components
- The tree remains a strict DAG — no cycles, single parent per node

### Status (Issues Only)

Default statuses (customizable per project):

- `backlog` — not yet planned
- `todo` — planned, not started
- `in_progress` — actively being worked on
- `in_review` — awaiting review
- `done` — completed
- `cancelled` — abandoned

Components don't have status — their "health" is derived from their children's statuses (e.g., "3/7 issues done, 1 blocked").

### Status Transitions (v0.1 Default)

v0.1 ships with a **permissive default model** — any status can transition to any other status. This avoids blocking agents or humans with rigid workflows before real usage patterns emerge.

```
backlog ⇄ todo ⇄ in_progress ⇄ in_review ⇄ done
   ↕        ↕         ↕             ↕          ↕
                    cancelled
```

All transitions are bidirectional. Reopening (`done` → `in_progress`) and skipping stages (`backlog` → `done`) are allowed. The system logs every transition with actor + timestamp for auditability.

**v0.2: Custom Transition Graphs.** Projects will be able to define a custom state machine that restricts allowed transitions (e.g., "only owners can reopen `done` issues," "`in_review` can only move to `done` or `in_progress`"). The default permissive model remains available as a preset.

### Labels

Labels handle all classification orthogonal to hierarchy and type:

- **Kind (issues):** `bug`, `feature`, `chore`, `spike`
- **Area:** `frontend`, `backend`, `infra`, `docs`
- **Priority:** `p0`, `p1`, `p2`, `p3`
- **Custom:** anything the team defines

## Repository Integration

### Repo Link

A component can be linked to a code source:

| Field | Type | Description |
|-------|------|-------------|
| `provider` | enum | `github`, `gitlab`, `bitbucket` |
| `repo_url` | string | Repository URL |
| `path` | string? | Subdirectory within repo (null = repo root) |
| `branch` | string? | Default branch to track (null = repo default) |

### Multi-Repo Support

A project can span multiple repositories. Each repo (or subdirectory) maps to a component node:

- **Monorepo:** one repo → multiple component nodes (one per package/service)
- **Multi-repo microservices:** each repo → one top-level component node
- **Mixed:** some repos map to a single component, others are split

### Skeleton Inference (Fast-Start)

When connecting repositories, the system proposes a component tree:

1. **Connect:** OAuth via Authentik to GitHub/GitLab
2. **Select repos:** pick which repositories belong to this project
3. **Scan:** system reads repo structure — directories, package manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`), major module boundaries
4. **Propose:** AI suggests a component tree: "I see 3 services with these modules — here's a proposed skeleton"
5. **Adjust:** user reviews, merges, splits, renames, rearranges
6. **Create:** skeleton is committed — user starts attaching issues

### Code ↔ Component Mapping

Because components are linked to repos/directories:

- **Commits** touching files in a component's path are automatically associated with that component
- **PRs** surfaced in the right component's activity feed without manual `NL-42` tagging (explicit tagging still works for issue-level linking)
- **New files/directories** can trigger suggestions: "A new directory `/src/notifications` appeared — add as a component?"
- **Agent context:** agent scoped to a component subtree can reference the actual code structure

## Decomposition Tree

The decomposition tree is a strict hierarchy:

- **Single parent:** Every node has exactly one parent (except roots)
- **Directed:** Edges flow from abstract (parent) to concrete (child)
- **Acyclic:** No node can be its own ancestor
- **Single root per project:** Each project has one root node (v0.1)
- **Typed:** Components form the skeleton, issues attach to it

### Reparenting

Moving a node to a different parent is a **structural change** (plan-then-apply):

- Permission boundaries may shift
- For components: repo link association persists, but position in tree changes
- For issues: moving between components changes which codebase the work is conceptually "in"
- System warns about consequences before committing

## Association Graph (Lateral Links)

### Link Types

| Type | Semantics | Directionality |
|------|-----------|----------------|
| `blocks` | A blocks B | Directed |
| `blocked_by` | Inverse of blocks | Directed (auto-created) |
| `relates_to` | General association | Undirected |
| `duplicates` | A is a duplicate of B | Directed |
| `depends_on` | Component A depends on component B | Directed |

`depends_on` is specifically for inter-component dependencies — can be inferred from code (import graphs, API calls) or declared manually.

### Backlinks (Inbound Link Surfacing)

Every node surfaces inbound lateral links: "3 tasks blocked by this," "2 components depend on this."

### Cross-Project Links (v0.2+)

Deferred. Will enable cross-project/cross-repo dependency tracking.

## Triage Inbox

Issues with `parent_id = null` live in the **rootless inbox**. With repo integration, triage becomes smarter — the system (or an agent) can suggest which component an inbox issue belongs to based on keywords, file paths, or related commits.

## Cycles

A cycle is a named set of issue references with a date range. Components don't join cycles — only issues do.

## Change History

Every mutation is a stored event with actor + timestamp. For components, this includes repo link changes and skeleton inference events.

## Workspace

A workspace is the top-level organizational container. It groups projects, users, and agents under a single identity boundary.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique identifier |
| `name` | string | Workspace name |
| `slug` | string | URL-safe identifier (`my-team`) |
| `projects` | project_id[] | Projects in this workspace |
| `members` | actor_id[] | Users and agents with workspace access |
| `created_at` | timestamp | Creation time |

- Users and agents belong to workspaces. A user can belong to multiple workspaces.
- Authentik maps to workspace-level identity — one Authentik group per workspace.
- Policies are per-project, but membership is per-workspace. A workspace member can be granted access to specific projects via project-level roles.
- Billing (if ever introduced) attaches to the workspace entity.
- v0.1 supports a single workspace per deployment. The entity exists from day one to avoid a painful migration later.

## Project

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique identifier |
| `name` | string | Project name |
| `workspace_id` | workspace_id | Parent workspace |
| `root_id` | node_id | Root node of decomposition tree |
| `repos` | repo_ref[] | Connected repositories |
| `created_at` | timestamp | Creation time |
| `members` | actor_id[] | Users and agents with project-level access |