128 lines
6.7 KiB
Markdown
128 lines
6.7 KiB
Markdown
# 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* |