> ## Documentation Index
> Fetch the complete documentation index at: https://o1.network/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

O1 Universal Remote is built on a modular, extensible architecture designed to support multiple infrastructure types while maintaining simplicity and power.

## High-Level Architecture

```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
%%{init: {"theme":"base","themeVariables":{"background":"#0d0f18","primaryColor":"#13161f","primaryTextColor":"#f0f0f2","primaryBorderColor":"rgba(255,255,255,0.1)","lineColor":"#888","edgeLabelBackground":"#0d0f18","fontSize":"15px","fontFamily":"ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart TD
    subgraph UI ["  User Interfaces  "]
        WebDash["Web Dashboard"]
        CLITool["CLI"]
        APIClient["API Clients"]
        NLPVoice["Natural Language"]
    end

    subgraph GW ["  API Gateway & Router  "]
        AuthN["Authentication & AuthZ"]
        Routing["Request Routing & Load Balancing"]
        RateLog["Rate Limiting & Logging"]
    end

    subgraph SVC ["  Service Layer  "]
        NodesSvc["Nodes Service"]
        AppsSvc["Applications Service"]
        MonSvc["Monitoring Service"]
        ExplSvc["Explorer Service"]
    end

    subgraph ORCH ["  Orchestration Engine  "]
        Playbooks["Playbook Execution"]
        DepMgmt["Dependency Management"]
        StateTrack["State Tracking & Audit"]
    end

    subgraph RT ["  Runtimes  "]
        Ansible["Ansible Engine"]
        DockerRT["Docker Runtime"]
        SystemdSvc["Systemd Service"]
        MultiProv["Multi-Provider Adapters"]
    end

    subgraph INFRA ["  Infrastructure  "]
        CloudProv["Cloud Providers"]
        K8sClusters["Kubernetes Clusters"]
        BlockchainNodes["Blockchain Nodes"]
        IoTEdge["IoT & Edge Devices"]
    end

    UI --> GW
    GW --> SVC
    SVC --> ORCH
    ORCH --> RT
    RT --> INFRA

    %% Precious metals + earth minerals — platinum → lapis → malachite → gold → bronze → iron
    classDef uiNode    fill:#161618,stroke:#D0CFCD,color:#EDECEB,stroke-width:1.5px
    classDef gwNode    fill:#02040a,stroke:#1E3A5A,color:#6A8AAA,stroke-width:1px
    classDef svcNode   fill:#071510,stroke:#3A8C5C,color:#A8D4B8,stroke-width:1.5px
    classDef orchNode  fill:#1a1400,stroke:#CFB53B,color:#F0DC8A,stroke-width:1.5px
    classDef rtNode    fill:#180e04,stroke:#B07832,color:#DEB882,stroke-width:1.5px
    classDef infraNode fill:#140a06,stroke:#8B6050,color:#C4A090,stroke-width:1.5px

    class WebDash,CLITool,APIClient,NLPVoice uiNode
    class AuthN,Routing,RateLog gwNode
    class NodesSvc,AppsSvc,MonSvc,ExplSvc svcNode
    class Playbooks,DepMgmt,StateTrack orchNode
    class Ansible,DockerRT,SystemdSvc,MultiProv rtNode
    class CloudProv,K8sClusters,BlockchainNodes,IoTEdge infraNode

    %% Subgraph backgrounds — deep tints of each material
    style UI    fill:#101012,stroke:#C0BFBD,color:#C8C7C5
    style GW    fill:#010308,stroke:#162840,color:#3A5878
    style SVC   fill:#060e09,stroke:#2E7A4E,color:#4EA870
    style ORCH  fill:#120f00,stroke:#CFB53B,color:#CFB53B
    style RT    fill:#120800,stroke:#A06828,color:#C08840
    style INFRA fill:#0e0604,stroke:#7A5040,color:#9A7060

    %% Arrows in the metal of their source layer
    linkStyle 0 stroke:#C0BFBD,stroke-width:2px
    linkStyle 1 stroke:#1E3A5A,stroke-width:2px
    linkStyle 2 stroke:#2E7A4E,stroke-width:2px
    linkStyle 3 stroke:#CFB53B,stroke-width:2px
    linkStyle 4 stroke:#A06828,stroke-width:2px
```

