Skip to content

05 — Solution Layout

The navigation map. Use it to find where things live before you open §06 — Key Services, §07 — MCP Architecture, or §08 — Templates for the depth.

The repository holds two coexisting realities. One is the .NET solution — server, shared library, a console run monitor, plus a test project and a benchmarks project — together with the React web client that the server serves. The other is the infrastructure around it — Docker compose files, helper scripts, the persistent context layer (.memory/), the existing documentation under docs/, and the parallel MkDocs effort you are reading now. The rest of this section walks both halves top-down.

The repository top level

Aetherium-core/
├── .claude/               # IDE/editor agent configuration
├── .github/               # CI workflows and issue templates
├── .handoffs/             # Per-session handoff documents
├── .memory/               # Persistent project-context layer
├── .vscode/               # VS Code workspace settings
├── Aetherium_Refactor/    # The .NET solution
├── docker/                # Containerized auxiliary services
├── docs/                  # Pre-existing developer and operator documentation
├── openclaw-martin-skill/ # Skill bundle for a specific agent workstream
├── scripts/               # Cross-platform deployment and sync scripts
├── CLAUDE.md              # Project-wide instructions for Claude Code
├── README.md              # Top-level project overview
├── docker-compose.yml     # The primary multi-service compose file
└── start-aetherium-linux.sh
Entry Purpose
Aetherium_Refactor/ The .NET solution. Server, client, shared library, tests, benchmarks.
docker/ Auxiliary compose files for optional services (e.g., SearxNG). Companion to the top-level docker-compose.yml.
docs/ Long-standing developer and operator documentation that has grown with the Engine. Authoritative for current operations.
docs/Documentation/ The parallel MkDocs documentation effort (the doc set you are reading now). Lives inside docs/ but is built and served separately.
scripts/ Cross-platform deployment scripts — Postgres and ChromaDB sync helpers, deploy.sh.
.memory/ The persistent context layer — see the subsection below.
.handoffs/ Long-lived handoff documents from prior workstreams. The persistent companion to .memory/ — see the subsection below.
openclaw-martin-skill/ A skill bundle tied to a specific agent workstream.
CLAUDE.md Project-wide instructions consumed by Claude Code.
README.md The repo's front door.
docker-compose.yml The primary compose file — PostgreSQL, ChromaDB, supporting services.
start-aetherium-linux.sh The one top-level lifecycle script; see the script subsection below.

The .NET solution

Aetherium_Refactor/ contains the entire .NET solution: a server, a shared library, and a console run monitor, plus a test project and a benchmarks project. The solution file is Aetherium_Refactor.slnx. The web client lives beside them in Aetherium.Web/ but is not a .NET project — it is built by its own toolchain into the server's wwwroot/app.

A note on the solution file. The Engine uses the newer .slnx format. dotnet build and dotnet watch work either against Aetherium_Refactor.slnx or against a specific .csproj, but dotnet publish against the .slnx does not invoke the server's Publish target — always target the server .csproj directly when publishing. Mechanics in §10 — Development Workflow; first-run context in §02 — Getting Started.

Aetherium_Refactor — the server project

The ASP.NET Core backend. Hosts the orchestrator, MCP server classes, controllers, SignalR hubs, and EF Core data layer.

