Build Plan · Collaboration OS

Build Plan

A winding surveyed path through gentle terrain passing through gate thresholds — early gates solid and passed, a middle gate being crossed, far gates drawn as open circles

The build runs on an executable phased plan with hard gates: each phase must leave the app working and demonstrable, and no phase starts before the prior one's acceptance criteria pass with James's confirmation. The framing discipline, stated in the plan itself: the operating-system framing can absorb unlimited scope without ever shipping — so ship a usable field early and let it stay incomplete for a long time.

Stack: Next.js (App Router) + TypeScript + Tailwind + shadcn/ui · Supabase (Postgres, RLS, auth) · n8n Cloud for scheduled two-way ClickUp sync and meeting automation · Three.js reserved for optional spatial views. Claude Code is the structural build agent; Cursor enters for interface polish.

Status pass: 20 July 2026.

Phase 0 — Foundations complete

A running, authenticated, empty app. Email + password auth with magic-link fallback, protected routes, Supabase wired from server and client components, and the design-token baseline — a calm, restrained warm palette, deliberately not the neon marketing aesthetic.

Phase 1 — Data Plumbing complete

The substrate everything rests on. A normalized schema (clients, engagements, people, task lists, tasks, sync state, outbound queue) mirrors ClickUp: an inbound sync pulls and upserts every 30 minutes, and app edits queue outbound pushes every 15. The full round trip is verified — an edit made in the app appears in ClickUp, and re-syncs create no duplicates. Tasks from real client folders flow in, correctly grouped; the n8n workflows are exported and version-controlled.

Phase 2 — The View-Model Engine complete — the ship point

The core abstraction: a serializable view-model format that references entities by ID and describes arrangement — grouping, ordering, and which axes carry color and position. Coordinates never live in the data. A pure rendering engine consumes a view model plus data and produces the 2D field; view models are switchable at runtime with no code changes.

The phase's defining gate was the bus factor: the format had to be legible enough that someone other than its author could write one. It passed — James authored a new view model from the format documentation alone, and it appeared in the switcher untouched by code.

Airtable Migration complete

The old portal's backend — 50 clients, 278 people, 55 engagements with their relationship links — migrated one-time into Supabase, with logos and avatars re-hosted in storage. Airtable is retired as the home for these tables. Around 220 historical meeting artifacts followed, with their taxonomy of types, tags, and technologies.

In Production live

The app runs in production on Vercel, auto-deploying from a private repository on every push. The full auth loop and the deny-by-default access model are verified against the live deployment — an unprovisioned account sees nothing until it is granted a role. Access has grown into three tiers: admin (full oversight), team (scoped to the engagements they're on), and client (their own work only), managed from an in-app admin surface with email invitations. The custom domain is owned and waits on DNS.

Phase 3 — Client Views & Interface Polish essentially complete

The role model is built and proven live: invited client accounts, deny-by-default row-level security, and a deliberately reduced client surface — task names, full Action Process statuses, due dates, and groupings, with no team chrome and no internal descriptions. Clients also see their meeting artifacts now, with their own notes channel back to the studio. The interface went far past polish: the IRIS-brand design system (its own typography and a root-phi scale), a card language that renders every entity at four sizes — point, line, card, panel — and one status vocabulary everywhere, with open rings for intention and solid dots for reality. Editing happens in place across the app: clients, engagements, artifacts, people. What keeps the gate open: handing a client link to a real person and watching it need no explanation, and a deliberate mobile pass.

The Artifacts Evolution phases A + B shipped

A three-phase deepening of the meeting pipeline, running alongside Phase 3:

A — Planned meetings ✓. Meetings exist in the OS before they happen: planned artifacts with attendees, type, and a team-notes editor. The automation matches each incoming Fireflies transcript to its planned meeting, grounds the AI summary in the team's own notes, files everything under the known engagement, generates a banner image, and creates follow-up tasks — which sync back into the field. Meeting recordings now archive to a video host with an embedded player on the artifact page.
B — Essence-first artifact pages ✓. The redesign drawn from the research, now live: the TL;DR and verbatim quotes pulled forward in the editorial serif, decisions as cards with rationale, the client asks named — and The Meeting in Time, a timeline band docked across the bottom of the window with chapters, quote/decision/ask markers, a speaker strip, and a live playhead. Clicking the band drives the recording; the video floats above it while you read.
C — Publish + field. Largely absorbed en route: clients already see their artifacts, and artifacts sit as connected nodes on the engagement surface. What remains is presentation polish, not plumbing.

The Engagement Surface emergent — not in the original plan

The plan's "navigable field" arrived early, in two dimensions. Every engagement now opens onto a spatial canvas — pan, zoom, drag — where the work is arranged by hand: meeting artifacts, initiatives with their live tasks, pages, notes, links, timelines, and people, connected by drawn wires. Cards resize like windows and change register as they grow, from a bare status point to a full panel. Nothing deletes — cards archive and return. Multi-select brings alignment, distribution, and grids; every arrangement act is undoable. Positions live on the surface's placements, never on the entities themselves — the plan's founding principle, kept. A shared people directory ties canvas people to real ClickUp accounts.

Phase 4 — Spatial Views & the Wider Field half-arrived, out of order

The wider field half is real: people, initiatives, engagement profiles, and meeting artifacts are first-class entities, connected to tasks, and the meeting automations enrich the field rather than just producing documents. The spatial 3D half — the optional Three.js layer and spatial view models — has not started, and the 2D surface has been absorbing the demand for spatial arrangement; whether three dimensions still earn their place is a decision to make against real usage. Candidate geometries for a time axis are being researched in Ways of Seeing the Work. This is also where the carried-forward ideas land — the meeting continuum, the memory layer — detailed in Design Considerations.