## Core Components

### 1. API Layer

RESTful HTTP and WebSocket endpoints with token authentication, request validation, and rate limiting.

<CardGroup cols={3}>
  <Card title="Nodes" icon="server">
    Infrastructure lifecycle, SSH keys, cloud credentials — **49 endpoints**
  </Card>

  <Card title="Applications" icon="rocket">
    Deployment, versioning, rollback, dependency resolution — **12 endpoints**
  </Card>

  <Card title="Monitoring" icon="chart-line">
    Metrics, logs, healthchecks, alerting — **22 endpoints**
  </Card>

  <Card title="Explorer" icon="magnifying-glass">
    Instance pricing, spot history, multi-cloud comparison — **4 endpoints**
  </Card>

  <Card title="Addons" icon="puzzle-piece">
    Addon CRUD and lifecycle management — **7 endpoints**
  </Card>

  <Card title="Operations & Realtime" icon="bolt">
    Playbook execution, PTY sessions, WebSocket streams — **6 endpoints**
  </Card>
</CardGroup>

Additional routes: `storage` (10), `scaling-groups` (9), `sync` (4), `deployment` (4), `environment` (4), `volumes` (1).

### 2. Service Layer

<CardGroup cols={2}>
  <Card title="Nodes Service" icon="server">
    Provisions and manages infrastructure nodes across AWS, Azure, GCP, and DigitalOcean. Handles SSH key store, cloud credentials, and infrastructure state sync.
  </Card>

  <Card title="Applications Service" icon="rocket">
    Dual-mode deployment (Docker container or binary). Manages versions, dependencies, configuration templates, and deployment history.
  </Card>

  <Card title="Monitoring Service" icon="chart-line">
    Real-time metrics streaming via WebSocket, log aggregation, scheduled healthchecks, and alert dispatch.
  </Card>

  <Card title="Explorer Service" icon="magnifying-glass">
    Queries 103K+ indexed instance types for pricing comparison, spot history forecasting, and resource optimization recommendations.
  </Card>
</CardGroup>

Additional services: `spotScalingService` (auto-scaling groups), `SyncService` (state reconciliation), `ptyService` (terminal sessions), `realtimeService` (WebSocket broker).

### 3. Orchestration Engine

Executes operational playbooks via **Ansible** (idempotent multi-node automation), **Docker** (container lifecycle and registry), and **Systemd** (service management, log rotation, startup ordering). The `PlaybookService` resolves dependencies, generates execution plans, tracks state, and writes audit logs.

### 4. Data Layer

<CardGroup cols={2}>
  <Card title="Storage Adapters" icon="database">
    Pluggable driver model with four backends: **Filesystem** (default), **MongoDB**, **S3**, and **Redis**. Configured per-deployment via `StorageConfigService`.
  </Card>

  <Card title="Configuration" icon="file-code">
    Entities (nodes, applications, addons) persisted as **YAML** with template variable substitution. Git-trackable by design.
  </Card>

  <Card title="Runtime State" icon="bolt">
    Infrastructure state, deployment history, and monitoring data managed by `infrastructureState` and the deployment service.
  </Card>

  <Card title="Secrets" icon="lock">
    SSH keys via `sshKeyStore`, cloud credentials via `cloudCredentialStore` and `sharedCredentialStore` — never stored in plain config.
  </Card>
</CardGroup>

## Data Flow

### 1. Request Processing

