Skip to content

project-layout.md

Latest commit

 

History

History
111 lines (96 loc) · 4.61 KB

project-layout.md

File metadata and controls

111 lines (96 loc) · 4.61 KB

Project Layout

This document maps the repository's directory structure to the conceptual model described in Boundaries & Responsibilities.

Check the Glossary for key terms such as Layer, System, Resource, Service, et cetera.

Top-Level Directories

Directory Purpose
actors/ L2 Actor processes: agent/, cli/, worker/
config/ Configuration samples (core.yaml.sample, resources.yaml.sample, actors.yaml.sample)
docs/ Architecture & contributor documentation
host-mcp-gateway/ Go-based HTTP proxy for host-level MCP Servers
img/ Diagrams and images referenced by docs and README
lib/ Shared Python packages (see below)
prompts/ LLM prompt templates (embedding/, inference/, config/)
resources/ L0 Resource implementations
scripts/ Build/generation scripts (glossary, service-api docs)
services/ L1 Service implementations
tests/ Cross-cutting and shared test infrastructure

Services

Services follow the convention services/<system>/<service>/. The three Systems map directly to subdirectories:

services/
  state/                        # State System (Authorities)
    cache_authority/
    embedding_authority/
    memory_authority/
    object_authority/
    vault_authority/
  action/                       # Action System
    attention_router/
    capability_engine/
    language_model/
    policy_service/
    switchboard/
  control/                      # Control System
    commitment/
    ingestion/
    job/

Each Service directory contains at minimum an __init__.py with its ServiceManifest registration. A fully built-out Service (e.g. embedding_authority/) includes:

File/Dir Role
component.py ServiceManifest declaration and registration
service.py Public API class (the canonical interface)
implementation.py Internal business logic
interfaces.py Abstract interfaces / protocols
domain.py Domain models and value objects
api.py FastAPI route registrar (publishes selected SDK-facing endpoints)
data/ Data layer: schema.py, repository.py, runtime.py
migrations/ Alembic env: alembic.ini, env.py, versions/
tests/ Component-level tests

Resources

Resources follow the convention resources/<kind>/<resource>/:

resources/
  adapters/                     # Adapter Resources (external I/O)
    llm/                    # LLM gateway adapter owned by Language Model Service
  substrates/                   # Substrate Resources (state)
    postgres/                   # Shared Infrastructure (bootstrap, engine, sessions)
    qdrant/                     # Vector search backend
    seaweedfs/                  # S3-compatible blob storage backend

Each Resource exports a MANIFEST via component.py with a ResourceManifest.

Packages

Shared code lives in lib/:

Package Purpose
shared/ Cross-cutting utilities: manifest.py (Component registry), envelope/, errors/, http/ (internal HTTP wrappers), ids/ (ULID helpers), logging/, config/, embeddings.py, component_loader.py; contract conventions for these shared types are defined in Conventions
core/ Brain Core runtime (L1 Service orchestration)
sdk/ Brain Core SDK for L2 Actors (thin HTTP client over the Core Unix socket)
capability_sdk/ Capability SDK for Op/Skill registration and management

Configuration

Runtime configuration is loaded from ~/.config/brain/core.yaml, ~/.config/brain/resources.yaml, and ~/.config/brain/actors.yaml. Matching samples are provided under config/. See Configuration Reference for keys and Conventions for Pydantic contract rules.

Tests

  • tests/ contains shared test infrastructure and cross-cutting tests.
  • Component-level tests live alongside their Service in services/<system>/<service>/tests/.
  • Resource-level tests live alongside their Resource.
  • Run all tests with make test (see Development Guide).

End of Project Layout