DREAMTEAM — Technical Architecture

1. Executive Summary

DREAMTEAM is three tightly-coupled systems sharing a common data layer:

System	Maps to Spec	Core Engineering Challenge
Team Hub + Workspace Intelligence	Bucket 3 (Team Workspace) + Reimagined Terminal	Brain² as the memory spine, multi-agent orchestrator with swarm management, two-way voice agent interface, conversational chat with context-drift detection — all surfaced through a terminal-like wrapped web app
Presentation Engine	Bucket 1 (Presentation Deck)	Format-agnostic content model that renders as both click-through deck and long-scroll proposal, adapted for multi-tenant team editing with shared brand presets
Pitch Intelligence Pipeline	Bucket 2 (Pitch Intelligence) + pitch-room features from Bucket 3	Orchestrating AI outputs into a live presentation without visible latency — the edit lifecycle from proposal to landing, plus invisible group chat and live performance dashboard during pitches

Creative Intelligence (Bucket 4) and Public MCP are parked — not on the build roadmap. The proprietary creative-data moat is a separate, far-future bet that depends on DREAMTEAM being a working product first.

The central artifact is the hub. The hub is the thing that makes DREAMTEAM a place a team lives, not a deck tool with extras bolted on. Get the operating layer right, then everything else — the deck, pitch intelligence, follow-up generation — has a home to plug into. This shapes the entire data model and build order.

2. System Map

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                             │
│                                                                 │
│   Wrapped Web App             Mobile Companion       PWA Bridge │
│   (Reimagined Terminal)       (demand-gated)         (day-one)  │
│   primary surface             React Native / Expo               │
│                                                                 │
└──────────────┬──────────────────────┬───────────────────────────┘
               │                      │
               ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                     REAL-TIME LAYER                              │
