System Architecture
┌──────────────────────────────────────────────────────────────┐│ SPACEBOT (Orchestrator) ││ Rust backend │ MCP client │ Studio + Stories UI (React) │└────────┬──────────────────┬──────────────────┬───────────────┘ │ MCP stdio │ MCP stdio │ HTTP ▼ ▼ ▼┌─────────────────┐ ┌─────────────────┐ ┌──────────────────────┐│ NARRATIVE MCP │ │ STORIES MCP │ │ CORE-X UNIFIED UI ││ screenplay │ │ voice-blog / │ │ (:5200) React+Three ││ planning + │ │ episode render │ │ 14 adaptive modes ││ render + audio │ │ audio + video │ │ │└───────┬─────────┘ └───────┬─────────┘ └──────────┬───────────┘ │ │ │ └─────────┬─────────┘ │ ▼ │┌──────────────────────────────────────┐ ││ MEDIA RUNTIME (shared) │ ││ TtsRuntime │ FrameRuntime │ ││ VideoRuntime │ VoiceResolver │ ││ MediaJobStore │ │└───────┬──────────────┬───────────────┘ │ │ │ │ ▼ ▼ │┌────────────────────┐ ┌─────────────────────────┐│ GATEWAY (:8090) │ │ EVENT BUS (:8085) ││ Unified API │ │ SSE pub/sub (A2A) ││ OpenResponses │ │ Agent-to-Agent comms │└──┬──┬──┬──┬──┬──┬──┘ └─────────────────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼┌──────────────────────────────────────────────────┐│ MLX SERVICE MESH ││ ││ CORE mlx-llm (:8091) mlx-rag (:8092) ││ STANDARD mflux (:8083) audio (:8093) ││ embed (:8095) ││ FULL vision (:8094) said (:8096) ││ video (:8084) │└──────────────────────────────────────────────────┘ │ ▼┌──────────────────────────────────────────────────┐│ REGISTRIES + SCHEMAS + CONFIG ││ services.manifest.json │ ecosystem.config.yaml ││ 70 JSON schemas │ model-zoo/registry.json │└──────────────────────────────────────────────────┘ │ ▼┌──────────────────────────────────────────────────┐│ DATA POOL │ REFINERY │ HOUSES (x24) ││ raw media │ curated │ domain workspaces ││ embeddings │ knowledge │ independent repos │└──────────────────────────────────────────────────┘Repository Layout
core-x-kbllr_0/├── core-x/ # Architecture backbone (tracked in git)│ ├── cli/ # Terminal TUI (Rich + InquirerPy)│ ├── config/ # Master configs (ecosystem.config.yaml, services.manifest.json, ...)│ ├── event_bus/ # FastAPI SSE pub/sub server│ ├── flows/ # YAML flow definitions (anthology, avatar, goals, media, ops, training)│ ├── lib/ # Shared runtime (Python + TypeScript): a2a, openresponses, registry│ ├── orchestrators/ # Prompt + orchestrator pairs (Anja)│ ├── pipelines/ # Automated data flows (run_all.py, knowledge_builder, etc.)│ ├── schemas/ # 70 JSON schemas — ecosystem contract│ ├── scripts/ # Operational scripts (event bus, validation, anthology, avatar, ...)│ ├── skills/ # 20 shared skill domains (meta, rag-query, mlx-chat, ...)│ ├── templates/ # Scaffolding for agents, flows, houses, skills│ ├── ui/ # Unified adaptive interface (Vite + React + Three.js)│ ├── narrative_mcp/ # MCP server: screenplay narrative planning + rendering + audio│ ├── stories_mcp/ # MCP server: voice-blog / episode pipeline (audio + video)│ ├── media_runtime/ # Shared media layer (TTS, frames, video, voice resolver)│ └── docs/ # Architecture documentation│├── corex-cli-v2/ # NEW: Rich TUI video analysis pipeline (Python, Typer, httpx)│├── mlx-services/ # MLX service runtime (start-all.sh, per-service dirs)│ └── var/ # Runtime data│├── houses/ # 24 domain workspaces (local, not tracked in git)│ ├── avatar-labs/ # Digital humans, voice registry, TalkingHead│ ├── project-anja/ # Voice assistant (avatar + SAiD integration)│ ├── audio-lab/ # Audio experiments│ ├── gen-filmaker/ # Generative filmmaking│ ├── emergence-lab/ # Creative AI workspace (shipped, Vercel)│ ├── smart-campus/ # IoT digital twin (shipped)│ ├── visual-composition-lab/ # 3D composition (shipped)│ ├── moonsyc/ # Music intelligence (shipped)│ ├── git-stars/ # Developer tools, repo analytics (shipped)│ ├── code-platformer-AI/ # Multiplayer game (WebGPU)│ ├── memory-labs/ # 3D geospatial│ ├── flash-ui-mlx/ # Design prototyping│ ├── label-forge/ # Design tooling│ ├── le-belle-epoch/ # Content publishing│ ├── htdi-project/ # Creative coding│ ├── flirtcopilot/ # Browser extension│ ├── echopaths/ # Narrative geospatial│ ├── city-council/ # Governance simulations│ ├── agent-avenue/ # Agent research│ ├── uix-design-innovation-lab/ # UI prototyping│ ├── Leagentdiary/ # Agent version control│ ├── gembooth/ # AI studio (scaffold)│ ├── kbllr-kaleidoscopy-lab/ # Portfolio (legacy)│ └── p5-gen-labs/ # p5.js generative art (legacy)│├── model-zoo/ # Model registry, cards, contracts, metadata│ ├── registry.json # 188 KB master registry│ ├── cards/ # 9 model cards│ └── scripts/ # validate_registry.py, etc.│├── registries/ # Generated indices (flows.registry.json)├── anthology/ # Documentation, research reports, wikis├── scripts/ # Root automation (launcher, generators, tests, audits)│├── launch-core-x.sh # Main dev launcher (start/stop/status)├── services.manifest.json # Deprecated mirror → canonical: core-x/config/services.manifest.json├── AGENTS.md # Navigation guide + port map├── RULES.md # Operational rules + hardware contract└── SITEMAP.md # Auto-generated directory treeTracked (enforced by .gitignore)
The root .gitignore uses a deny-all / allow-list pattern (/* ignores everything, then !path/ un-ignores tracked dirs). Only these top-level entries are tracked in git:
core-x/— architecture backbone (config, schemas, UI, scripts, flows, skills)corex-cli-v2/— Rich TUI video analysis pipelinescripts/— root automation scriptsmodel-zoo/— registry + metadata only (models themselves are gitignored)anthology/— directory structure + READMEs only (content gitignored)launch-core-x.sh,AGENTS.md,RULES.md,SITEMAP.md,PROJECT_GUIDE.md
Local-only (not tracked, lives on disk)
These directories exist locally but are never committed:
houses/— 24 domain workspaces; registry cards go incore-x/registries/houses/data-pool/— raw media, embeddings, processed outputsrefinery/— curated knowledge basemlx-services/— MLX service runtime (start-all.sh, per-service dirs, model weights)clouds/,graphic-islands/,notebooks/,vendor/— scratch / vendor dirsregistries/— generated indices (rebuilt byscripts/generate-registries.py)
Large binaries (
.glb,.safetensors,.gguf,.mp4, fonts, etc.) are globally gitignored regardless of directory.
Where Config Lives
| Config | Canonical Path | Purpose |
|---|---|---|
| Service registry | core-x/config/services.manifest.json | Port assignments, tiers, health paths |
| Ecosystem config | core-x/config/ecosystem.config.yaml | Tiers, memory profiles, startup order |
| UI environment | core-x/ui/src/lib/env.ts | Compile-time port/host constants |
| UI package deps | core-x/ui/package.json | React, Three.js, Vite versions |
| JSON schemas | core-x/schemas/ | 70 schema files — ecosystem contract |
| Flow definitions | core-x/flows/ | YAML flow specs (anthology, avatar, goals, media, ops, training) |
| Model zoo registry | model-zoo/registry.json | 188 KB master model index |
| MCP server registry | core-x/config/mcp-servers.json | Narrative + Stories MCP tool/env config |
| Video presets | core-x/config/presets/video-ltx2.json | LTX-2 pipeline presets |
| House registry cards | core-x/registries/houses/ | Per-house capability declarations |
| Launcher logs | .core-x-logs/ | Runtime logs (created by launch-core-x.sh) |
Root .gitignore | .gitignore | Deny-all + allow-list pattern |
Single source of truth:
core-x/config/services.manifest.jsonis canonical for ports. The rootservices.manifest.jsonis a deprecated mirror — do not edit it.