# Non-Linear: Data Model

## Overview

The data model consists of two overlaid graphs on the same set of 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.

## Issue Node (Atomic Unit)

Every node in the graph is an **issue**. Issues are intentionally untyped — their depth in the decomposition tree implies their abstraction level.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique identifier |
| `title` | string | Short descriptive title |
| `description` | text | Detailed description (markdown) |
| `status` | enum | Current state (see Status below) |
| `labels` | string[] | Freeform tags for orthogonal concerns |
| `assignee` | actor_id? | User or agent assigned |
| `parent_id` | issue_id? | Parent in decomposition tree (null = root) |
| `created_at` | timestamp | Creation time |
| `updated_at` | timestamp | Last modification |
| `created_by` | actor_id | Creator (user or agent) |

### Status

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

### Labels

Labels handle all classification orthogonal to hierarchy:

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

### Why Untyped

Traditional trackers have explicit types: Epic, Story, Task, Subtask, Bug. This creates rigidity — teams argue about what level something belongs at, and refactoring the hierarchy means changing types.

In Non-Linear, depth *is* type:

```
Root (depth 0)          → "project level"
├── Child (depth 1)     → "component/epic level"
│   ├── Child (depth 2) → "feature/story level"
│   │   └── Child (depth 3) → "task level"
```

A node's abstraction level is determined by its position, not a type field. Moving a node to a different depth changes its conceptual level automatically.

## Decomposition Tree

The decomposition tree is a strict hierarchy with these properties:

- **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)

### Reparenting

Moving a node to a different parent is a **structural change**. It affects:

- The node's implied abstraction level
- Agent permissions (if scoped to a subtree)
- The layered view layout
- Who can access the node (if resource-scoped policies apply)

The system should warn when reparenting changes permission boundaries.

## Association Graph (Lateral Links)

Lateral links are typed, many-to-many relationships that don't affect hierarchy.

### Link Types

| Type | Semantics | Directionality |
|------|-----------|----------------|
| `blocks` | A blocks B (B can't proceed until A is done) | Directed |
| `blocked_by` | Inverse of blocks | Directed (auto-created) |
| `relates_to` | General association | Undirected |
| `duplicates` | A is a duplicate of B | Directed |

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

In future versions, lateral links can cross project boundaries. This enables:

- Freelancer's client project depending on a shared library
- Shared infrastructure components blocking multiple projects
- Cross-team dependency tracking

Cross-project links add complexity to permissions (an agent scoped to Project A sees a link to Project B but may not access the target) and are deferred to v0.2.

### Link vs. Parent Relationship

| Property | Parent→Child | Lateral Link |
|----------|-------------|--------------|
| Cardinality | One parent per node | Many-to-many |
| Affects hierarchy | Yes | No |
| Affects layered view | Yes | Shown as overlay edges |
| Affects permissions | Yes (subtree scoping) | No |
| Removal impact | Structural (node needs new parent) | Annotation only |

## Project (v0.1)

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique identifier |
| `name` | string | Project name |
| `root_id` | issue_id | Root node of decomposition tree |
| `created_at` | timestamp | Creation time |
| `members` | actor_id[] | Users and agents with access |

In v0.1, each project has exactly one root node and one decomposition tree. Multi-root or cross-project features are deferred.