```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
%%{init: {"theme":"base","themeVariables":{"background":"#0d0f18","primaryColor":"#13161f","primaryTextColor":"#f0f0f2","primaryBorderColor":"rgba(255,255,255,0.14)","lineColor":"#CFB53B","edgeLabelBackground":"#0d0f18","fontSize":"15px","fontFamily":"ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
    UserReq["User Request"] --> APIGateway["API Gateway"]
    APIGateway --> AuthStep["Authentication"]
    AuthStep --> Validation["Request Validation"]
    Validation --> SvcRouter["Service Router"]
    SvcRouter --> SvcHandler["Service Handler"]
    SvcHandler --> OrchEngine["Orchestration Engine"]
    OrchEngine --> Infra["Infrastructure"]
```

### 2. Deployment Flow

```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
%%{init: {"theme":"base","themeVariables":{"background":"#0d0f18","primaryColor":"#13161f","primaryTextColor":"#f0f0f2","primaryBorderColor":"rgba(255,255,255,0.14)","lineColor":"#CFB53B","edgeLabelBackground":"#0d0f18","fontSize":"15px","fontFamily":"ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
    DeployReq["Deploy Request"] --> AppSvc["Application Service"]
    AppSvc --> DepRes["Dependency Resolution"]
    DepRes --> PlaybookGen["Playbook Generation"]
    PlaybookGen --> AnsibleExec["Ansible Execution"]
    AnsibleExec --> StateUpdate["State Update"]
    StateUpdate --> MonReg["Monitoring Registration"]
    MonReg --> Success["Success Response"]
```

### 3. Monitoring Flow

```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
%%{init: {"theme":"base","themeVariables":{"background":"#0d0f18","primaryColor":"#13161f","primaryTextColor":"#f0f0f2","primaryBorderColor":"rgba(255,255,255,0.14)","lineColor":"#CFB53B","edgeLabelBackground":"#0d0f18","fontSize":"15px","fontFamily":"ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
    MetricCol["Metric Collection"] --> MonSvc["Monitoring Service"]
    MonSvc --> DataProc["Data Processing"]
    DataProc --> Storage["Storage & Publishing"]
    Storage --> RTStream["Real-time Streaming"]
    RTStream --> Alerting["Alerting"]
    Alerting --> Dashboard["Dashboard Updates"]
```

## Security Architecture

<CardGroup cols={3}>
  <Card title="Authentication" icon="key">
    API token auth on all endpoints. SSH keys managed by `sshKeyStore` — no passwords stored. Full audit trail on every operation.
  </Card>

  <Card title="Secrets & Encryption" icon="lock">
    Cloud credentials isolated in `cloudCredentialStore`. Secrets encrypted at rest and in transit. Network segmentation via firewall rules.
  </Card>

  <Card title="Least Privilege" icon="shield">
    Operations run with minimal required permissions. Automated security hardening applied to provisioned nodes.
  </Card>
</CardGroup>

## Scalability & Performance

<CardGroup cols={3}>
  <Card title="Horizontal Scaling" icon="arrows-left-right">
    Stateless API services scale independently. External storage backends (MongoDB, Redis, S3) decouple state from compute.
  </Card>

  <Card title="Performance" icon="bolt">
    `instanceTypeCache` and `spotPricing` caches reduce upstream API calls. Long-running operations execute asynchronously via playbook queue.
  </Card>

  <Card title="High Availability" icon="circle-check">
    `SyncService` reconciles infrastructure state on reconnect. Storage adapter failover supported across all four driver types.
  </Card>
</CardGroup>

## Extension Architecture

O1's adapter pattern makes it straightforward to add new providers, runtimes, and integrations:

* **Provider adapters** — implement the cloud provider interface to add new infrastructure targets
* **Storage drivers** — extend `StorageDriver` to add new persistence backends
* **Playbook templates** — add YAML playbooks to extend the orchestration engine without touching core code
* **Webhook events** — subscribe to the realtime event bus for external system integration

See the [Contributing Guide](/docs/advanced/contributing) for implementation details.

***

*This modular architecture scales from a single-node homelab to multi-region enterprise deployments — without changing the interface.*