---
title: "Architecture Guide"
description: "Understanding the internal architecture of Nexus OS. 1. CLI parses user input into a Cmd enum 2. Main dispatches to the appropriate module 3. Module opens the Store (SQLite connection) 4. Store reads/writes data and retu"
resource: https://www.aiagents.nexus/docs/manual/contributing/architecture
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# Architecture Guide

Understanding the internal architecture of Nexus OS.

## Module Dependency Graph

```
main.rs
  ├── cli.rs (argument parsing)
  ├── config.rs (YAML loading)
  ├── store.rs (SQLite persistence)
  ├── commands.rs (agent lifecycle)
  │   └── store.rs
  ├── axis.rs (trust verification)
  │   └── store.rs
  ├── broker.rs (routing engine)
  │   ├── store.rs
  │   └── config.rs
  ├── edge.rs (edge deployment)
  │   ├── store.rs
  │   ├── config.rs
  │   └── cloudflare.rs
  └── dashboard.rs (web UI)
      └── store.rs
```

## Data Flow

1. **CLI** parses user input into a `Cmd` enum
2. **Main** dispatches to the appropriate module
3. **Module** opens the `Store` (SQLite connection)
4. **Store** reads/writes data and returns results
5. **Module** formats output for the terminal

## Store Design

The Store uses SQLite with these design principles:

- **Single file** — All data in one `nexus.db` file
- **Migrations** — Schema created on first open
- **No ORM** — Direct SQL with rusqlite
- **Transactions** — Used for multi-step operations

## Adding a New Module

1. Create `src/new_module.rs`
2. Add tables to `Store::open()` migration
3. Add data types and methods to `store.rs`
4. Add CLI subcommand to `cli.rs`
5. Add dispatch arm to `main.rs`
6. Add dashboard page to `dashboard.rs`