Aetherium_Refactor/
├── Controllers/       # REST API endpoints
├── Data/              # AetheriumDbContext and EF Core configuration
├── Hubs/              # SignalR hubs for real-time streams
├── McpServers/        # MCP server classes that expose tools to agents
├── Middleware/        # Cross-cutting request pipeline components
├── Migrations/        # EF Core database migrations
├── Properties/        # launchSettings.json and project metadata
├── Services/          # The business-logic core (orchestrator, scheduler, etc.)
├── Templates/         # Embedded Workflow Template JSON files
├── config/            # Auxiliary runtime configuration
├── wwwroot/           # Static assets served to the browser
├── Program.cs         # Composition root — DI, middleware, route mapping
├── appsettings.json   # Default configuration
├── appsettings.Development.json
├── appsettings.Linux.json
├── appsettings.Local.json
└── Aetherium_Refactor.csproj
Directory What lives there
Controllers/ REST endpoints. The thin layer that turns HTTP requests into service calls.
Services/ The orchestrator, scheduler, context manager, LLM client, and every other long-lived service. The depth lives in §06.
McpServers/ The MCP server classes — workspace, shell, research, knowledge, quality, planning, communication, orchestration, team messaging, ComfyUI. Depth in §07.
Hubs/ SignalR hubs for streaming notifications, project runs, container logs, and team state.
Data/ AetheriumDbContext and EF Core entity configuration.
Migrations/ EF Core migrations. Generated and applied with dotnet ef.
Templates/ The Workflow Template JSON files embedded into the server build. Depth in §08.
Middleware/ Authentication, request logging, exception handling.
config/ Auxiliary runtime configuration files referenced by services.
wwwroot/ Static assets served directly by the server, including app/ — the compiled React client.

Aetherium.Web — the React client

The interactive UI. React with TypeScript, built by Vite, compiled into the server's wwwroot/app and served by the same host at /app. It is not part of the .slnx and dotnet build does not build it — see §10 — Development Workflow for the build order, which is load-bearing.

Aetherium.Web/
├── src/
│   ├── api/           # generated OpenAPI types + a thin typed fetch wrapper
│   ├── agui/          # the run event contract: decode, SSE stream, pure fold
│   ├── cards/         # the renderer registry and one component per card kind
│   ├── chat/          # the transcript and its message grouping
│   ├── design/        # the team designer's graph model and nodes
│   ├── live/          # approvals and the monitor's live feed
│   ├── routes/        # one file per screen
│   ├── trajectory/    # the shared run ledger, used live and on replay
│   ├── ui/            # the shell, the project bar, and the component kit
│   ├── lib/           # agent colours (ported from C#), theme, data loading
│   └── styles/        # the ported design tokens and the Tailwind bridge
├── package.json
└── vite.config.ts
Directory What lives there
routes/ One file per screen. Each is a top-level UI surface.
api/ schema.d.ts is generated from the server's OpenAPI document — nothing here hand-mirrors a server DTO.
agui/ The run event stream: a tolerant decoder, the SSE client, and a pure fold from events to rows.
cards/ The renderer registry — a map from card kind to component, with a generic fallback so an unknown kind degrades instead of crashing.
trajectory/ The ledger component shared by the live run viewer and the replay viewer, because a run in progress and a finished run are the same thing.
ui/ The application shell, the per-project navigation bar, and the shared surfaces (cards, badges, empty states).

Aetherium.Shared — the cross-tier library

The types referenced by both server and client. Keep this lean — anything that needs only one side belongs in that side's project.

Aetherium.Shared/
├── Configuration/     # Strongly-typed configuration option classes
├── Constants/         # Shared constants (event names, header keys, etc.)
├── DTOs/              # Data-transfer objects used across the API boundary
├── Interfaces/        # Contracts implemented on the server, consumed on both sides
├── Models/            # Domain models — Project, Role, TeamConfig, and so on
├── Services/          # Shared service abstractions
├── Utilities/         # Pure helpers
└── Aetherium.Shared.csproj
Directory What lives there
Models/ Domain entities and configuration objects.
DTOs/ Data-transfer objects shaped for the API surface.
Interfaces/ Service contracts shared between server and client.
Configuration/ Option classes bound from appsettings.json. Details in §09 — Configuration.
Constants/ Shared string constants — SignalR event names, header keys, well-known IDs.
Services/ Service abstractions that both tiers reference.
Utilities/ Pure helper functions with no infrastructure dependencies.

The .memory/ discipline

.memory/ is the persistent context layer that bridges sessions. It records what shipped, what is in flight, and what was learned, so the next session — human or agent — picks up without rebuilding the picture. Both Claude Code and the humans on the project write here.

Four files are canonical. Everything else in .memory/ is session notes and per-arc records orbiting these four.

