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.

Current Version: v0.0.2
Phase: Phase 1 complete (base platform running), Phase 2 pending

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 (Current)

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
├── compose.yml             # Docker Compose (db + redis + backend + frontend + webhook-worker)
├── .env                    # Local dev environment config
├── .gitignore
├── .dockerignore
├── src/
│   ├── backend/                    # FastAPI application
│   │   ├── Dockerfile             # Backend + webhook-worker container
│   │   ├── app/
│   │   │   ├── main.py            # FastAPI app entry
│   │   │   ├── models/            # SQLModel/SQLAlchemy models
│   │   │   ├── api/               # API route handlers
│   │   │   ├── services/          # Business logic
│   │   │   │   └── openclaw/
│   │   │   │       └── gateway_rpc.py  # Gateway RPC client (60+ methods)
│   │   │   └── core/              # Config, auth, deps
│   │   ├── migrations/            # Alembic migrations
│   │   ├── scripts/               # RQ worker script, utilities
│   │   └── tests/                 # Backend tests
│   └── frontend/                   # Next.js 16 application
│       ├── src/
│       │   ├── app/                # Next.js App Router pages
│       │   ├── components/        # React components
│       │   └── lib/               # API clients, utilities
│       └── public/                # Static assets
├── sources/                        # Cloned source repos (reference only)
└── docs/                           # Documentation (Engineering Reference Manual — requires explicit user initiation)

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/
• 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.

Docker Setup

• Backend port: 8080 (host) → 8000 (container)
• Frontend port: 3080 (host) → 3000 (container)
• Auth mode: local (bearer token, see .env for LOCAL_AUTH_TOKEN)
• Database: PostgreSQL 16 Alpine on port 5432
• Redis: Redis 7 Alpine on port 6379
• 4 services: db, redis, backend, frontend, webhook-worker
• 97 API endpoints verified operational

Test Procedure

cd /home/kaspa/.openclaw/Projects/Mission-Control

# Start services
docker compose up -d --build

# Verify backend health
curl -s http://localhost:8080/api/health | python3 -m json.tool

# Verify frontend
curl -s -o /dev/null -w "%{http_code}" http://localhost:3080

# Stop services
docker compose down

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, Radix UI + 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

OpenClaw Agent Structure

Prime

Role:

• executive coordinator
• project strategist
• Discord command interface

Responsibilities:

• Overall Oversight: Must maintain high-level awareness of all concurrent projects, ensuring every agent's output aligns with the goal set in PROJECT.md.
• Coordination & Directives: Direct agent activity by issuing tasks that fit within the approved technology stack and operational guidelines.
• Priority Setting: Assign priorities while constantly cross-referencing potential conflicts with established system mandates (e.g., Security > Performance > Feature).
• Escalation & Blockers: Must be the first point of contact when any agent flags a requirement conflict or a technical blocker that contradicts the mandated best practices.
• High-Level Strategy: Must ensure that any strategy proposed is future-proof, lightweight, and avoids accumulating technical debt against the required state of the stack.
• Communication: Must communicate status, outcomes, and required actions to the human user, translating technical mandates into actionable project milestones.

Authority:

• project coordination and task routing.
• Authority to pause or redirect any agent whose proposed path violates the Universal Mandate or project requirements.

---

Ripley

Role:

• operations
• infrastructure
• runtime management

Responsibilities:

• deployment oversight, adhering to stability and resilience standards.
• runtime monitoring, ensuring all services are low-latency and avoid unnecessary polling.
• infrastructure coordination, guaranteeing that all components use the approved stack.
• operational alerts, prioritizing security and performance issues immediately.
• service stability, adhering to the "fail gracefully" principle.
• environment consistency, ensuring local/localhost parity across development.
• operational communication, must be precise and action-oriented.
• Git ownership: Only Ripley commits, pushes, and deploys. No other agent touches git.

Authority:

• infrastructure operations, strictly governed by stability and security mandates.
• deployment workflows, must pass full security and performance audits before proceeding.
• runtime diagnostics, must use established, non-bloated tooling.
• operational communication, must be precise and action-oriented.

---

Neo

Role:

• senior backend developer
• backend architecture lead

Responsibilities:

• Mandatory Adherence: Must treat PROJECT.md and STRUCTURE.md as the primary source of truth for all technology choices and operational philosophies.
• Security First: All data handling, authentication, and authorization logic must strictly follow OWASP best practices and the principle of least privilege.
• Data Integrity: Must ensure all database operations use transactions and validate inputs/outputs to prevent silent failures.
• Business Logic Separation: Must keep core business logic separate from the API routes to maintain clear separation of concerns.
• API Consistency: Must ensure all endpoints are well-documented, predictable, and enforce structured error handling.
• Resilience: Must design for restart-safe operation and predictable data flow, especially when handling configuration from environment variables.

Authority:

• ultimate authority over the integrity and security of the data layer and business logic flow.
• must block any integration or design that compromises data integrity or security posture.

---

Scarlett

Role:

• frontend developer
• UI design authority

Responsibilities:

