170 lines
7.6 KiB
Markdown
170 lines
7.6 KiB
Markdown
# Non-Linear: Views & UI
|
|
|
|
## Overview
|
|
|
|
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.
|
|
|
|
## View 1: Layered Overview
|
|
|
|
**Purpose:** See the entire project structure at a glance, organized by abstraction level.
|
|
|
|
**Layout:** Rows arranged by depth in the decomposition tree. Each row represents one abstraction layer.
|
|
|
|
```
|
|
Layer 0 (root): [My SaaS Project]
|
|
/ | \
|
|
Layer 1: [Auth] [Billing] [Dashboard]
|
|
/ \ | / \
|
|
Layer 2: [Login] [SSO] [Stripe] [Charts] [Filters]
|
|
| |
|
|
Layer 3: [OAuth flow] [Bar chart component]
|
|
```
|
|
|
|
### Behavior
|
|
|
|
- **Edges visible:** Parent→child edges drawn between layers. Lateral links shown as overlay edges (dashed, colored by type).
|
|
- **Backlink count badges:** Nodes show inbound link counts ("3 blocked").
|
|
- **Cycle highlighting:** Cycle members highlighted with color/tag.
|
|
- **Collapse/expand:** Each node can collapse its subtree.
|
|
- **Zoom:** At high zoom, nodes show only title. At lower zoom, nodes show title + status + assignee.
|
|
- **Filtering:** Filter by label, status, assignee. Non-matching nodes dimmed, not hidden (preserving structural context).
|
|
- **Node coloring:** Status-based by default. Optionally by label, assignee, or priority.
|
|
|
|
## View 2: Focus Widget
|
|
|
|
**Purpose:** Inspect a single node and its immediate context.
|
|
|
|
**Layout:** Selected node in center. Parent shown above. Children shown below. Lateral links shown as badges or side panel.
|
|
|
|
### Behavior
|
|
|
|
- **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 type.
|
|
- **Quick actions:** Change status, assign, add labels, add child, add link.
|
|
|
|
## View 3: Flat List / Board (Fallback)
|
|
|
|
**Purpose:** Quick triage, standup-style review, batch operations.
|
|
|
|
**Layout:** Standard list or Kanban board (columns = statuses).
|
|
|
|
- **Sorting:** By status, priority, assignee, updated date, creation date.
|
|
- **Grouping:** By parent node, label, assignee.
|
|
- **Bulk actions:** Multi-select for status change, assign, add labels.
|
|
- **Search:** Full-text search across titles and descriptions.
|
|
|
|
## View 4: Cycle View
|
|
|
|
**Purpose:** See current sprint/cycle work across all subtrees.
|
|
|
|
**Layout:** Flat list of current cycle members, grouped by subtree or status.
|
|
|
|
## Comments & Collaboration
|
|
|
|
### Threading Model
|
|
|
|
Comments are **flat and parented by nodes** — not nested under other comments. Each node has a single comment stream displayed in chronological order. This keeps the model simple and avoids deeply nested threads that become hard to follow.
|
|
|
|
Multiple node comment streams can be merged into a single chronological view (e.g., "show all comments across this subtree") for standup-style review.
|
|
|
|
### Markdown & Rich References
|
|
|
|
Comments use **GitHub-style markdown** with extensions for project references:
|
|
|
|
- `@alice`, `@agent-1` — mention a user or agent (triggers notification)
|
|
- `#NL-42` — link to an issue node
|
|
- `#NL-C12` — link to a component node
|
|
- `!123` — link to a merge request / pull request
|
|
- Bare commit SHAs (7+ chars) — auto-linked to the relevant repo
|
|
- Standard markdown: headings, lists, code blocks, inline code, bold/italic, images, links
|
|
|
|
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
|
|
|
|
Emoji reactions on comments — lightweight feedback without noise. Standard set (thumbs up/down, eyes, rocket, heart, etc.) plus custom emoji support deferred.
|
|
|
|
### Agent Comments
|
|
|
|
Agents post comments via the same API as humans. For structured output (test results, decomposition proposals, status reports), agents use markdown code blocks or tables within the comment body. No separate "bot message" type — agents are first-class actors in the comment stream, distinguished by their actor identity in the UI.
|
|
|
|
## Interaction Model
|
|
|
|
### Keyboard-First
|
|
|
|
Every action has a keyboard shortcut. Graph navigation:
|
|
|
|
- `Alt+↑` — navigate to parent
|
|
- `Alt+↓` — navigate to children
|
|
- `Alt+←/→` — navigate siblings
|
|
- Follow lateral links via shortcut
|
|
|
|
### Command Palette (`Cmd+K`)
|
|
|
|
The primary navigation and action method:
|
|
|
|
- Fuzzy search across all nodes, actions, views
|
|
- 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)
|
|
|
|
Type in the command palette: "Add a bug under Auth > Login flow: password reset emails aren't sending, p0, assign to agent-1"
|
|
|
|
- Parses tree path via `>`, labels via `#` or keywords (`p0`, `bug`), assignment via `@`
|
|
- Fuzzy-matches node names in the path
|
|
- Falls back to inbox if path can't be resolved
|
|
- Agent can use same syntax via API
|
|
|
|
### Plan-Then-Apply
|
|
|
|
Structural changes show a preview before committing:
|
|
|
|
- **Reparent preview:** "Moving 'Auth' under 'Infrastructure' will: change depth from 1→2, move 12 child nodes, agent-1 will lose access (scoped to 'Backend' subtree)"
|
|
- **Bulk operations:** "Changing status of 8 nodes to 'done' — 3 have open blockers"
|
|
- **Delete preview:** "Deleting 'Legacy API' will remove 1 node + 7 children, break 3 lateral links"
|
|
- **Agent proposals:** agent submits a "plan" (e.g., proposed decomposition), human reviews diff-style and approves
|
|
|
|
## View Switching
|
|
|
|
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)
|
|
|
|
### Watch Scoping
|
|
|
|
- **Watch granularity:** single node, subtree, or project-wide
|
|
- **Event type filters:** status changes, comments, new children, link changes, agent actions
|
|
- **Defaults:** watch nodes you created or are assigned to
|
|
- **Mute:** temporarily silence a noisy subtree
|
|
- **Agent filter:** "only notify me when agent-1 changes something"
|
|
|
|
### Delivery Channels
|
|
|
|
Notifications are delivered through three channels, configurable per user:
|
|
|
|
1. **In-app real-time (Centrifugo).** Connected clients receive instant push via Centrifugo WebSocket channels. Notifications appear in an in-app notification center (badge count + dropdown). This is the primary channel.
|
|
2. **Push notifications.** Web Push API for browser notifications when the tab is backgrounded. Tauri desktop uses native OS notifications via the Tauri notification plugin.
|
|
3. **Email.** For offline/away users. Two modes per user preference:
|
|
- **Immediate:** one email per event (for high-priority watches only)
|
|
- **Digest:** batched summary (hourly or daily, configurable)
|
|
|
|
Delivery is handled by the `tasks/notifications.py` Taskiq worker. The worker reads the user's watch configuration + delivery preferences, then fans out to the appropriate channels.
|
|
|
|
## Entry Experience
|
|
|
|
### New Project (Clean Start)
|
|
|
|
1. User creates a project → automatically creates root node with project name
|
|
2. User placed in Focus Widget on root node
|
|
3. Prompt to add first children (components/areas)
|
|
4. Command palette available immediately for keyboard-driven creation
|
|
|
|
### Import (v0.2+)
|
|
|
|
- Import from Linear, Jira, GitHub Issues
|
|
- System infers hierarchy from existing relationships
|
|
- User reviews and adjusts inferred tree before confirming
|