File What it holds
activeContext.md The current state of the project: what shipped last, what is in flight, what is queued next. The freshest single source of "where are we."
progress.md The chronological log of completed work, organized by session or by feature arc.
systemPatterns.md Recurring architectural patterns, gotchas learned the hard way, conventions earned through experience.
productContext.md The long-lived product framing: who the Engine is for, what it does, and what it explicitly is not.

Update these at session end. Treat them as the closest thing to a single source of truth on "where the project is right now" — the codebase shows what exists; the memory files tell you why and what is next.

The .handoffs/ directory is the transactional companion — long-lived handoff documents from prior workstreams that need to outlive their session. Memory is durable; handoffs are episodic. Newer workstreams sometimes co-locate their handoffs with the work itself rather than centralizing in .handoffs/ — the documentation effort you are reading uses docs/Documentation/ for its per-section handoffs, for instance.

Supporting directories

docker/ and docker-compose.yml

The top-level docker-compose.yml defines the primary multi-service stack — PostgreSQL, ChromaDB, and supporting services. The docker/ subdirectory holds auxiliary compose files for optional add-ons (currently docker-compose.searxng.yml for self-hosted web search). First-run startup in §02 — Getting Started; production shape in §14 — Deployment.

scripts/ and the top-level lifecycle scripts

Two locations. One top-level script remains for running by hand — start-aetherium-linux.sh, which sets the storage environment variables, checks dependencies, and starts the Engine on Linux. The seven PowerShell lifecycle scripts that used to sit beside it (start, restart, health check, seed, integrity check, archive, API smoke) were removed on 2026-09-09; they described a Windows dev launch the Engine's deployment never used.

The scripts/ subdirectory holds deployment and data-sync helpers — deploy.sh, plus sync-chroma.{ps1,sh} and sync-db.{ps1,sh} for moving ChromaDB collections and PostgreSQL state between machines.

docs/ and docs/Documentation/

The docs/ directory holds the pre-existing developer and operator documentation that has grown with the Engine — USER_GUIDE.md, DEVELOPMENT.md, CONFIGURATION.md, API_REFERENCE.md, orchestration-internals.md, and others. Authoritative for current operations. A separate, parallel documentation effort lives at docs/Documentation/ — that is the doc set you are currently reading, built with MkDocs Material and aimed at developers evaluating or extending the Engine. The two surfaces coexist; neither obsoletes the other.

Tests

Path Framework What it covers
Aetherium_Refactor/Aetherium_Refactor.Tests/ xUnit Unit and integration tests for server services, controllers, MCP servers, the tool-card builders, and the live event contract.
Aetherium_Refactor/Aetherium.Web/src/ bun test Client tests, colocated with what they cover — the event fold, message grouping, the graph model, approvals.

Where common things live

When you are hunting for a specific kind of file, this is the table to scan.

Looking for Where to look
An MCP server class Aetherium_Refactor/Aetherium_Refactor/McpServers/
A Workflow Template Aetherium_Refactor/Aetherium_Refactor/Templates/
A controller Aetherium_Refactor/Aetherium_Refactor/Controllers/
A SignalR hub Aetherium_Refactor/Aetherium_Refactor/Hubs/
A long-lived service Aetherium_Refactor/Aetherium_Refactor/Services/
A database migration Aetherium_Refactor/Aetherium_Refactor/Migrations/
A screen in the web client Aetherium_Refactor/Aetherium.Web/src/routes/
A reusable UI component Aetherium_Refactor/Aetherium.Web/src/ui/
A tool-result card renderer Aetherium_Refactor/Aetherium.Web/src/cards/
A model or DTO shared by both tiers Aetherium_Refactor/Aetherium.Shared/Models/ or Aetherium_Refactor/Aetherium.Shared/DTOs/
A configuration option class Aetherium_Refactor/Aetherium.Shared/Configuration/
A unit or component test Aetherium_Refactor/Aetherium_Refactor.Tests/
A benchmark Aetherium_Refactor/Aetherium.Benchmarks/
Brand assets used by this doc set docs/Documentation/content/assets/

Where to go next