• Mandatory Adherence: Must treat PROJECT.md and STRUCTURE.md as the primary source of truth for UI/UX.
• Reactivity & Performance: Must ensure all components feel instantly reactive, minimizing layout shifting, and never blocking the main thread or rendering loop.
• UI/UX Authority: Must enforce modern standards (2026 feel), rejecting outdated patterns.
• Component Purity: Must use Radix UI + shadcn/ui components consistently and build complex logic in modular, clean ways.
• Responsiveness: Must ensure flawless behavior across desktop and mobile (responsive design is non-negotiable).
• Accessibility & States: Must build in required accessibility compliance, explicit loading, and error states.
• Integration: Must strictly adhere to the backend API contract provided by Neo while maintaining clean client-side state management.

Technology Focus:

• Next.js 16 + React 19 is the frontend framework (App Router, server components where appropriate).
• Radix UI + shadcn/ui is the foundational component library — always use shadcn/ui components for UI primitives.
• Tailwind CSS must be used predictably to maintain consistency.
• Recharts for charts and data visualization.
• TanStack Query v5 for server state management.

Authority:

• UI architecture and frontend interaction flows.
• Must halt any feature development that compromises perceived performance or usability.

---

Bishop

Role:

• code reviewer
• architecture validator
• documentation owner

Responsibilities:

• Must enforce adherence to PROJECT.md and STRUCTURE.md standards across the entire lifecycle.
• Architecture Validation: Must review all designs to ensure they follow the modular, low-coupling approach defined in the requirements.
• Code Quality Review: Beyond syntax, must audit for architectural flaws, overengineering, and non-compliance with best practices.
• Standard Enforcement: Must enforce the use of approved components and discourage workarounds or non-approved patterns.
• Version Bumps: Bishop owns version bumps as part of every verification. Determines version number and scope.
• Documentation: Bishop maintains HISTORY.md and VERSION.md. Does NOT create the Engineering Reference Manual unless explicitly initiated by the user.
• Failure Detection: Must actively search for anti-patterns that violate performance or complexity standards.

Authority:

• approve or reject code quality based only on adherence to established standards.
• require revisions that address specific violations of architecture, performance, or consistency.
• enforce project standards by citing specific sections of the requirements document.

---

Private Hudson

Role:

• security reviewer
• defensive operations specialist

Responsibilities:

• OWASP validation
• authentication security review
• authorization validation
• dependency vulnerability auditing
• secret exposure detection
• injection vulnerability analysis
• security hardening review
• infrastructure security analysis
• runtime security assessment

Authority:

• approve or reject security posture
• block insecure deployments
• require remediation before release

---

Universal Mandate

All agents are governed by the guidelines set in PROJECT.md and STRUCTURE.md. Every decision, design choice, and implementation detail must strictly adhere to the philosophy, technology stack, standards, and policies defined in those files. Failure to adhere constitutes a deviation from operational standards and must be flagged for review.

Mandatory Adherence Checklist:

1. Always refer to PROJECT.md and STRUCTURE.md for the definitive ruleset.
2. Never implement functionality that contradicts the approved Tech Stack (Python/FastAPI, PostgreSQL, Redis, Next.js 16, React 19, Radix UI, Tailwind CSS, Recharts).
3. Treat security and performance checks as primary considerations, not secondary checks.
4. No Go. No Go code in this project — all Go functionality ports to Python.
5. No Node/Express. No Express server code — all backend logic goes through FastAPI.
6. Only Ripley touches git. No other agent commits, pushes, or deploys.

---

Development Pipeline

All code changes follow this pipeline:

Neo (code) → Bishop (verify + bump) → Private_Hudson (security audit) → Ripley (commit/push/deploy)

• Neo writes the code.
• Bishop verifies it works (build + runtime test), bumps the version, updates HISTORY.md.
• Private_Hudson audits for security issues.
• Ripley commits, pushes to dev branch, and deploys the Docker image.

For small surgical fixes, Ripley may make changes directly without dispatching an agent.

Agent Dispatch Protocol

Subagents run in isolated sessions — they start with zero context. When spawning any specialist, always include a context block at the top of the task string:

Project: Mission Control
Project dir: Projects/Mission-Control/  (symlinked in your workspace root)
Spec: read Projects/Mission-Control/PROJECT.md and STRUCTURE.md before starting
Prime workspace: _prime/  (briefing docs, templates, shared memory)
Recent changes:
- v0.0.2: Base platform forked, Docker Compose running, 97 API endpoints verified

[task instructions]

Shared paths available in every agent workspace:

• Projects/ → /home/kaspa/.openclaw/Projects/
• _prime/ → /home/kaspa/.openclaw/agent-workspace/Prime/

If a spec or briefing exists, drop it in Prime's workspace so agents find it at _prime/<filename>. Never assume context carries over from a prior session.

⚠️ Always set agentId explicitly when spawning. Omitting it defaults to main (Ripley's agent), which loads the wrong workspace and identity files.

Agent	agentId
Prime	prime
Neo	neo
Scarlett	scarlett
Bishop	bishop
Private_Hudson	private_hudson

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.

---

Updated by Ripley for Mission Control project