Architecture

Phantom is built as a modular monorepo. Each package has a single responsibility and communicates through explicit TypeScript contracts plus the local runtime APIs.

System Diagram

graph TD
    User[User / Product Manager] --> UI["@phantom-pm/app (Next.js Matrix UI)"]
    User --> Inputs["Channels / Browser Capture / MCP"]
    Inputs --> UI
    UI --> Core["@phantom-pm/core (The Brain)"]

    subgraph "Phantom Core (The Brain)"
        Core --> AI[AIManager (Models) + Dynamic Providers Registry]
        Core --> Rules[Mission Policies and Guardrails]
        Core --> Context[Rowboat Context Engine (Graph)]
        Core --> Swarm[Agent Swarm Routines]
        Core --> Jobs[BullMQ Background Jobs]
        Core --> Gateway[OS Gateway (WebSocket)]
        Context --> SQLite[(SQLite DB)]
        Jobs --> Redis[(Redis)]
    end

    subgraph "Intelligence Extensibility (The Hands)"
        Gateway --> EdgeNode["@phantom-pm/os-agent (Edge Node)"]
        EdgeNode --> OS[Desktop UI / Bash / Mouse]
        Core --> MCPClient[MCP Aggregator]
        MCPClient --> Notion[Notion MCP Node]
        MCPClient --> Jira[Jira MCP Node]
    end

    subgraph "Generative Feedback"
        UI --> Sandpack[OpenUI React Sandbox]
    end

    AI --> Claude[Anthropic (Claude 3.7 + Computer Use)]
    AI --> OpenAI[OpenAI (o3-mini)]
    AI --> Ollama[Local Models (Llama 3, DeepSeek)]

Package Overview

Package	Purpose	Key Files
`@phantom-pm/core`	The core engine. Houses the AIManager, Rowboat graph context, mission policies, and the runtime contracts.	`ai/manager.ts`, `context.ts`, `missions/store.ts`
`@phantom-pm/app`	The browser UI for missions, context, memory, and integrations.	`app/page.tsx`, `components/missions/MissionHistory.tsx`
`@phantom-pm/os-agent`	The local edge node for browser and desktop actions.	`index.ts`
`@phantom-pm/mcp-server`	Model Context Protocol server exposing Phantom to editors and other tools.	`index.ts`, `discovery.ts`
`@phantom-pm/cli`	The terminal interface for local-first operation and automation.	`index.tsx`, `commands/server.ts`

Data Storage

All runtime data is stored locally in ~/.phantom/:

~/.phantom/
├── config.json
├── phantom.db
├── context/
├── memory/
├── missions/
└── web/

No Phantom-hosted control plane is required for the product to run locally.

Build System

TypeScript throughout
npm workspaces for monorepo management
Next.js for the app UI
docs-site as the canonical public documentation surface for GitHub Pages
Dependency flow: core -> app / os-agent / mcp-server -> cli

Prototype Notes

WisprFlow voice remains a prototype and is intentionally outside the shipped runtime surface.
The local AgentProtocol helper is not a distributed transport and should be treated as internal-only.