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