Skip to content
Core-X Docs

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    UNIFIED UI (:5200)                        │
│      React + Three.js + Vite  (see core-x/ui/package.json)   │
│    14 adaptive modes (chat, canvas, voice, image, ...)      │
└────────────┬────────────────────────┬───────────────────────┘
             │  HTTP/WS               │  SSE
             ▼                        ▼
┌────────────────────┐   ┌─────────────────────────┐
│   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 (x8)        │
│  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)
│   └── 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/                  # 8 domain workspaces (local, not tracked in git)
│   ├── audio-lab/           # Audio experiments
│   ├── city-council/        # Governance simulations
│   ├── echopaths/           # Narrative exploration
│   ├── gen-filmaker/        # Generative filmmaking
│   ├── kbllr-kaleidoscopy-lab/
│   ├── p5-gen-labs/         # p5.js generative art
│   ├── uix-design-innovation-lab/
│   └── visual-composition-lab/
│
├── 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 tree

Tracked (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 pipeline
  • scripts/ — root automation scripts
  • model-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/ — 8 domain workspaces; registry cards go in core-x/registries/houses/
  • data-pool/ — raw media, embeddings, processed outputs
  • refinery/ — curated knowledge base
  • mlx-services/ — MLX service runtime (start-all.sh, per-service dirs, model weights)
  • clouds/, graphic-islands/, notebooks/, vendor/ — scratch / vendor dirs
  • registries/ — generated indices (rebuilt by scripts/generate-registries.py)

Large binaries (.glb, .safetensors, .gguf, .mp4, fonts, etc.) are globally gitignored regardless of directory.

Where Config Lives

ConfigCanonical PathPurpose
Service registrycore-x/config/services.manifest.jsonPort assignments, tiers, health paths
Ecosystem configcore-x/config/ecosystem.config.yamlTiers, memory profiles, startup order
UI environmentcore-x/ui/src/lib/env.tsCompile-time port/host constants
UI package depscore-x/ui/package.jsonReact, Three.js, Vite versions
JSON schemascore-x/schemas/70 schema files — ecosystem contract
Flow definitionscore-x/flows/YAML flow specs (anthology, avatar, goals, media, ops, training)
Model zoo registrymodel-zoo/registry.json188 KB master model index
House registry cardscore-x/registries/houses/Per-house capability declarations
Launcher logs.core-x-logs/Runtime logs (created by launch-core-x.sh)
Root .gitignore.gitignoreDeny-all + allow-list pattern

Single source of truth: core-x/config/services.manifest.json is canonical for ports. The root services.manifest.json is a deprecated mirror — do not edit it.