# aegisaifoundation/aegis architecture

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

- Interactive diagram: https://gitdiagram.com/aegisaifoundation/aegis
- Repository: https://github.com/aegisaifoundation/aegis

## Overview

1. **What this repo actually contains**
   - The codebase is currently a **Node/TypeScript CLI + terminal UI application** called AEGIS Core.
   - The README describes a much larger federated medical AI vision, but the checked-in code here is the **local control plane**: startup, configuration, terminal UX, agent scaffolding, and tool abstractions.

2. **Top-level execution path**
   - The runtime entrypoint is `aegis-core/bin/aegis.js`, which boots the compiled app from `aegis-core/dist`.
   - Source lives under `aegis-core/src`, and the compiled JavaScript is committed in `aegis-core/dist`, so the repo supports both source development and packaged execution.

3. **CLI and command boundary**
   - `src/commands/index.ts` is the command routing layer behind the CLI verbs mentioned in the README: launch/start/configure/uninstall.
   - This layer is the first policy boundary: it decides whether the user can enter the TUI, whether local configuration exists, and which setup or cleanup action to run.

4. **Terminal UI subsystem**
   - `src/terminal/App.tsx` and `src/terminal/Dashboard.tsx` form the interactive terminal experience.
   - `art.ts` provides branding/ASCII art for the TUI.
   - This layer is presentation-only and sits above the core agent/tool logic; it likely renders status, identity, and operational state rather than performing the work itself.

5. **Agent orchestration layer**
   - `src/agent/index.ts` is the main orchestration module for the “agent” concept.
   - Based on the README and surrounding modules, this layer owns the current runtime persona/role and coordinates actions between the terminal UI, memory, and tools.

6. **Tooling subsystem**
   - `src/tools/` contains the capability boundary:
     - `FileTool.ts` for filesystem access
     - `SystemTool.ts` for environment/system actions
     - `MemoryTool.ts` for persistence and retrieval of local state
     - `TerminalTool.ts` for interacting with the TUI/terminal context
   - `src/tools/index.ts` likely aggregates and exports these tools for the agent layer.
   - In architecture terms, the agent does not directly do everything; it delegates through these tools.

7. **Local state and memory**
   - `src/memory/index.ts` is the local memory subsystem.
   - The repository also includes `.memory/default.json`, which looks like a seeded/default state file.
   - This is the persistent knowledge layer for the CLI experience, separate from user configuration and separate from runtime process memory.

8. **Configuration and identity**
   - `src/config/index.ts` manages local configuration, and the README states the CLI stores installation state in `~/.aegis/config.json`.
   - This is where agent identity and role are configured before the TUI can launch.
   - Configuration is therefore a prerequisite for runtime, not just a convenience setting.

9. **Shared data model layer**
   - `src/models/index.ts` holds shared types or domain models used across agent, tools, config, and memory.
   - This keeps the other subsystems loosely coupled and is the likely boundary for common request/state schemas.

10. **Runtime and build model**
   - The project is TypeScript-based (`src/*.ts`, `src/*.tsx`) and targets Node.js.
   - `tsconfig.json`, `package.json`, and the generated `dist/` directory show a standard compile step from TypeScript to distributable CommonJS/JS output.
   - The presence of `node_modules/` and `package-lock.json` indicates npm-managed dependencies.

11. **Installer and launch scripts**
   - `scripts/install.sh`, `scripts/start.sh`, and `scripts/dev.sh` suggest three operational modes: install/setup, run, and development.
   - `install.ps1` supports Windows installation.
   - These scripts are the external entry surfaces around the core Node runtime.

12. **Project structure and non-runtime artifacts**
   - `scratch/` contains experiments and generated assets; it is not part of the main application flow.
   - `assets/` provides branding imagery used by the README and likely the CLI/TUI presentation.
   - `.env` in `aegis-core/` suggests environment-variable-based local configuration, but it is not the primary persisted state.

13. **How data flows through the app**
   - User launches the CLI → command router resolves the action → config/installation state is checked → agent is initialized → terminal UI renders the dashboard → tools read/write local system, file, and memory state as needed.
   - The key architecture boundary is that **UI, orchestration, and capabilities are separated**, with persistent state split between config and memory.

