# nabilkhan-01/astralis architecture

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

- Interactive diagram: https://gitdiagram.com/nabilkhan-01/astralis
- Repository: https://github.com/nabilkhan-01/astralis

## Overview

ASTRALIS is a modular personal AI assistant. Its documented request workflow runs from the CLI through memory retrieval and context assembly to the Brain and capability execution, returning a response while keeping the user in control. The graph also shows persistent memory, interchangeable AI providers, and the broader capability integrations. Edges are grounded in the README or shown source/index references; several capability and provider internals were not sampled, so their detailed runtime calls are not asserted.

Main entry points: [`astralis/pipeline/request_pipeline.py`](https://github.com/nabilkhan-01/astralis/blob/main/astralis/pipeline/request_pipeline.py) (Request pipeline), [`astralis/brain/brain.py`](https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/brain.py) (Brain), [`astralis/bootstrap/bootstrap.py`](https://github.com/nabilkhan-01/astralis/blob/main/astralis/bootstrap/bootstrap.py) (Bootstrap), [`astralis/capability`](https://github.com/nabilkhan-01/astralis/tree/main/astralis/capability) (Capabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request and reasoning"]
  node_cli["CLI<br/>[cli.py]"]
  node_pipeline["Request pipeline"]
  node_brain["Brain<br/>[brain.py]"]
  node_reasoning["Interpret and plan<br/>[interpreter.py]"]
  node_conversation["Conversation state<br/>[conversation.py]"]
  node_response["Response<br/>[response.py]"]
end

subgraph group_memory["Context and memory"]
  node_retriever["Memory retrieval<br/>[retriever.py]"]
  node_relevance["Relevance ranking<br/>[relevance.py]"]
  node_context["Request context<br/>[context.py]"]
  node_memory_manager["Memory manager<br/>[manager.py]"]
  node_entity_store[("Entity store<br/>[json_store.py]")]
  node_domain_memory["Domain memories"]
end

subgraph group_action["Capabilities and integrations"]
  node_cap_manager["Capability manager<br/>[manager.py]"]
  node_cap_registry["Capability registry<br/>[registry.py]"]
  node_capabilities["Capabilities"]
  node_tools["Computer tools"]
  node_apis["External APIs"]
  node_provider_factory["Provider factory<br/>[factory.py]"]
  node_provider["AI providers"]
end

subgraph group_runtime["Application runtime"]
  node_bootstrap["Bootstrap<br/>[bootstrap.py]"]
  node_application["Application<br/>[application.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_monitor["Request monitoring<br/>[monitor.py]"]
end

node_user(("User"))
node_external_services{{"Web and service APIs"}}

node_user -->|"submits request"| node_cli
node_cli -->|"forwards request"| node_pipeline
node_pipeline -->|"retrieves memory"| node_retriever
node_retriever -->|"loads entities"| node_memory_manager
node_memory_manager -->|"reads and writes"| node_entity_store
node_retriever -->|"ranks candidates"| node_relevance
node_relevance -->|"builds context"| node_context
node_pipeline -->|"processes request"| node_brain
node_pipeline -->|"measures request"| node_monitor
node_brain -->|"interprets and plans"| node_reasoning
node_brain -->|"records messages"| node_conversation
node_brain -->|"executes plan"| node_cap_manager
node_cap_manager -->|"selects capability"| node_cap_registry
node_cap_manager -->|"executes capability"| node_capabilities
node_brain -->|"uses retrieved context"| node_context
node_pipeline -->|"returns response"| node_response
node_bootstrap -->|"assembles components"| node_application
node_bootstrap -->|"registers capabilities"| node_cap_registry
node_bootstrap -->|"creates provider"| node_provider_factory
node_provider_factory -.->|"selects implementation"| node_provider
node_bootstrap -->|"loads configuration"| node_config
node_capabilities -.->|"uses computer tools"| node_tools
node_capabilities -.->|"uses service clients"| node_apis
node_apis -.->|"calls external services"| node_external_services
node_capabilities -.->|"uses language provider"| node_provider

click node_cli "https://github.com/nabilkhan-01/astralis/blob/main/astralis/interfaces/cli.py"
click node_pipeline "https://github.com/nabilkhan-01/astralis/blob/main/astralis/pipeline/request_pipeline.py"
click node_brain "https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/brain.py"
click node_reasoning "https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/interpreter.py"
click node_conversation "https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/conversation.py"
click node_response "https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/response.py"
click node_retriever "https://github.com/nabilkhan-01/astralis/blob/main/astralis/memory/retriever.py"
click node_relevance "https://github.com/nabilkhan-01/astralis/blob/main/astralis/context/relevance.py"
click node_context "https://github.com/nabilkhan-01/astralis/blob/main/astralis/context/context.py"
click node_memory_manager "https://github.com/nabilkhan-01/astralis/blob/main/astralis/memory/manager.py"
click node_entity_store "https://github.com/nabilkhan-01/astralis/blob/main/astralis/memory/json_store.py"
click node_domain_memory "https://github.com/nabilkhan-01/astralis/tree/main/astralis/memory"
click node_cap_manager "https://github.com/nabilkhan-01/astralis/blob/main/astralis/capability/manager.py"
click node_cap_registry "https://github.com/nabilkhan-01/astralis/blob/main/astralis/capability/registry.py"
click node_capabilities "https://github.com/nabilkhan-01/astralis/tree/main/astralis/capability"
click node_tools "https://github.com/nabilkhan-01/astralis/tree/main/astralis/tools"
click node_apis "https://github.com/nabilkhan-01/astralis/tree/main/astralis/api"
click node_provider_factory "https://github.com/nabilkhan-01/astralis/blob/main/astralis/providers/factory.py"
click node_provider "https://github.com/nabilkhan-01/astralis/tree/main/astralis/providers"
click node_bootstrap "https://github.com/nabilkhan-01/astralis/blob/main/astralis/bootstrap/bootstrap.py"
click node_application "https://github.com/nabilkhan-01/astralis/blob/main/astralis/bootstrap/application.py"
click node_config "https://github.com/nabilkhan-01/astralis/blob/main/astralis/core/config.py"
click node_monitor "https://github.com/nabilkhan-01/astralis/blob/main/astralis/monitoring/monitor.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_cli,node_pipeline,node_brain,node_reasoning,node_conversation,node_response,node_user toneBlue
class node_retriever,node_relevance,node_context,node_memory_manager,node_entity_store,node_domain_memory toneAmber
class node_cap_manager,node_cap_registry,node_capabilities,node_tools,node_apis,node_provider_factory,node_provider,node_external_services toneMint
class node_bootstrap,node_application,node_config,node_monitor toneRose
```

## Components

### Request and reasoning

- [CLI](https://github.com/nabilkhan-01/astralis/blob/main/astralis/interfaces/cli.py): `astralis/interfaces/cli.py`
- [Request pipeline](https://github.com/nabilkhan-01/astralis/blob/main/astralis/pipeline/request_pipeline.py): `astralis/pipeline/request_pipeline.py`
- [Brain](https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/brain.py): `astralis/brain/brain.py`
- [Interpret and plan](https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/interpreter.py): `astralis/brain/interpreter.py`
- [Conversation state](https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/conversation.py): `astralis/brain/conversation.py`
- [Response](https://github.com/nabilkhan-01/astralis/blob/main/astralis/brain/response.py): `astralis/brain/response.py`

### Context and memory

- [Memory retrieval](https://github.com/nabilkhan-01/astralis/blob/main/astralis/memory/retriever.py): `astralis/memory/retriever.py`
- [Relevance ranking](https://github.com/nabilkhan-01/astralis/blob/main/astralis/context/relevance.py): `astralis/context/relevance.py`
- [Request context](https://github.com/nabilkhan-01/astralis/blob/main/astralis/context/context.py): `astralis/context/context.py`
- [Memory manager](https://github.com/nabilkhan-01/astralis/blob/main/astralis/memory/manager.py): `astralis/memory/manager.py`
- [Entity store](https://github.com/nabilkhan-01/astralis/blob/main/astralis/memory/json_store.py): `astralis/memory/json_store.py`
- [Domain memories](https://github.com/nabilkhan-01/astralis/tree/main/astralis/memory): `astralis/memory`

### Capabilities and integrations

- [Capability manager](https://github.com/nabilkhan-01/astralis/blob/main/astralis/capability/manager.py): `astralis/capability/manager.py`
- [Capability registry](https://github.com/nabilkhan-01/astralis/blob/main/astralis/capability/registry.py): `astralis/capability/registry.py`
- [Capabilities](https://github.com/nabilkhan-01/astralis/tree/main/astralis/capability): `astralis/capability`
- [Computer tools](https://github.com/nabilkhan-01/astralis/tree/main/astralis/tools): `astralis/tools`
- [External APIs](https://github.com/nabilkhan-01/astralis/tree/main/astralis/api): `astralis/api`
- [Provider factory](https://github.com/nabilkhan-01/astralis/blob/main/astralis/providers/factory.py): `astralis/providers/factory.py`
- [AI providers](https://github.com/nabilkhan-01/astralis/tree/main/astralis/providers): `astralis/providers`

### Application runtime

- [Bootstrap](https://github.com/nabilkhan-01/astralis/blob/main/astralis/bootstrap/bootstrap.py): `astralis/bootstrap/bootstrap.py`
- [Application](https://github.com/nabilkhan-01/astralis/blob/main/astralis/bootstrap/application.py): `astralis/bootstrap/application.py`
- [Configuration](https://github.com/nabilkhan-01/astralis/blob/main/astralis/core/config.py): `astralis/core/config.py`
- [Request monitoring](https://github.com/nabilkhan-01/astralis/blob/main/astralis/monitoring/monitor.py): `astralis/monitoring/monitor.py`

### Other components

- **User**
- **Web and service APIs**

## Connections

- User → CLI: submits request (evidence: `README.md`)
- CLI → Request pipeline: forwards request (evidence: `astralis/interfaces/cli.py`)
- Request pipeline → Memory retrieval: retrieves memory (evidence: `astralis/pipeline/request_pipeline.py`)
- Memory retrieval → Memory manager: loads entities (evidence: `astralis/memory/retriever.py`)
- Memory manager → Entity store: reads and writes (evidence: `astralis/memory/manager.py`)
- Memory retrieval → Relevance ranking: ranks candidates (evidence: `astralis/memory/retriever.py`)
- Relevance ranking → Request context: builds context (evidence: `astralis/context/relevance.py`)
- Request pipeline → Brain: processes request (evidence: `astralis/pipeline/request_pipeline.py`)
- Request pipeline → Request monitoring: measures request (evidence: `astralis/pipeline/request_pipeline.py`)
- Brain → Interpret and plan: interprets and plans (evidence: `astralis/brain/brain.py`)
- Brain → Conversation state: records messages (evidence: `astralis/brain/brain.py`)
- Brain → Capability manager: executes plan (evidence: `astralis/brain/brain.py`)
- Capability manager → Capability registry: selects capability (evidence: `astralis/capability/manager.py`)
- Capability manager → Capabilities: executes capability (evidence: `astralis/capability/manager.py`)
- Brain → Request context: uses retrieved context (evidence: `astralis/brain/brain.py`)
- Request pipeline → Response: returns response (evidence: `astralis/pipeline/request_pipeline.py`)
- Bootstrap → Application: assembles components (evidence: `astralis/bootstrap/bootstrap.py`)
- Bootstrap → Capability registry: registers capabilities (evidence: `astralis/bootstrap/bootstrap.py`)
- Bootstrap → Provider factory: creates provider (evidence: `astralis/bootstrap/bootstrap.py`)
- Provider factory → AI providers: selects implementation
- Bootstrap → Configuration: loads configuration (evidence: `astralis/bootstrap/bootstrap.py`)
- Capabilities → Computer tools: uses computer tools
- Capabilities → External APIs: uses service clients (evidence: `astralis/capability/search.py`)
- External APIs → Web and service APIs: calls external services
- Capabilities → AI providers: uses language provider
