# rafalapenta/ephemeral-agents architecture

> Architecture diagram of the GitHub repository rafalapenta/ephemeral-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rafalapenta/ephemeral-agents
- Repository: https://github.com/rafalapenta/ephemeral-agents

## Overview

AGency is a multi-agent orchestration platform: a task is accepted, tracked, routed to a matching agent with authorized tools, handed off, and recorded in persistent state. The dashboard and FastMCP clients are documented entry points; the README also describes memory, scheduling, and a skills registry. The excerpts establish the orchestration, routing, catalog, and state relationships. Dashboard-to-API details and some documented subsystems are not shown in source excerpts, so those links are omitted rather than inferred.

Main entry points: [`src/macro_agents/orchestrator.py`](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/macro_agents/orchestrator.py) (Task orchestrator), [`src/catalog/indexer.py`](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/catalog/indexer.py) (Agent catalog indexer), [`server.py`](https://github.com/rafalapenta/ephemeral-agents/blob/main/server.py) (FastAPI server), [`src/router/semantic.py`](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/router/semantic.py) (Semantic router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entry points"]
  node_dashboard["Web dashboard<br/>[app.js]"]
  node_mcp_clients["Agent clients"]
  node_api_server["FastAPI server<br/>[server.py]"]
end

subgraph group_workflow["Task orchestration"]
  node_macro["Task orchestrator<br/>[orchestrator.py]"]
  node_kanban["Kanban lifecycle<br/>[kanban.py]"]
  node_context["Context compressor<br/>[context.py]"]
end

subgraph group_routing["Agent registry and routing"]
  node_semantic_router["Semantic router<br/>[semantic.py]"]
  node_catalog_indexer["Agent catalog indexer<br/>[indexer.py]"]
  node_catalog_models["Catalog models<br/>[models.py]"]
  node_catalog_schemas["Catalog schemas<br/>[schemas.py]"]
  node_catalog_db[("Relational catalog")]
  node_vector_store[("Vector index")]
end

subgraph group_state["Persistent state and memory"]
  node_state_manager["State manager<br/>[manager.py]"]
  node_merge_patch["Merge-patch logic<br/>[merge_patch.py]"]
  node_memory[("Persistent memory search<br/>[memory_search.py]")]
end

subgraph group_capabilities["Product capabilities"]
  node_scheduler["Task scheduler<br/>[scheduler.py]"]
  node_skills["Skills registry"]
end

node_requester(("Dashboard or agent client"))

node_requester -->|"uses"| node_dashboard
node_requester -->|"uses"| node_mcp_clients
node_dashboard -.->|"accesses"| node_api_server
node_api_server -.->|"dispatches"| node_macro
node_api_server -->|"uses"| node_memory
node_api_server -->|"uses"| node_scheduler
node_macro -->|"creates and transitions"| node_kanban
node_macro -->|"persists state"| node_state_manager
node_macro -->|"routes task"| node_semantic_router
node_macro -.->|"compresses context"| node_context
node_semantic_router -->|"queries"| node_catalog_db
node_semantic_router -->|"searches"| node_vector_store
node_catalog_indexer -->|"persists catalog"| node_catalog_db
node_catalog_indexer -->|"persists vectors"| node_vector_store
node_catalog_indexer -->|"creates records"| node_catalog_models
node_catalog_indexer -->|"validates entries"| node_catalog_schemas
node_state_manager -->|"applies patches"| node_merge_patch

click node_dashboard "https://github.com/rafalapenta/ephemeral-agents/blob/main/dashboard/app.js"
click node_api_server "https://github.com/rafalapenta/ephemeral-agents/blob/main/server.py"
click node_macro "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/macro_agents/orchestrator.py"
click node_kanban "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/orchestration/kanban.py"
click node_context "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/orchestration/context.py"
click node_semantic_router "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/router/semantic.py"
click node_catalog_indexer "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/catalog/indexer.py"
click node_catalog_models "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/database/models.py"
click node_catalog_schemas "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/database/schemas.py"
click node_state_manager "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/state/manager.py"
click node_merge_patch "https://github.com/rafalapenta/ephemeral-agents/blob/main/src/state/merge_patch.py"
click node_memory "https://github.com/rafalapenta/ephemeral-agents/blob/main/brain/memory_search.py"
click node_scheduler "https://github.com/rafalapenta/ephemeral-agents/blob/main/scheduler/scheduler.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_mcp_clients,node_api_server,node_requester toneBlue
class node_macro,node_kanban,node_context toneAmber
class node_semantic_router,node_catalog_indexer,node_catalog_models,node_catalog_schemas,node_catalog_db,node_vector_store toneMint
class node_state_manager,node_merge_patch,node_memory toneRose
class node_scheduler,node_skills toneIndigo
```

## Components

### Product entry points

- [Web dashboard](https://github.com/rafalapenta/ephemeral-agents/blob/main/dashboard/app.js): `dashboard/app.js`
- **Agent clients**
- [FastAPI server](https://github.com/rafalapenta/ephemeral-agents/blob/main/server.py): `server.py`

### Task orchestration

- [Task orchestrator](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/macro_agents/orchestrator.py): `src/macro_agents/orchestrator.py`
- [Kanban lifecycle](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/orchestration/kanban.py): `src/orchestration/kanban.py`
- [Context compressor](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/orchestration/context.py): `src/orchestration/context.py`

### Agent registry and routing

- [Semantic router](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/router/semantic.py): `src/router/semantic.py`
- [Agent catalog indexer](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/catalog/indexer.py): `src/catalog/indexer.py`
- [Catalog models](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/database/models.py): `src/database/models.py`
- [Catalog schemas](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/database/schemas.py): `src/database/schemas.py`
- **Relational catalog**
- **Vector index**

### Persistent state and memory

- [State manager](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/state/manager.py): `src/state/manager.py`
- [Merge-patch logic](https://github.com/rafalapenta/ephemeral-agents/blob/main/src/state/merge_patch.py): `src/state/merge_patch.py`
- [Persistent memory search](https://github.com/rafalapenta/ephemeral-agents/blob/main/brain/memory_search.py): `brain/memory_search.py`

### Product capabilities

- [Task scheduler](https://github.com/rafalapenta/ephemeral-agents/blob/main/scheduler/scheduler.py): `scheduler/scheduler.py`
- **Skills registry**

### Other components

- **Dashboard or agent client**

## Connections

- Dashboard or agent client → Web dashboard: uses (evidence: `README.md`)
- Dashboard or agent client → Agent clients: uses (evidence: `README.md`)
- Web dashboard → FastAPI server: accesses
- FastAPI server → Task orchestrator: dispatches
- FastAPI server → Persistent memory search: uses (evidence: `server.py`)
- FastAPI server → Task scheduler: uses (evidence: `server.py`)
- Task orchestrator → Kanban lifecycle: creates and transitions (evidence: `src/macro_agents/orchestrator.py`)
- Task orchestrator → State manager: persists state (evidence: `src/macro_agents/orchestrator.py`)
- Task orchestrator → Semantic router: routes task (evidence: `src/macro_agents/orchestrator.py`)
- Task orchestrator → Context compressor: compresses context (evidence: `src/macro_agents/orchestrator.py`)
- Semantic router → Relational catalog: queries (evidence: `src/router/semantic.py`)
- Semantic router → Vector index: searches (evidence: `src/router/semantic.py`)
- Agent catalog indexer → Relational catalog: persists catalog (evidence: `src/catalog/indexer.py`)
- Agent catalog indexer → Vector index: persists vectors (evidence: `src/catalog/indexer.py`)
- Agent catalog indexer → Catalog models: creates records (evidence: `src/catalog/indexer.py`)
- Agent catalog indexer → Catalog schemas: validates entries (evidence: `src/catalog/indexer.py`)
- State manager → Merge-patch logic: applies patches (evidence: `src/state/manager.py`)