14. **How to diagram this repo accurately**
   - Draw it as a **single local Node/TypeScript application** with four main internal zones:
     - CLI/bootstrap
     - terminal UI
     - agent orchestration
     - tool + state layer
   - Keep the federated/blockchain/medical-network concepts from the README as the intended product vision, but do not diagram them as implemented runtime subsystems unless additional source files are added later.

Main entry points: [`aegis-core/src/models/index.ts`](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/models/index.ts) (Shared Models), [`aegis-core/src/commands/index.ts`](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/commands/index.ts) (Command Router), [`aegis-core/src/tools/index.ts`](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/index.ts) (Tool Hub), [`aegis-core/src/terminal/App.tsx`](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/App.tsx) (Terminal App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI Runtime"]
  node_aegis_core_bin_aegis_js["Boot Loader<br/>bootstrap<br/>[aegis.js]"]
  node_aegis_core_src_index_tsx["App Entry<br/>cli entry<br/>[index.tsx]"]
  node_aegis_core_src_commands_index_ts["Command Router<br/>cli router<br/>[index.ts]"]
end

subgraph group_ui["Terminal UI"]
  node_aegis_core_src_terminal_app_tsx["Terminal App<br/>tui shell<br/>[App.tsx]"]
  node_aegis_core_src_terminal_dashboard_tsx["Dashboard<br/>tui view<br/>[Dashboard.tsx]"]
  node_aegis_core_src_terminal_art_ts["Branding Art<br/>tui assets<br/>[art.ts]"]
end

subgraph group_agent["Agent Layer"]
  node_aegis_core_src_agent_index_ts{{"Agent Core<br/>orchestrator<br/>[index.ts]"}}
  node_aegis_core_src_models_index_ts["Shared Models<br/>domain types<br/>[index.ts]"]
end

subgraph group_capabilities["Tooling"]
  node_aegis_core_src_tools_index_ts["Tool Hub<br/>tool registry<br/>[index.ts]"]
  node_aegis_core_src_tools_filetool_ts["File Tool<br/>filesystem tool<br/>[FileTool.ts]"]
  node_aegis_core_src_tools_systemtool_ts["System Tool<br/>[SystemTool.ts]"]
  node_aegis_core_src_tools_memorytool_ts["Memory Tool<br/>persistence tool<br/>[MemoryTool.ts]"]
  node_aegis_core_src_tools_terminaltool_ts["Terminal Tool<br/>ui tool<br/>[TerminalTool.ts]"]
end

subgraph group_state["State"]
  node_aegis_core_src_memory_index_ts[("Local Memory<br/>memory store<br/>[index.ts]")]
  node_memory_default_json["Seed Memory<br/>seed state<br/>[default.json]"]
  node_aegis_core_src_config_index_ts[("Config Store<br/>[index.ts]")]
end

subgraph group_ops["Launchers"]
  node_aegis_core_scripts_start_sh["Start Script<br/>launcher<br/>[start.sh]"]
  node_aegis_core_scripts_install_sh["Install Script<br/>installer<br/>[install.sh]"]
end

node_aegis_core_bin_aegis_js -->|"starts"| node_aegis_core_src_index_tsx
node_aegis_core_src_index_tsx -->|"routes"| node_aegis_core_src_commands_index_ts
node_aegis_core_src_commands_index_ts -->|"checks"| node_aegis_core_src_config_index_ts
node_aegis_core_src_commands_index_ts -->|"launches"| node_aegis_core_src_terminal_app_tsx
node_aegis_core_src_commands_index_ts -.->|"wraps"| node_aegis_core_scripts_start_sh
node_aegis_core_src_commands_index_ts -.->|"wraps"| node_aegis_core_scripts_install_sh
node_aegis_core_src_terminal_app_tsx -->|"renders"| node_aegis_core_src_terminal_dashboard_tsx
node_aegis_core_src_terminal_app_tsx -->|"brands"| node_aegis_core_src_terminal_art_ts
node_aegis_core_src_terminal_app_tsx -->|"hosts"| node_aegis_core_src_agent_index_ts
node_aegis_core_src_agent_index_ts -->|"uses"| node_aegis_core_src_models_index_ts
node_aegis_core_src_agent_index_ts -->|"delegates"| node_aegis_core_src_tools_index_ts
node_aegis_core_src_agent_index_ts -->|"persists"| node_aegis_core_src_memory_index_ts
node_aegis_core_src_config_index_ts -->|"types"| node_aegis_core_src_models_index_ts
node_aegis_core_src_tools_index_ts -->|"exports"| node_aegis_core_src_tools_filetool_ts
node_aegis_core_src_tools_index_ts -->|"exports"| node_aegis_core_src_tools_systemtool_ts
node_aegis_core_src_tools_index_ts -->|"exports"| node_aegis_core_src_tools_memorytool_ts
node_aegis_core_src_tools_index_ts -->|"exports"| node_aegis_core_src_tools_terminaltool_ts
node_aegis_core_src_tools_memorytool_ts -->|"stores"| node_aegis_core_src_memory_index_ts
node_aegis_core_src_memory_index_ts -->|"seeds"| node_memory_default_json
node_aegis_core_src_tools_filetool_ts -->|"uses"| node_aegis_core_src_models_index_ts
node_aegis_core_src_tools_systemtool_ts -->|"uses"| node_aegis_core_src_models_index_ts
node_aegis_core_src_tools_memorytool_ts -->|"uses"| node_aegis_core_src_models_index_ts
node_aegis_core_src_tools_terminaltool_ts -->|"uses"| node_aegis_core_src_models_index_ts
node_aegis_core_src_config_index_ts -->|"initializes"| node_aegis_core_src_agent_index_ts
node_aegis_core_src_config_index_ts -.->|"gates"| node_aegis_core_src_terminal_app_tsx

click node_aegis_core_bin_aegis_js "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/bin/aegis.js"
click node_aegis_core_src_index_tsx "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/index.tsx"
click node_aegis_core_src_commands_index_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/commands/index.ts"
click node_aegis_core_scripts_start_sh "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/scripts/start.sh"
click node_aegis_core_scripts_install_sh "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/scripts/install.sh"
click node_aegis_core_src_terminal_app_tsx "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/App.tsx"
click node_aegis_core_src_terminal_dashboard_tsx "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/Dashboard.tsx"
click node_aegis_core_src_terminal_art_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/art.ts"
click node_aegis_core_src_agent_index_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/agent/index.ts"
click node_aegis_core_src_models_index_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/models/index.ts"
click node_aegis_core_src_tools_index_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/index.ts"
click node_aegis_core_src_tools_filetool_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/FileTool.ts"
click node_aegis_core_src_tools_systemtool_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/SystemTool.ts"
click node_aegis_core_src_tools_memorytool_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/MemoryTool.ts"
click node_aegis_core_src_tools_terminaltool_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/TerminalTool.ts"
click node_aegis_core_src_memory_index_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/memory/index.ts"
click node_memory_default_json "https://github.com/aegisaifoundation/aegis/blob/main/.memory/default.json"
click node_aegis_core_src_config_index_ts "https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/config/index.ts"

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_aegis_core_bin_aegis_js,node_aegis_core_src_index_tsx,node_aegis_core_src_commands_index_ts toneBlue
class node_aegis_core_src_terminal_app_tsx,node_aegis_core_src_terminal_dashboard_tsx,node_aegis_core_src_terminal_art_ts toneAmber
class node_aegis_core_src_agent_index_ts,node_aegis_core_src_models_index_ts toneMint
class node_aegis_core_src_tools_index_ts,node_aegis_core_src_tools_filetool_ts,node_aegis_core_src_tools_systemtool_ts,node_aegis_core_src_tools_memorytool_ts,node_aegis_core_src_tools_terminaltool_ts toneRose
class node_aegis_core_src_memory_index_ts,node_memory_default_json,node_aegis_core_src_config_index_ts toneIndigo
class node_aegis_core_scripts_start_sh,node_aegis_core_scripts_install_sh toneTeal
```

## Components

### CLI Runtime

Bootstrap and command routing for the Node/TypeScript application.

- [Boot Loader](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/bin/aegis.js): bootstrap · Node entry script that starts the compiled application. · `aegis-core/bin/aegis.js`
- [App Entry](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/index.tsx): cli entry · Top-level TypeScript application entrypoint. · `aegis-core/src/index.tsx`
- [Command Router](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/commands/index.ts): cli router · Routes CLI verbs into launch, config, and cleanup flows. · `aegis-core/src/commands/index.ts`

### Terminal UI

Interactive terminal presentation and branding.

- [Terminal App](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/App.tsx): tui shell · Main interactive terminal application shell. · `aegis-core/src/terminal/App.tsx`
- [Dashboard](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/Dashboard.tsx): tui view · Primary terminal dashboard view. · `aegis-core/src/terminal/Dashboard.tsx`
- [Branding Art](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/terminal/art.ts): tui assets · ASCII art and branding used by the terminal UI. · `aegis-core/src/terminal/art.ts`

### Agent Layer

Agent orchestration and shared domain models.

- [Agent Core](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/agent/index.ts): orchestrator · Coordinates agent state, UI, memory, and tools. · `aegis-core/src/agent/index.ts`
- [Shared Models](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/models/index.ts): domain types · Common types and data contracts shared across subsystems. · `aegis-core/src/models/index.ts`

### Tooling

Delegated capabilities used by the agent.

- [Tool Hub](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/index.ts): tool registry · Aggregates and exports the agent capability tools. · `aegis-core/src/tools/index.ts`
- [File Tool](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/FileTool.ts): filesystem tool · Filesystem access and file operations. · `aegis-core/src/tools/FileTool.ts`
- [System Tool](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/SystemTool.ts): system tool · Environment and system-level actions. · `aegis-core/src/tools/SystemTool.ts`
- [Memory Tool](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/MemoryTool.ts): persistence tool · Reads and writes persistent local memory state. · `aegis-core/src/tools/MemoryTool.ts`
- [Terminal Tool](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/tools/TerminalTool.ts): ui tool · Terminal interaction support for the agent. · `aegis-core/src/tools/TerminalTool.ts`

### State

Configuration and persistent local memory.

- [Local Memory](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/memory/index.ts): memory store · Persistent local memory subsystem. · `aegis-core/src/memory/index.ts`
- [Seed Memory](https://github.com/aegisaifoundation/aegis/blob/main/.memory/default.json): seed state · Default seeded memory content for local state. · `.memory/default.json`
- [Config Store](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/src/config/index.ts): config store · Local configuration and installation state. · `aegis-core/src/config/index.ts`

### Launchers

Shell and installer entrypoints around the app.

- [Start Script](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/scripts/start.sh): launcher · Shell wrapper for running the application. · `aegis-core/scripts/start.sh`
- [Install Script](https://github.com/aegisaifoundation/aegis/blob/main/aegis-core/scripts/install.sh): installer · Shell wrapper for installation and setup. · `aegis-core/scripts/install.sh`

## Connections

- Boot Loader → App Entry: starts · Bootstrap hands off into the application entrypoint.
- App Entry → Command Router: routes · App entry delegates CLI verbs to the command router.
- Command Router → Config Store: checks · Commands verify installation and configuration state.
- Command Router → Terminal App: launches · Launch/start flows enter the terminal application.
- Command Router → Start Script: wraps · Start flows are exposed through shell launcher scripts.
- Command Router → Install Script: wraps · Setup and installation are exposed through shell scripts.
- Terminal App → Dashboard: renders · The terminal app presents the dashboard view.
- Terminal App → Branding Art: brands · The UI includes ASCII branding and identity art.
- Terminal App → Agent Core: hosts · The UI drives and displays the agent runtime.
- Agent Core → Shared Models: uses · Agent logic relies on shared domain models.
- Agent Core → Tool Hub: delegates · The agent delegates actions through the tool boundary.
- Agent Core → Local Memory: persists · Agent orchestration reads and updates local memory.
- Config Store → Shared Models: types · Configuration shares the common data model layer.
- Tool Hub → File Tool: exports · Tool registry exposes filesystem capability.
- Tool Hub → System Tool: exports · Tool registry exposes system capability.
- Tool Hub → Memory Tool: exports · Tool registry exposes memory capability.
- Tool Hub → Terminal Tool: exports · Tool registry exposes terminal capability.
- Memory Tool → Local Memory: stores · Memory tool reads and writes persistent state.
- Local Memory → Seed Memory: seeds · Local memory is initialized from seeded defaults.
- File Tool → Shared Models: uses · Tools share common request and result shapes.
- System Tool → Shared Models: uses · Tools share common request and result shapes.
- Memory Tool → Shared Models: uses · Tools share common request and result shapes.
- Terminal Tool → Shared Models: uses · Tools share common request and result shapes.
- Config Store → Agent Core: initializes · Configuration is a prerequisite for agent startup.
- Config Store → Terminal App: gates · Configuration state gates the terminal experience.