│                                                                 │
│   Supabase Realtime                                             │
│   ├── Broadcast (chat, dashboard signals, edit lifecycle)       │
│   ├── Presence (who's online, viewport state, pitch status)     │
│   └── Postgres Changes (data sync, task board updates)          │
│                                                                 │
└──────────────┬──────────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    APPLICATION LAYER                             │
│                                                                 │
│   Fastify Backend (Railway) + BullMQ Workers                    │
│   ├── Brain² Manager (tier cycling, critical-flag enforcement)  │
│   ├── Agent Orchestrator (dispatch, swarm mgmt, completion)     │
│   ├── AI Gateway (BYOK credential resolution, Vercel AI SDK)   │
│   ├── Conversational Agent Runtime (voice out, turn-taking)     │
│   ├── Chat Layer Engine (context-drift, auto-route, auto-save)  │
│   ├── Migration Pipeline (Notion import, structure mapping)     │
│   ├── Deck Operations (CRUD, versioning, brand-preset apply)    │
│   ├── Edit Lifecycle Manager (propose → approve → land)         │
│   ├── Pre-pitch Pipeline (calendar watch, research trigger)     │
│   └── Meeting Capture Processor (Granola hook / fallback)       │
│                                                                 │
└──────────────┬──────────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      DATA LAYER                                  │
│                                                                 │
│   Supabase (Postgres)                                           │
│   ├── Core: orgs, members, projects, decks, slides, pitches    │
│   ├── Workspace: chat_messages, conversations, threads          │
│   ├── Tasks: task_board, agent_runs, swarm_runs                 │
│   ├── Memory: brain2_items (hot/warm/cold tiered)               │
│   ├── Migration: import_jobs, source_mappings                   │
│   └── pgvector: embeddings for Brain², semantic search          │
│                                                                 │
│   Supabase Storage                                              │
│   ├── Brand assets (logos, fonts, images)                       │
│   ├── Meeting recordings / transcripts                          │
│   ├── Template marketplace assets                               │
│   └── Deck exports / snapshots                                  │
│                                                                 │
└──────────────┬──────────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────────┐
│                   AI INTEGRATION BOUNDARY                        │
│                                                                 │
│   Engineering provides:          AI team provides:              │
│   ├── Audio capture pipeline     ├── STT models                 │
│   ├── Agent runtime/scheduler    ├── Voice-reactive inference   │
│   ├── Suggestion UI + approval   ├── Auto-tailor logic          │
│   ├── Voice-out playback infra   ├── TTS engine                 │
│   ├── Context-drift detection    ├── Topic-embedding models     │
│   ├── Scoring pipeline hooks     ├── Suggestion generation      │
│   └── Migration struct. mapping  └── Content classification     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

3. Subsystem Breakdown

3.1 Team Hub + Workspace Intelligence (Phase 1)

What it does: The always-on operating layer — Brain², multi-agent orchestrator, conversational interfaces, meeting capture, migration. Everything reads and writes through this. Surfaced as a terminal-like wrapped web app.

Key technical components:

Component	What it is	How it works
Brain²	Tiered knowledge store — the memory spine	Three Postgres tables (brain2_hot, brain2_warm, brain2_cold) with different retention policies. Hot = active project context (full rows). Warm = recent + semantically close (pgvector embeddings, searchable). Cold = historical archive (pgvector, compressed). Smart cycling keyed to active project/quarter/objective. Critical-flag items never auto-demote. Every demotion logged, one-click re-promote.
Multi-Agent Orchestrator + Task Board	Runtime for AI agent deployment + project management	Kanban board with three input sources (human, auto-extracted from meetings, agent-proposed). Dispatches agents/squads against tasks. Swarm visibility (composite run view), swarm-sizing recommendation, auto-recognition of completion + board deduplication. Efficiency lens per teammate. Privacy gate for solo/scratch sessions.
Conversational Agent Interface	Two-way voice interaction	Voice in already solved (Wispr-style dictation). This adds voice out + true turn-taking loop — teammate talks, DREAMTEAM responds aloud, teammate reacts, agent adjusts. Cross-cutting modality: applies anywhere you’d otherwise type at an agent (briefing swarms, reviewing runs, querying Brain²). Same agent runtime, voiced front-end.
Conversational Chat Layer	Persistent conversation history with intelligence	Claude-style sidebar of every past conversation — scroll back, branch, resume. Context-drift detection (Wispr-style): when a conversation shifts topic, auto-spawn a new thread that stays aware of the prior one. No-manual-save running doc auto-populates as conversation unfolds. Auto-route on close: archive/close/inactivity routes the doc to the right destination (project folder, Brain² tier, task board). Direct Brain² intake — auto-routed concise docs feed warm/cold tiers.
Reimagined Terminal	Terminal-style wrapped web app	The hub operates like a terminal: you work in it and it feels like a cloud that knows your entire brain, with room to tweak. Shipped as a wrapped web app — the primary surface. References: Macro and Merydian’s hub approaches as starting points.
Meeting Capture	Granola integration or native fallback	If Granola connected: webhook to receive transcript/summary feed, store pointer + metadata. If not: native audio capture → STT → structured summary (action items, decisions, attendees, named-entity tags). Encrypted at rest, tenant-isolated. Feeds Brain², pre-pitch briefings, and follow-up decks.
Migration & Onboarding	One-click import from existing tools	Notion-first: workspaces, docs, databases, task boards via OAuth. Zero-config mapping: Notion pages/docs → Brain² (warm/cold), Notion databases/boards → task board, Notion teamspaces → workspace structure. Preserves hierarchy, links, properties/tags, assignees. Optional incremental re-sync until full cutover. Adjacent stores later (Google Docs/Drive, Linear, Asana, Coda).

Hard problems:

Brain² cycling logic: “Smart cycling keyed to active project/quarter/objective” — the interaction between cycling rules, critical-flag protection, and sublinear index maintenance is tricky. When items move from warm to cold, embeddings need re-indexing into the cold-tier vector index without blocking queries.
Multi-agent orchestration complexity: Swarm management, completion detection, swarm-sizing recommendation, and board deduplication are each non-trivial systems. Start simple: single-agent runs first, add swarm features incrementally.
Voice talkback pipeline: TTS engine selection, barge-in handling (interrupting the agent mid-sentence), and whether it runs client-side or streams from the runtime. Latency-sensitive — needs to feel conversational, not walkie-talkie.
Context-drift detection: What signals trigger an auto-spawned new thread (topic-embedding distance? explicit cue? silence gap?)? Too aggressive = annoying thread fragmentation. Too lax = conversations become incoherent. Needs tuning.
Migration fidelity: Preserving Notion page hierarchy, links between pages, properties/tags, and assignees so the imported workspace is navigable — not a flat dump. Incremental re-sync introduces conflict resolution if both sides edit during cutover.

3.2 Presentation Engine (Phase 2)

What it does: Stores, renders, and mutates pitch decks. Already largely built (parzvl.com/dual-template, adaptive viewer, brand preset system). The Phase 2 work is adapting it to be team-editable: multi-tenant brand presets, shared delivery, team ownership — not a single-operator tool.

Key technical components:

Component	What it is	How it works
Content Model	Format-agnostic slide/block representation	Each “slide” is an ordered list of content blocks (text, image, chart, embed) with layout hints. The renderer decides deck-vs-scroll layout, not the data model.
Brand Preset System	Versioned design-token object	Palette, type system, logo treatments, motion, spacing, voice/tone, component skins. Stored as JSON with version history. Editing propagates to all linked decks. Per-deck overrides via JSON merge-patch. Multi-tenant: org-level presets with team ownership.
Dual-Mode Renderer	React component library	Two layout engines consuming the same content model. Desktop defaults to deck, mobile defaults to scroll. Mode toggle preserves equivalent section. Build on existing `dual-template` prototype.
Shareable Links	Every deck is a URL, never a file	Next.js dynamic routes with SSR for preview/SEO. Auth layer controls access (public link, org-only, password-protected). Live edits propagate to the same URL.
Template System	Marketplace + house-line packs	Templates are deck skeletons. On download, auto-conform to user’s active brand preset.
Mode Toggles	Executive / Concept / Print-safe / Dark-Light	Global presets that adjust rendering parameters. These are preset-modifier objects, not separate presets.

Hard problems:

Live hot-swap during presentation: When the live editing engine lands a change mid-pitch, the viewer’s deck must update without jarring transitions. Renderer needs a diffing strategy — update individual content blocks, not re-render the full slide.
“Smart auto-restructure”: If a pending edit isn’t done rendering when the presenter advances, promote the next-ready slide and reinsert the edited one when ready. Real-time priority queue for slide rendering.
Dual-mode rendering fidelity: Deck and scroll views diverging in quality/behavior. Invest in the content model — if the abstraction is right, both renderers are straightforward.

3.3 Pitch Intelligence Pipeline (Phase 2)

What it does: The AI-powered layer that adapts decks before, during, and after pitches. Engineering owns the plumbing; the AI team owns the intelligence. Includes the two pitch-room features (invisible group chat + live performance dashboard) relocated from Bucket 3 since they only matter during a pitch.

Key technical components:

Component	Engineering owns	AI team owns
Live Editing Engine	Edit lifecycle state machine (Proposed → Approved → Countdown → Landed → Reverted). WebSocket-driven. Visible countdown timer per push. Conflict resolution when multiple edits target the same slide.	—
Pre-pitch Adaptation	Calendar integration (Google/Outlook API), scheduling pipeline (T-24h deep scan, T-2h final), approval UI for proposed modifications, briefing document renderer	Auto-research (buyer news, exec moves, social signals), auto-tailor (cross-reference briefing against active deck, propose mods)
Voice-reactive Extension	Audio capture pipeline (browser MediaStream API or native), relay to STT service, suggestion UI (inline in invisible chat), approval flow, live-edit push on approval	STT transcription, real-time understanding (what’s landing, what isn’t), suggestion generation
Follow-up Deck	Post-pitch trigger, template selection, auto-draft assembly from transcript + deck + action items, human review UI	Content generation from transcript + deck context, action-item extraction
Invisible Group Chat	Supabase Realtime Broadcast channel per pitch session. Each teammate has independent viewport state (Presence). Messages persisted for post-pitch review.	—
Live Performance Dashboard	Renders coaching signals: slide timer, talk-time balance bars, transcript surface, pacing flags. All inline in the invisible-chat surface as chips, not modal interrupts.	Audio analysis signals: talk-time per speaker, pacing assessment, key-phrase highlights, “buyer hasn’t spoken” flags

The edit lifecycle is a state machine:

  ┌──────────┐    approve    ┌──────────┐   timer    ┌───────────┐
  │ Proposed │──────────────▶│ Approved │──────────▶│ Countdown │
  └──────────┘               └──────────┘           └─────┬─────┘
       │                          │                        │
       │ reject                   │ cancel                 │ timer expires
       ▼                          ▼                        ▼
  ┌──────────┐              ┌──────────┐            ┌──────────┐
  │ Rejected │              │ Cancelled│            │  Landed  │
  └──────────┘              └──────────┘            └────┬─────┘
                                                         │
                                                         │ revert
                                                         ▼
                                                    ┌──────────┐
                                                    │ Reverted │
                                                    └──────────┘

Hard problems:

Latency budget for voice-reactive: Audio capture → STT → understanding → suggestion → render. Must surface suggestions within seconds of the relevant conversation moment. Engineering needs to buffer and stream, not wait for complete utterances.
Slide-on-demand: Generate a brand-new slide from prompt during the pitch. Content model must support dynamic insertion, and the viewer’s navigation must accommodate it without disrupting the presenter’s flow.
Screen-share-invisible chat: The spec calls for kCGWindowSharingNone (macOS) and WDA_EXCLUDEFROMCAPTURE (Windows). This cannot be done in a browser tab — requires a native desktop shell. Fallback: the mobile companion IS the invisible back-channel (phones already on the table during pitches).

4. Data Architecture

4.1 Core Entity Model

Organization
├── Members (user_id, role, permissions)
├── BrandPresets (versioned JSON, org-level, per-deck override)
├── Projects
│   ├── Decks
│   │   ├── Slides (ordered, content_blocks JSONB)
│   │   ├── DeckBrandOverride (merge-patch on org preset)
│   │   └── EditQueue (status, target_slide, target_block, proposed_content)
│   ├── Pitches (scheduled events)
│   │   ├── PitchSessions (live state: active/completed)
│   │   │   ├── ChatMessages (persisted back-channel)
│   │   │   ├── DashboardSignals (talk_time, pacing, transcript)
│   │   │   └── EditLifecycleEvents (proposed/approved/landed/reverted)
│   │   └── BuyerBriefings (pre-pitch research output)
│   ├── TaskBoard
│   │   ├── Tasks (source: human/meeting_capture/agent, status, assignee)
│   │   └── AgentRuns (task_id, agent_type, status, model, tokens, output)
│   │        └── SwarmRuns (composite run, child agent_runs)
│   └── Brain2Items (tier: hot/warm/cold, content, embedding, critical_flag)
├── Conversations (thread_id, parent_thread, topic_embedding, status)
│   ├── Messages (role, content, timestamp)
│   └── AutoRoutedDocs (destination, confirmation_status)
├── MeetingCaptures (transcript, action_items, decisions, attendees)
└── ImportJobs (source: notion/gdrive/etc, status, mapping_config)
    └── SourceMappings (source_id, target_type, target_id, structure_meta)

4.2 Storage Strategy

Data type	Storage	Why
Structured data (all tables above)	Supabase Postgres	Relational integrity, RLS for multi-tenancy, real-time subscriptions
Vector embeddings (Brain², semantic search, context-drift)	pgvector extension	Native to Supabase, no separate vector DB to manage
Brand assets, logos, fonts	Supabase Storage	CDN-backed, access-controlled
Meeting recordings	Supabase Storage (encrypted)	Tenant-isolated, retention-controlled
Template marketplace assets	Supabase Storage	Public/paid access tiers

4.3 Multi-tenancy & Security

Row Level Security (RLS) on every table. Org membership determines access.
Brain² isolation: Each org’s memory is completely isolated. No cross-tenant data leakage.
Meeting captures encrypted at rest: Supabase Storage encryption + application-level encryption for transcript content.
Conversation privacy: Solo/scratch agent sessions stay private. Only runs explicitly attached to a task surface to the team.
Migration data isolation: Imported data inherits the org’s RLS policies on arrival.

5. Tech Stack

5.1 Confirmed Stack

Layer	Technology	Rationale
Web frontend	Next.js 15 (App Router)	SSR for shareable deck links, React Server Components for dashboard, client-side for real-time. Vercel deployment. The web app IS the desktop experience day one.
Backend service	Fastify (TypeScript)	Persistent backend for agent orchestration, AI gateway, voice pipeline, background jobs. Separate from Next.js because agent runs are long-lived (minutes), voice needs persistent WebSockets, and background jobs need a persistent process. Deploys to Railway.
Job queue	BullMQ + Redis	Background job processing: agent dispatch, Brain² tier cycling, scheduled pre-pitch research (T-24h/T-2h triggers), migration imports, meeting capture processing.
Database	Supabase (Postgres)	Relational data, RLS for multi-tenancy, Realtime subscriptions.
Vector search	pgvector (Supabase)	Brain² warm/cold tiers, semantic search, context-drift topic embeddings. Native Postgres extension — no separate vector DB. Hardcoded to `vector(1536)` for now (matches OpenAI text-embedding-3-small).
Real-time	Supabase Realtime	Broadcast for chat/signals, Presence for user state, Postgres Changes for data sync.
Auth	Supabase Auth	Email/password + OAuth (Google for calendar, Notion for migration). Org-based access via RLS. API key auth via Edge Function → JWT minting.
Storage	Supabase Storage	Brand assets, meeting recordings (encrypted), template marketplace assets, deck exports.
AI SDK	Vercel AI SDK	Provider-agnostic interface across LLM providers (Anthropic, OpenAI, Google). Wraps each provider’s SDK (`@ai-sdk/anthropic`, `@ai-sdk/openai`) into a unified API. Streaming-first, tool calling, agent support. React hooks (`useChat`, `useCompletion`) for consuming AI streams in the frontend.
AI gateway	Custom (in backend service)	Resolves BYOK credentials per org, routes through Vercel AI SDK to the right provider, logs usage to `ai_usage_records`. Security boundary — credential decryption happens here, never in the frontend or Edge Functions.
Edge Functions	Supabase Edge Functions (Deno)	Lightweight, short-lived operations: API key validation → JWT minting, webhook receivers (Granola, OAuth callbacks). NOT used for agent orchestration or AI calls.
Hosting (web)	Vercel	Next.js deployment, preview URLs, edge rendering for global deck access.
Hosting (backend)	Railway	Long-running Node.js process, WebSocket support, Redis addon for BullMQ. Simple deploy from monorepo subfolder.
Monorepo	pnpm workspaces	Shared TypeScript types between web + api from day one (both apps talk to the same DB and each other). No Turborepo — pnpm workspaces handle the dependency graph without extra tooling overhead.
Payments	Stripe	Subscription billing, marketplace payouts (Stripe Connect).
Mobile	React Native / Expo	Demand-gated — ship after web app. Shared data-layer logic via `packages/shared`. Native APIs for camera, mic, push notifications.

5.2 Project Structure

dreamteam/
├── apps/
│   ├── web/                    — Next.js 15 (App Router)
│   │   ├── app/                  Vercel deployment
│   │   ├── components/           The Reimagined Terminal, all UI
│   │   ├── lib/                  Auth pages, SSR for shareable deck links
│   │   └── ...                   Supabase client for direct data access (RLS-enforced)
│   │                             Consumes AI streams from backend via React hooks
│   │
│   └── api/                    — Node.js backend service (Fastify)
│       ├── src/
│       │   ├── routes/           API endpoints
│       │   ├── agents/           Agent orchestrator + agent type definitions
│       │   ├── gateway/          AI gateway (BYOK credential resolution, provider routing)
│       │   ├── voice/            Voice pipeline (WebSocket, TTS, turn-taking)
│       │   ├── workers/          BullMQ job processors
│       │   │   ├── brain2/         Tier cycling, embedding computation
│       │   │   ├── migration/      Notion import pipeline
│       │   │   ├── meeting/        Meeting capture processing
│       │   │   └── research/       Pre-pitch research triggers
│       │   └── lib/              Shared utilities, Supabase client
│       └── ...
│
├── packages/
│   └── shared/                 — Shared TypeScript
│       ├── src/
│       │   ├── types/            Domain types (AgentEvent, Brain2Item, TaskStatus, etc.)
│       │   ├── contracts/        API request/response shapes
│       │   ├── constants/        Status enums, tier names, scopes, provider list
│       │   └── supabase.ts       Generated Supabase types (from supabase gen types)
│       └── ...
│
├── supabase/
│   ├── migrations/             — SQL migrations
│   │   └── 001_foundation.sql    Schema: orgs, members, projects, Brain², tasks,
│   │                             agents, API keys, credentials, usage, profiles
│   ├── functions/              — Edge Functions (Deno)
│   │   ├── auth-api-key/         API key validation → JWT minting
│   │   └── webhooks/             Granola, OAuth callbacks
│   ├── seed.sql                — Development seed data
│   └── config.toml             — Supabase project config
│
├── pnpm-workspace.yaml
├── package.json
└── tsconfig.base.json

5.3 What Runs Where

Concern	Where	Why there
UI rendering, auth pages, deck viewer	`apps/web` (Vercel)	Short-lived requests, SSR, static assets
Direct data queries (CRUD, search)	`apps/web` → Supabase	RLS enforces auth, no backend roundtrip needed
Supabase Realtime subscriptions	`apps/web` client-side	Browser holds the WebSocket to Supabase
Agent dispatching + swarm coordination	`apps/api` (Railway)	Long-running (minutes), stateful, needs persistent process
AI calls (all providers, BYOK)	`apps/api` via Vercel AI SDK	Security boundary for credential decryption
Agent output streaming to UI	`apps/api` → SSE/WebSocket → `apps/web`	Backend streams tokens/progress, frontend renders
Voice turn-taking loop	`apps/api` WebSocket endpoint	Persistent connection, latency-critical
Brain² tier cycling	`apps/api` BullMQ worker	Scheduled background job
Migration imports	`apps/api` BullMQ worker	Long-running, processes hundreds of pages
Meeting capture processing	`apps/api` BullMQ worker	Audio → STT → structured summary pipeline
Pre-pitch research triggers	`apps/api` BullMQ worker	Scheduled (T-24h, T-2h), background
API key → JWT minting	`supabase/functions/`	Lightweight, runs close to the DB, short-lived
Webhook receivers	`supabase/functions/`	Simple request → DB write

6. AI Integration Boundary

6.0 AI Gateway + Credential Model

BYOK (Bring Your Own Key) only. Every org provides their own LLM provider API keys (Anthropic, OpenAI, etc.). DREAMTEAM does not hold platform keys or resell API access — the org pays their provider directly. This keeps the business model simple: DREAMTEAM charges for the platform, not for inference.

The AI gateway sits in the backend service and:

Reads the org’s stored credentials for the requested provider
Routes through the Vercel AI SDK (unified interface across providers)
Logs usage to ai_usage_records for the efficiency lens (per-teammate AI usage visibility) — not for billing

Provider credentials are encrypted at the application level before storage. Raw keys are never returned to the frontend after creation.

Org model: Every user gets a personal org auto-created on signup (Supabase Auth trigger). Teams create additional orgs. API keys live at the org level. Solo users set their own key; team admins set the team key.

6.1 Interface Contracts

Capability	Engineering provides (input)	AI team provides (output)	Latency requirement
Pre-pitch auto-research	Buyer name, company, meeting context, calendar metadata	Structured briefing: news items, exec moves, social signals, competitive context	Background (T-24h trigger), can be minutes
Auto-tailor	Current deck (content model), buyer briefing	Proposed modifications (list of slide/block-level edits with rationale)	Background (T-2h trigger), minutes acceptable
Voice-reactive suggestions	Audio stream (chunked), current deck state, current slide position	Suggestions: text + target slide/block + confidence score	<3 seconds from relevant utterance
Follow-up deck draft	Meeting transcript, original deck, action items	Draft follow-up content blocks (recap, next steps, ask-specific addendum)	Background (post-meeting), minutes acceptable
Live dashboard signals	Audio stream, speaker diarization	Talk-time per speaker, pacing assessment, key-phrase highlights, “buyer hasn’t spoken” flags	<2 seconds
Meeting summarization	Full audio recording or transcript	Structured summary: action items, decisions, key moments, attendee contributions	Post-meeting, minutes acceptable
Voice-out / TTS	Text response from agent runtime	Natural speech audio stream with low latency	<500ms first-byte for conversational feel
Context-drift detection	Conversation message history + embeddings	Topic-shift signal (new topic detected, confidence score)	<1 second per message
Migration content classification	Raw imported content (Notion pages, docs)	Classification: project context vs. reference material vs. task vs. archive	Background, seconds acceptable

6.2 Agent Runtime Contract

The orchestrator dispatches AI agents. Each agent must conform to:

interface AgentContract {
  agentType: string;           // e.g., "research_buyer", "auto_tailor"
  invoke(input: AgentInput): AsyncIterable<AgentEvent>;
  // Events the agent must emit:
  // - status_update: current step, progress estimate
  // - task_delta: structured change to a task/artifact
  // - completion: final output + one-sentence summary
  // - error: failure with retry guidance
}

7. Phase 1 — Wave-Level Execution Plan

Alex paves the backend; Nate wires the frontend. Each wave ships backend work that unblocks frontend work. A wave is a coherent slice — not a time box. Sprints are the time box.

Wave 1 — Foundation & Shared Contract

Why first: Everything downstream depends on typed contracts and a working API skeleton. Nate can’t build real UI without types and endpoints.

#	Item	Owner	What ships
1.1	Shared types from schema	Alex	`packages/shared/` populated: Org, Member, Brain2Item, Task, AgentRun, SwarmRun, Conversation, Message, UserProfile, API key types. Generated Supabase types via `supabase gen types`.
1.2	API service auth + Supabase client	Alex	Fastify middleware that validates Supabase JWT, extracts user/org context. Service-role Supabase client for backend operations.
1.3	Org + profile endpoints	Alex	GET/PATCH org, GET org members, GET/PATCH user profile. Nate can build settings UI.
1.4	API key management endpoints	Alex	CRUD for org API keys (BYOK). Encrypted storage, admin-only.
1.5	Dashboard data endpoint	Alex	Aggregated endpoint: org summary, recent activity, member list. Unblocks Nate’s dashboard.

Nate unblocked on: Settings UI, dashboard shell, org management, user profile.

Wave 2 — Brain² (The Memory Spine)

Why second: Brain² is the central data layer everything else reads/writes through. Chat feeds it, agents query it, meeting capture populates it. Build this before anything that depends on memory.

#	Item	Owner	What ships
2.1	Brain² CRUD API	Alex	Create/read/update/delete brain2 items. Filter by tier (hot/warm/cold), project, critical flag. Paginated list + single-item fetch.
2.2	Brain² search (pgvector)	Alex	Semantic search endpoint: text query → embedding → cosine similarity search across warm+cold tiers. Uses `vector(1536)` with OpenAI text-embedding-3-small.
2.3	Brain² tier cycling worker	Alex	BullMQ background job: evaluates items for demotion (hot→warm→cold) based on project activity, age, access frequency. Critical-flag items skip. Logs every demotion.
2.4	Brain² re-promote endpoint	Alex	One-click re-promote: cold→warm or warm→hot. Reverses auto-demotion.
2.5	Brain² intake endpoint	Alex	Accepts content from other systems (chat auto-route, meeting capture) and classifies into the right tier.

Nate unblocked on: Brain² UI — the “second brain” view. Search interface. Memory timeline. Hot/warm/cold visualization.

Dependency note: Wave 2 requires Redis + BullMQ for the cycling worker. Set up Redis addon on Railway as part of 2.3.

Wave 3 — Conversational Chat Layer

Why third: The chat layer is the primary interaction surface — the main thing users type into. It feeds Brain² (wave 2) and later connects to the agent runtime (wave 4).

#	Item	Owner	What ships
3.1	Conversations + messages API	Alex	CRUD for conversations (create, list, get with messages). Message streaming via Supabase Realtime (postgres_changes on messages table). Thread branching (parent_thread_id).
3.2	Running doc auto-generation	Alex	As messages arrive, maintain a concise running doc per conversation. Background job or trigger.
3.3	Auto-route on close	Alex	When conversation is archived/closed/inactive, route the running doc to a destination: Brain² tier, project folder, or task board. Confirmation chip (not a gate).
3.4	Context-drift detection (v1)	Alex	Basic implementation: compute topic embeddings per message window, detect when similarity drops below threshold. Start conservative (explicit cues only). Auto-spawn new thread on drift.

Nate unblocked on: Chat UI — Claude-style sidebar, conversation history, thread navigation. The “reimagined terminal” is largely this + Brain² rendered in a terminal-like shell.

Wave 4 — Agent Runtime & In-App Task Board

Why fourth: The agent runtime deploys AI agents against tasks. The in-app task board (not the project taskboard) is where agents and humans collaborate on project work.

#	Item	Owner	What ships
4.1	AgentContract + registry	Alex	TypeScript interface for agents (agentType, invoke → AsyncIterable). Agent registry for type→implementation lookup.
4.2	AI gateway (BYOK routing)	Alex	Resolve org’s provider credentials, route through Vercel AI SDK, log usage to ai_usage_records. Security boundary — credentials decrypted here only.
4.3	Single-agent dispatcher	Alex	Dispatch an agent against a task. Stream AgentEvents (status_update, task_delta, completion, error) back to the client via SSE.
4.4	In-app task CRUD	Alex	Create/read/update tasks within a project. Three sources: human, auto-extracted, agent-proposed. Assignee, status, project scope.
4.5	Agent run tracking	Alex	Track agent runs: model, tokens, current step, ETA. Attach runs to tasks. Stream progress.
4.6	Agent completion detection	Alex	Agents emit structured task-delta events. On completion, draft one-sentence summary. Flag candidate task completion for human review.
4.7	Privacy gate	Alex	Solo/scratch agent sessions stay private. Only runs explicitly attached to a task surface to the team.

Nate unblocked on: Agent run UI, task board UI, efficiency lens (per-teammate AI usage), agent output streaming display.

Deferred from this wave (add incrementally): Swarm management, swarm-sizing recommendation, board deduplication. Start with single-agent runs.

Wave 5 — Voice Pipeline

Why fifth: Depends on agent runtime (wave 4). Voice is a modality on top of the existing agent + chat infrastructure.

#	Item	Owner	What ships
5.1	TTS engine integration	Alex	Select and integrate TTS engine (likely ElevenLabs or OpenAI TTS). Streaming audio output. <500ms first-byte target.
5.2	Voice turn-taking WebSocket	Alex	Persistent WebSocket endpoint for voice sessions. Client sends audio chunks → STT → agent runtime → TTS → client plays audio. Turn-taking protocol.
5.3	Barge-in handling	Alex	Client-side detection of user speaking while agent is outputting. Interrupt agent mid-sentence, restart listening.

Nate unblocked on: Voice UI — mic button, audio playback, visual turn indicators.

Open question: TTS engine choice. Spike needed before committing.

Wave 6 — Meeting Capture

Why sixth: Feeds Brain² and later pitch briefings. Not on the critical path for core hub experience but important for “knows your whole brain.”

#	Item	Owner	What ships
6.1	Meeting capture processor	Alex	BullMQ worker: accepts audio/transcript → STT (if audio) → structured summary (action items, decisions, attendees, named-entity tags).
6.2	Granola integration (if available)	Alex	Webhook receiver: Granola sends transcript/summary → store pointer + metadata. Edge Function or API route.
6.3	Brain² + task board feed	Alex	Processed meeting outputs → Brain² warm tier. Action items → task board as proposed tasks.

Open question: Granola partnership model. Build native fallback first.

Wave 7 — Migration & Onboarding

Why last in Phase 1: Important for adoption but not for core product experience. Teams can use DREAMTEAM without importing from Notion day one.

#	Item	Owner	What ships
7.1	Notion OAuth flow	Alex	OAuth integration for Notion API access. Stored at org level.
7.2	Structure mapping engine	Alex	Map Notion hierarchy → DreamTeam structure. Pages/docs → Brain² (warm/cold). Databases/boards → task board. Teamspaces → workspace structure.
7.3	Import pipeline worker	Alex	BullMQ worker: processes hundreds of pages. Preserves hierarchy, links, properties, assignees. Progress reporting.
7.4	Re-sync (optional)	Alex	Incremental re-sync from Notion until full cutover. Conflict resolution if both sides edited.

Nate unblocked on: Migration UI — connect Notion, pick what to import, progress display, mapping review.

Cross-cutting (Nate-led, depends on waves 1-4)

Item	Owner	Depends on
Reimagined Terminal shell	Nate	Waves 1-3 (needs chat + brain2 APIs)
Dashboard with real data	Nate	Wave 1 (dashboard endpoint)
Brain² UI (memory view)	Nate	Wave 2 (brain2 API)
Chat UI (sidebar, threads)	Nate	Wave 3 (chat API)
Agent run + task board UI	Nate	Wave 4 (agent + task API)
Voice UI	Nate	Wave 5 (voice pipeline)
Meeting capture UI	Nate	Wave 6 (capture API)
Migration/onboarding UI	Nate	Wave 7 (migration API)

8. Hard Problems & Risk Register

#	Problem	Risk	Mitigation
1	Voice talkback pipeline latency	If agent voice responses feel sluggish (>1s latency), the conversational interface feels broken — walkie-talkie, not conversation	Research TTS engines early. Prototype streaming voice output. Define barge-in handling strategy before building the full conversational interface.
2	Brain² tier cycling under load	Moving items between tiers while maintaining query performance	Start with hot tier, add warm/cold incrementally when usage patterns are clear. pgvector reindexing can run as background jobs.
3	Context-drift detection tuning	Too aggressive = annoying thread fragmentation. Too lax = incoherent conversations.	Start conservative (explicit cues only), add embedding-based detection as a tunable threshold. User override always available.
4	Migration fidelity	Notion page hierarchy, links, properties lost or flattened during import	Build a structural mapping layer, not just text extraction. Test against real Notion workspaces with complex hierarchies. Incremental re-sync introduces conflict resolution complexity.
5	Multi-agent orchestration complexity	Swarm management, completion detection, and board deduplication are each non-trivial systems	Start simple: single-agent runs. Add swarm features incrementally.
6	Live deck mutation latency	Viewer sees stale slides or janky transitions during a pitch	Build a prototype of the edit lifecycle early. Measure round-trip: edit approved → viewer sees update. Target <500ms.
7	Screen-share-invisible chat	May require a desktop shell (Tauri/Electron), adding significant complexity	Fallback: mobile companion IS the invisible back-channel. Many pitch teams already have phones on the table. Desktop shell is post-mobile concern.
8	Voice-reactive pipeline latency	If AI suggestions arrive 10+ seconds after the relevant moment, they’re useless	Define latency SLA with AI team early (<3s). Build the audio pipeline to stream chunks, not wait for complete utterances.
9	Dual-mode rendering fidelity	Deck and scroll views diverging in quality/behavior	Invest in the content model. If the abstraction is right, both renderers are straightforward. Prototype both views early.

9. Open Questions for Product

#	Question	Blocks	Engineering needs
1	Granola partnership model (API, white-label, or screen-scraping shim?)	Phase 1 meeting capture	Determines integration architecture
2	Voice talkback stack — TTS engine + barge-in handling, client-side or server-streamed?	Phase 1 conversational agent interface	Determines audio pipeline architecture
3	Context-drift threshold — what signals trigger auto-spawned new thread, and how aggressive?	Phase 1 chat layer	Determines detection model + tuning strategy
4	Migration depth — one-time cutover import vs. live two-way sync with Notion? Conflict handling?	Phase 1 migration	Determines sync architecture complexity
5	Full-screen-share invisibility — solvable, or accept window-share-only?	Phase 2 invisible chat	Determines whether to rely on mobile fallback
6	Per-brand upfront fee structure (fixed, deck-volume-scoped, tiered?)	Phase 2 onboarding flow	Determines billing UI + Stripe product setup
7	Marketplace revenue split (flat % or tiered?)	Phase 2 marketplace	Determines Stripe Connect configuration
8	Push-lifecycle countdowns — static defaults or auto-tuned?	Phase 2 edit lifecycle	Static is much simpler; auto-tuned needs historical data
9	Task-delta event format — canonical schema?	Phase 1 agent orchestrator	Determines the agent runtime contract
10	Cross-tool agent ingestion — Claude Code / Cursor / arbitrary CLIs, or only DREAMTEAM-launched agents?	Phase 1 agent orchestrator	Determines whether orchestrator needs a generic agent adapter layer
11	Sublinear index choice — HNSW vs. FAISS-IVF vs. bespoke?	Phase 1 Brain² cold tier	pgvector uses HNSW natively; if FAISS is required, need separate service
12	Swarm-sizing model — heuristic table, learned-from-history, or LLM-judged?	Phase 1 orchestrator	Determines recommendation engine complexity
13	Board-dedupe matching — how strict before flagging accidental completion?	Phase 1 orchestrator	Determines matching strategy (exact title vs. semantic vs. artifact overlap)

10. Parked — Creative Intelligence (Bucket 4)

The following systems from the DREAMTEAM Spec are parked, not sequenced:

Award-show credit database + scoring index
Love-the-Work-More AI — multi-modal study of award-winning work
Legend Arsenal — AI personas of advertising legends
Public MCP Server — metered API exposing the knowledge corpus to external agents

These will be revisited once DREAMTEAM is a working product. The orchestrator in Phase 1 is designed to be agent-agnostic, so Legend Arsenal personas can plug in later without architectural changes.

This document maps the DREAMTEAM Working Spec, Build Order v3, and wave-level execution plan to engineering reality. Updated 2026-05-29.