System Architecture

Andromity is engineered as a modular, open-source system consisting of the Python core runtime, native VS Code extension, and developer tooling.

Core SubsystemsCopy Anchor Link

High-Level TopologyCopy Anchor Link

graph TD
    subgraph Local Developer Machine
        ClientIDE[VS Code Secondary Sidebar]
        ClientCLI[Terminal TUI / CLI]
        AgentCore[Python Agent Core: src/andromity]
        LocalOllama[(Local Ollama - 100% Offline)]
    end

    subgraph LLM Providers
        Claude[Anthropic Claude 3.7]
        GPT[OpenAI GPT-4o]
        Gemini[Google Gemini 2.5]
        Groq[Groq LPU]
    end

    ClientIDE <--> AgentCore
    ClientCLI <--> AgentCore
    AgentCore -.->|Local Offline Inference| LocalOllama
    AgentCore -->|BYOK Direct API| Claude
    AgentCore -->|BYOK Direct API| GPT
    AgentCore -->|BYOK Direct API| Gemini
    AgentCore -->|BYOK Direct API| Groq

Core Architectural InvariantsCopy Anchor Link

Agents and contributors modifying Andromity must uphold the following invariants:

1. Trust Boundary First: Folder trust is resolved before permission checks. If a folder is untrusted, all mutating actions are unconditionally blocked.
2. Stateless Edge Gateway (Zero-PII): The gateway acts strictly as a stateless stream router. It never persists, logs, or stores user source code, prompts, completions, or file contents.
3. Guaranteed Real-Time Streaming: Token streams must use unbuffered ReadableStream SSE streaming (text/event-stream). Tokens must never be buffered in memory.
4. Lazy MCP Loading: Model Context Protocol (MCP) tool schemas are loaded lazily on demand to prevent prompt context window exhaustion.