# LaunchNests Ship — Technical Architecture

> Architectural specifications for cloud coordination, Model Context Protocol (MCP) server, and local agent execution.

## 1. System Components

The LaunchNests Ship ecosystem is partitioned into three discrete layers:

```text
┌────────────────────────────────────────────────────────┐
│               CLOUD CONTROL PLANE                      │
│ - Web Dashboard (Next.js 16 App Router)                │
│ - PostgreSQL DB via Drizzle ORM                        │
│ - Playbook Engine & Relevance Scoring                  │
│ - Fast MCP Server (Remote HTTP / SSE Transport)        │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │ Model Context Protocol
                           │
┌──────────────────────────▼─────────────────────────────┐
│               LOCAL EXECUTION LAYER                    │
│ - Developer Workspace CLI (npx launchnests-ship)       │
│ - AI Agent (Claude Code / Cursor / Codex)              │
│ - Browser Automation (Chrome DevTools Protocol)        │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │ Local Browser Session
                           │
┌──────────────────────────▼─────────────────────────────┐
│               TARGET LAUNCH SITES                      │
│ - Product Hunt, SaaSHub, AlternativeTo, Uneed          │
└────────────────────────────────────────────────────────┘
```

## 2. Model Context Protocol (MCP) Tools

The LaunchNests MCP server exposes domain operations directly to your AI coding agent:

| Tool Name | Parameters | Purpose |
|---|---|---|
| `search_platforms` | `{ query?: string, category?: string }` | Filters available launch platforms by relevance and requirements |
| `get_playbook` | `{ platformId: string }` | Returns markdown and JSON submission specifications with character limits |
| `create_launch_project` | `{ name: string, productId: string }` | Initiates a distribution campaign |
| `create_launch_target` | `{ launchId: string, platformId: string }` | Links a platform target to a campaign |
| `create_submission_attempt`| `{ targetId: string }` | Creates a new attempt record with an audit timestamp |
| `update_submission` | `{ attemptId: string, status: string, payload?: object, liveUrl?: string }` | Transitions state machine and records submission data |
| `create_human_handoff` | `{ targetId: string, reason: string, instructions: string }` | Halts execution for CAPTCHA, 2FA, or human review |
| `resolve_human_handoff` | `{ handoffId: string }` | Confirms action completed by user and resumes execution |

## 3. Controlled State Machine

The submission lifecycle enforces strict state transitions:

```text
not_started ──► preparing ──► ready ──► submitting ──► submitted ──► published
                   │            │            │             │
                   ▼            ▼            ▼             ▼
                 failed    needs_human    failed       in_review ──► published
```

- **Idempotency**: Retries create new submission attempts while preserving previous attempt records.
- **Verification Rule**: Transitions to `published` require verifiable evidence (HTTP 200 on public canonical URL).

## 4. Security & Privacy Guarantees

1. **No Sensitive Credential Storage**: Cloud records contain only public product metadata. Browser cookies and authentication passwords are never transmitted.
2. **Local Session Isolation**: The agent uses the user's local browser profile, ensuring enterprise SSO, 2FA, and passkeys are handled locally.
3. **Audited Event Ledger**: Every state change generates an immutable event with timestamps, actor IDs, and payload hashes.