# Architecture

Armorer evolved from a simple CLI into a **Service-Oriented Architecture** where a persistent background "Core" manages security and execution, while lightweight interfaces (CLI, Signal) handle user interaction.

## System Topology

```mermaid
graph TD
    subgraph "Host Machine (Mac/Linux)"
        CLI[Armorer CLI] -->|Inbox/Outbox| Core[Armorer Core Container]
        Core -->|Docker Socket| Daemon[Docker Daemon]
        
        subgraph "Sandboxed Runtime"
            Daemon -->|Spawn| Agent1[Agent A]
            Daemon -->|Spawn| Agent2[Agent B]
        end
        
        Data[(Installed Data)]
        Core -->|RW Access| Data
        Agent1 -->|Scoped Access| Data
        Agent2 -->|Scoped Access| Data
    end
```

## Core Components

### 1. Armorer Core (The Brain)
The Core is a persistent background service running in a Docker container. It is responsible for:
-   **Security Oversight**: Real-time monitoring and redaction of agent logs.
-   **Command Execution**: Processing asynchronous tasks from the CLI or future remote interfaces.
-   **State Management**: Maintaining the App Registry and Secure Vault.

### 2. The Sandbox Inception Model
Armorer uses a "Docker-out-of-Docker" pattern. The Core container mounts the host's `/var/run/docker.sock`, allowing it to manage the lifecycle of other containers (the agents) without being physically "inside" them.

## The "Superior Observer" Security Model

Armorer is designed with a **Unidirectional Privilege Boundary**. This ensures that even if an agent is fully compromised, it cannot attack the oversight system.

### How it Works:
1.  **Isolation**: Every agent runs in its own isolated Docker container.
2.  **RW Access**: The Armorer Core mounts the agent's data volume with **Read-Write** permissions. It can see and edit everything the agent does.
3.  **Invisible Sentry**: The agent has **no network access** to the Armorer Core. It cannot "see" the oversight process or the CLI.
4.  **Host-Level Protection**: Because the Core manages the volumes from the "sibling" level, it can redact a secret on the host filesystem before the agent even has a chance to process the next turn.

### Priviledge Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as Armorer CLI
    participant Core as Armorer Core (Superior)
    participant Agent as Agent Sandbox (Inferior)
    
    User->>CLI: "Check logs for keys"
    CLI->>Core: Create Task (Inbox)
    Core->>Agent: Inspect Files (RW Volume)
    Note over Core,Agent: Agent cannot see Core
    Core->>Agent: Redact Secret (Write)
    Core->>CLI: Return Result (Outbox)
    CLI->>User: "Redaction Complete"
```

## Path Translation
When running in Docker, Armorer intelligently translates paths between the container environment and the host system using the `HOST_PROJECT_ROOT` variable. This ensures that volume mounts always point to the correct physical location on your machine.

## Graph-Based Installation

Armorer uses a **deterministic directed graph** (DAG) architecture to orchestrate the installation process. This ensures robust, step-by-step execution where the output of one agent becomes the input for the next.

```mermaid
graph LR
    User[User Request] --> Researcher
    Researcher[Researcher Agent] -->|Research Summary| Planner[Planner Agent]
    Planner -->|Deployment Plan| Executor[Execution Engine]
    
    subgraph "Installer Graph"
    Researcher
    Planner
    end
```

- **Researcher**: Explores documentation, verifies Docker images, and identifies installation patterns.
- **Planner**: Synthesizes research into a strictly valid `docker-compose.yml` and a set of run commands.
- **Executor**: Applies the plan and enters the stabilization loop.

## Agentic Repair Loop

When a deployment fails, Armorer enters an autonomous repair cycle. The repair agent has access to multiple tools and maintains conversation state across attempts:

```mermaid
flowchart TD
    A[Deploy Fails] --> B[Collect Error Context]
    B --> C{read_logs: Navigate Full Log}
    C --> D[_get_auto_fix: LLM Diagnosis]
    D --> E{Tools Available}
    E --> F[shell: Inspect containers]
    E --> G[file_write: Fix configs]
    E --> H[google_search: Research errors]
    E --> I[search_knowledge: KB lookup]
    E --> J[read_logs: Deep log dive]
    D --> K[Apply Fix]
    K --> L[Feed Result Back to Agent A3]
    L --> M[Save Fix to KB]
    M --> N{Stable?}
    N -->|No| B
    N -->|Yes| O[Done]
```

### Key Design Decisions
- **Head+Tail + Paginated Logs**: The initial prompt shows the first 40 and last 40 lines. The agent can use `read_logs` to navigate any section of the full log.
- **Google Grounding Search**: When KB knowledge is insufficient, the agent can search the web for cited, authoritative answers using Google's grounding API.
- **Feedback Loop (A3)**: After each fix, the result is fed back into the agent's conversation so it can reason about whether the fix worked.
- **Learned Fixes**: Successful repair patterns are persisted to `~/.armorer/knowledge/learned_fixes.md` for future sessions.

## Knowledge System

Armorer's knowledge base consists of Markdown files loaded from two locations:

1. **Built-in KB** (`src/armorer/knowledge/`): Docker patterns, troubleshooting, security, networking, databases, Dockerfile patterns, ARM/multiarch, healthchecks, and error dictionaries.
2. **User KB** (`~/.armorer/knowledge/`): Custom knowledge files dropped in by the user, plus automatically learned fixes.

The `KnowledgeBase` class provides keyword search across all topics. Agents access it via three tools: `search_knowledge`, `get_knowledge_topic`, and `list_knowledge_topics`.

