Mission-Control/STRUCTURE.md

Mission Control Project Structure

Project Overview

Mission Control — Unified OpenClaw management platform merging three open-source dashboards into one. Python/FastAPI + PostgreSQL + Redis backend, Next.js 16 + React 19 frontend.

Source Repos (Reference Only — Not Modified Directly)

/tmp/mission-control-research/
├── openclaw-mission-control/    # Base platform (Python/FastAPI + Next.js)
├── openclaw-dashboard/          # Tracking/monitoring (Go → port to Python)
└── openclaw-pixel-agents-dashboard/  # Agent visualization (Node/Express → port to Python)

Directory Structure (Target)

Mission-Control/
├── PROJECT.md              # Full project plan, phases, architecture decisions
├── STRUCTURE.md            # THIS FILE — project structure and agent roles
├── FUTURE.md               # Pending improvements (priority-grouped)
├── HISTORY.md              # User-facing changelog (completed items only)
├── DEVELOPMENT_LOG.md      # Agent work tracking
├── VERSION.md              # Current version + history
├── src/
│   ├── backend/                    # FastAPI application
│   │   ├── app/
│   │   │   ├── main.py             # FastAPI app entry
│   │   │   ├── models/             # SQLModel/SQLAlchemy models
│   │   │   │   ├── monitoring.py   # CostSnapshot, CronJobStatus, SessionEvent, etc.
│   │   │   │   └── alert_rules.py  # AlertRule model
│   │   │   ├── api/                # API route handlers
│   │   │   │   ├── monitoring.py         # Cost, session, cron endpoints
│   │   │   │   ├── monitoring_system.py  # System health endpoints
│   │   │   │   └── agent_events.py       # WebSocket endpoint for agent events
│   │   │   ├── services/           # Business logic
│   │   │   │   ├── monitoring/
│   │   │   │   │   ├── gateway_collector.py  # Polls OpenClaw gateway
│   │   │   │   │   ├── jsonl_watcher.py      # Watches session JSONL files
│   │   │   │   │   ├── cost_tracker.py       # Cost aggregation and projection
│   │   │   │   │   └── alert_engine.py       # Alert rule evaluation
│   │   │   │   └── openclaw/
│   │   │   │       └── gateway_rpc.py         # Existing gateway RPC client
│   │   │   └── core/              # Config, auth, deps
│   │   ├── migrations/             # Alembic migrations
│   │   └── tests/                  # Backend tests
│   └── frontend/                   # Next.js 16 application
│       ├── src/
│       │   ├── app/                # Next.js App Router pages
│       │   │   ├── monitoring/
│       │   │   │   ├── page.tsx           # Main monitoring dashboard
│       │   │   │   ├── costs/page.tsx     # Cost detail page
│       │   │   │   ├── sessions/page.tsx  # Session detail page
│       │   │   │   ├── crons/page.tsx     # Cron management page
│       │   │   │   └── system/page.tsx    # System health page
│       │   │   └── agents/
│       │   │       └── pixel/page.tsx      # Pixel agent canvas page
│       │   ├── components/
│       │   │   ├── monitoring/     # CostCards, Charts, SessionTable, etc.
│       │   │   └── agents/        # PixelCanvas, AgentSprite, SpawnPanel, etc.
│       │   └── lib/
│       │       ├── monitoring-api.ts    # API client for monitoring endpoints
│       │       └── agent-events.ts     # WebSocket client for agent events
│       └── public/                  # Static assets (pixel sprites, etc.)
├── docker-compose.yml              # Dev + prod Docker Compose
├── Dockerfile                      # Container build
└── docs/                           # Documentation

Critical Notes for Agents

Backend Code Location

ALL backend code is in src/backend/:

• Entry: src/backend/app/main.py
• Models: src/backend/app/models/*.py
• API: src/backend/app/api/*.py
• Services: src/backend/app/services/**/*.py
• Migrations: src/backend/migrations/
• Gateway RPC: src/backend/app/services/openclaw/gateway_rpc.py

Frontend Code Location

ALL frontend code is in src/frontend/:

• Pages: src/frontend/src/app/**/page.tsx
• Components: src/frontend/src/components/**/*.tsx
• API client: src/frontend/src/lib/monitoring-api.ts
• WebSocket client: src/frontend/src/lib/agent-events.ts

Porting Rules

• No Go. All dashboard data collection ports to Python services.
• No Node/Express. All pixel-agents functionality ports to Python/FastAPI.
• Reuse existing gateway RPC. Mission Control already has gateway_rpc.py with 60+ methods.
• React for all UI. No embedded HTML/JS — everything becomes React components.

Agent Review Roles

Agent	Role	Focus Area
Neo	Backend / System Architecture	FastAPI services, models, migrations, gateway RPC, data collection, API endpoints
Scarlett	UI/UX / Frontend	Next.js pages, React components, Tailwind styling, pixel canvas, charts, themes
Bishop	Analysis / Code Quality	Architecture review, code quality, dependency review, version bumps, documentation
Private_Hudson	Security / Compliance	Auth flows, data protection, input validation, OWASP, dependency vulnerabilities

Cross-Cutting Concerns

All agents must be aware of:

• Auth: Clerk JWT or local bearer token — scoped to organization + gateway
• Gateway RPC: gateway_rpc.py is the single source of truth for all OpenClaw API calls
• Data Models: PostgreSQL + SQLModel with Alembic migrations
• Real-Time: WebSocket for agent events, TanStack Query polling for monitoring data
• Theme System: 6 themes with CSS variables mapped to Tailwind config

Technology Stack

Layer	Technology	Notes
Backend	Python 3.12+ / FastAPI	Existing
Database	PostgreSQL + SQLModel	Existing
Migrations	Alembic	Existing
Job Queue	Redis + RQ	Existing
Frontend	Next.js 16 + React 19	Existing
UI	Radix UI + Tailwind CSS	Existing
Charts	Recharts	Existing
Pixel Canvas	HTML5 Canvas	New — ported from pixel-agents
WebSocket	FastAPI WebSocket	New — ported from pixel-agents
Auth	Clerk / local bearer token	Existing

No new backend languages. Go and Node/Express are NOT added to this project.

---

Generated by Ripley for Mission Control project