# 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*