tasks.paralla.org — Ground-Up Redesign: Design Document

Item	Detail
Owner	Metis (design) → Apollo (build)
Stack	Single-file Alpine.js + FastAPI (uvicorn), served at `tasks.paralla.org`
Status	Design complete; build backlog ready
Created	2026-06-23

1. Problem Statement

The existing tasks.paralla.org board is confusing — task-centric, flat list, no project context. pvs needs a control-room view where the primary unit of attention is the project, with clear visibility into who’s doing what and what’s next.

Core user question: “What is happening on each project right now?“

2. Non-Goals

Out of scope	Rationale
Auth / multi-user	Single user (pvs); keep current model
Mobile <640px	Control-room UI; warn banner, no optimisation
Charts / historical analytics	Future
Notifications / webpush	Future

3. Architecture

3.1 Stack Constraints

Single-file frontend — Alpine.js embedded in index.html (one file, inline CSS at top). Keeps the project deployable as a static site + API.
FastAPI backend — single-file Python server, wraps JSON on disk (projects.json). No database migration needed.
No schema change — new endpoints are additive; existing /api/tasks preserved for backward compat.

3.2 Routes

Route	View	Description
`#/`	Projects (default)	Grid of project cards with status, assignees, progress
`#/live`	Live Ops	Agent lanes + unified activity feed
`#/projects/:slug`	Project detail	Active task, backlog editor, activity history
`#/agents/:agent`	Agent profile	Projects owned, current task, history

3.3 API Endpoints (additions)

All mutations return the updated entity; client uses optimistic UI.

Method	Path	Purpose
GET	`/api/projects`	List projects (summary: assignees, progress, active_task_id)
GET	`/api/projects/:slug`	Project + todos + recent activity (composite)
POST	`/api/projects`	Create project {slug, name, summary}
PATCH	`/api/projects/:slug`	Rename / update summary
PATCH	`/api/projects/:slug/assignees`	Set assignees {agents: […]}
POST	`/api/projects/:slug/todos`	Append todo {text, owner, order?}
PATCH	`/api/projects/:slug/todos/:id`	Edit text / owner / status / order
DELETE	`/api/projects/:slug/todos/:id`	Remove todo
POST	`/api/projects/:slug/todos/reorder`	Bulk reorder [{id, order}] (atomic)
GET	`/api/agents`	Agent registry (id, name, colour, role)
GET	`/api/heartbeat`	{ts, agents:{state, current_task}} for “now” pulses
GET	`/api/activity?agent=&project=&limit=`	Activity stream (already exists; add project filter)

3.4 Data Model

File on disk: projects.json — array of project objects.

{
  "slug": "tasks-ui-rewrite",
  "name": "Tasks UI Rewrite v2",
  "summary": "Alpine.js + FastAPI single-file rewrite",
  "assignees": ["metis", "apollo"],
  "todos": [
    {
      "id": "t-001",
      "text": "Add design tokens block",
      "owner": "apollo",
      "status": "done|doing|todo",
      "order": 1,
      "created_at": "2026-06-23T10:45:00Z"
    }
  ],
  "activity": [
    {
      "agent": "apollo",
      "action": "completed",
      "target": "todo t-001",
      "project": "tasks-ui-rewrite",
      "ts": "2026-06-23T14:02:00Z"
    }
  ],
  "created_at": "2026-06-25T00:00:00Z"
}

4. Visual Design — Design Tokens

Source of truth in app/design-tokens.css (single :root block).

4.1 Colours

Neutrals (dark mission-control):

Token	Hex	Usage
`--bg-0`	0B0D10	App background
`--bg-1`	#111418	Card / panel
`--bg-2`	171B21	Raised / hover
`--line`	22272E	Hairline borders, dividers
`--text-1`	E6E8EB	Primary text
`--text-2`	9AA3AD	Secondary text
`--text-3`	5C6470	Tertiary / meta
`--accent`	7DD3FC	Focus rings, primary CTA

Agent colours:

Agent	Colour	Role	Semantics
metis	`#6366F1` (indigo)	Architect / design	Calm, strategic
apollo	`#10B981` (emerald)	Builder / implementation	Active, green-light
mercury	`#F59E0B` (amber)	Operator / infra	Warm, alert

Semantic: success=#10B981, warning=#F59E0B, danger=#EF4444, info=#7DD3FC.

4.2 Typography

Single font: Inter (system fallback). Mono: JetBrains Mono.

Scale	Size	Usage
display	1.75rem	Project name on detail header
h1	1.25rem	Page title
h2	1.00rem	Section header
body	0.875rem	Default
sm	0.8125rem	Dense rows
xs	0.75rem	Meta / timestamps

Weight: 500 headings, 400 body, 600 numerics & agent names. Tabular numerics for counts.

4.3 Spacing & Layout

Base unit 4px. Tokens: s1=4, s2=8, s3=12, s4=16, s6=24, s8=32, s12=48.

Breakpoints: sm≤640, md≤1024, lg≤1440, xl>1440. Desktop-first.

App shell: 56px topbar + 240px left rail (collapsible to 56px) + fluid main area.

5. Component Catalog

Component	Key Props / Style
Card	bg-1, radius 10px, padding s4. Hover: border → accent 40%, translateY -1px. Blocked: 2px left border danger.
AgentChip	Pill, h=22px, fill=agent-colour@18%, text=agent-colour@100%, 1px border agent-colour@35%. Leading dot solid.
AssigneeStack	Overlapping chips (-6px margin), max 3 visible + “+N” overflow in bg-2.
ProgressBar	Track bg-2, h=6px, radius 4px. Fill = gradient of assignee colours. Inline label “7 / 12”.
StatusDot	8px circle. Doing: agent-colour + pulse animation (1.6s). Todo/done: text-3 dot/ring. Blocked: danger.
TodoRow	36px tall, drag handle ⠿, status dot, editable owner chip, editable text, kebab ⋯ for delete/move-top. Done rows collapsed by default with expand checkbox.
SectionHeader	h2 left, count badge right (mono, bg-2). Sticky inside project detail scroll.
ActivityRow	28px, agent-colour 2px left bar, mono timestamp xs text-3, actor chip, verb, object link.
EmptyState	Single muted illustration + one-line + CTA. No “no data” walls.

6. Interactions & Motion

Interaction	Behaviour
Pulse (doing)	Scale 1→1.4, opacity 1→0.4, 1.6s ease-in-out
Card hover	120ms ease-out, border colour, translateY -1px
Drag	Shadow + 1px accent border, 1.02 scale
Route transition	160ms cross-fade main pane only
Toast	Bottom-right, slide-up 200ms, auto-dismiss 4s, undo on destructive (5s)
Focus ring	2px accent at 2px offset, always visible

All motion respects prefers-reduced-motion: reduce (tokens set to 0ms).

7. Keyboard Shortcuts

Keys	Action
`?`	Toggle help overlay
`j / k`	Navigate backlog rows down / up
`e`	Edit selected todo text (in-place)
`Space`	Cycle status: todo → doing → done → todo
`dd`	Delete selected todo (5s undo toast)
`1 / 2 / 3`	Assign owner to apollo / metis / mercury
`g p`	Go to Projects
`g l`	Go to Live Ops
`g a`	Go to Agents

8. Build Phases (Apollo backlog)

See todos.json — 17 tasks across bottom-up build:

Phase	Tasks	Description
0	t-001	Design tokens block in CSS
1	t-002	App shell: topbar + rail + hash routing
2	t-003	Core components (Card, AgentChip, ProgressBar, etc.)
3	t-004 to t-006	Projects grid → Project detail view
4	t-007 to t-008	Inline todo editor + backend endpoints
5	t-009 to t-010	Live Ops + Agents views
6	t-011 to t-013	Motion, keyboard shortcuts, density toggle
7	t-014 to t-017	Cleanup, smoke test, design review, docs

9. Risks & Mitigations

Risk	Mitigation
Existing endpoints stay; new are additive	No migration needed; client composes data
todos.json per project is disk-based	Fine for single-user; file lock = FastAPI process (single instance)
Real-time: polling, not SSE	Poll /heartbeat 3s + /activity 5s. SSE optional later
Single-file Alpine.js constraint	CSS tokens in `:root` block at top; inline everything

10. Quick Usage — pvs cheat sheet

Add a project

Click ”+ New Project” in left rail → dialog: slug, name, summary → save. Project appears on grid with zero todos, no assignees.

Add a todo (inside a project)

Open project detail → click ”[+ Add todo]” at top-right of Backlog → inline row auto-focused, default owner = first assignee → Enter saves, Esc cancels.

Reassign a todo

Click the owner chip on any todo row → popover with apollo / metis / mercury + “unassigned”. Or use keyboard 1/2/3.

Reassign a project

On project detail header, click any agent chip → agent toggled in/out of project. Saves via PATCH /assignees.

Design document created 2026-07-01 by Hermes-Ralph. Source materials: redesign.md (architectural spec), todos.json (build backlog), app/server.py (backend skeleton), app/design-tokens.css (CSS tokens).

Quartz 4

Explorer

DESIGN