System Overview¶

Lango is organized into four architectural layers. Each layer has a clear responsibility boundary, and dependencies flow strictly downward: Presentation depends on Agent, Agent depends on Intelligence, and all layers depend on Infrastructure.

Architecture Diagram¶

graph TB
    subgraph Presentation["Presentation Layer"]
        CLI["CLI (Cobra)"]
        TUI["TUI"]
        TG["Telegram"]
        DC["Discord"]
        SL["Slack"]
        GW["Gateway<br/>(HTTP/WebSocket)"]
    end

    subgraph AgentLayer["Agent Layer"]
        ADK["ADK Agent<br/>(Google ADK v0.4.0)"]
        ORCH["Orchestration<br/>(Multi-Agent)"]
        TOOLS["Tools<br/>(exec, fs, browser,<br/>crypto, payment)"]
        SKILL["Skills<br/>(30 embedded defaults)"]
        A2A["A2A Protocol<br/>(Remote Agents)"]
    end

    subgraph Intelligence["Intelligence Layer"]
        KS["Knowledge Store<br/>(8-layer context)"]
        LE["Learning Engine<br/>(Self-Learning Graph)"]
        MEM["Observational Memory<br/>(Observer + Reflector)"]
        EMB["Embedding / RAG<br/>(Vector Search)"]
        GR["Graph Store<br/>(BoltDB Triple Store)"]
        GRAM["Graph RAG<br/>(Hybrid Retrieval)"]
        LIB["Librarian<br/>(Proactive Extraction)"]
    end

    subgraph Infra["Infrastructure Layer"]
        CFG["Config"]
        SEC["Security<br/>(Crypto, Secrets)"]
        SESS["Session Store<br/>(Ent/SQLite)"]
        LOG["Logging (Zap)"]
        PAY["Payment<br/>(USDC, X402)"]
        PROV["AI Providers<br/>(OpenAI, Gemini, Claude)"]
        AUTO["Automation<br/>(Cron, Background,<br/>Workflow)"]
    end

    CLI --> GW
    TUI --> GW
    TG --> GW
    DC --> GW
    SL --> GW
    GW --> ADK
    ADK --> ORCH
    ADK --> TOOLS
    ADK --> SKILL
    ORCH --> A2A
    ADK --> PROV
    ADK --> KS
    ADK --> MEM
    ADK --> EMB
    KS --> LE
    EMB --> GR
    GR --> GRAM
    KS --> LIB
    MEM --> LIB
    ADK --> SESS
    TOOLS --> SEC
    PAY --> SEC
    AUTO --> ADK

Layer Descriptions¶

Presentation Layer¶

The presentation layer handles all user-facing interactions. It contains no business logic -- each component is a thin adapter that accepts input, forwards it to the Agent layer via the Gateway, and formats the response for output.

Agent Layer¶

The agent layer is the core runtime. It manages the AI agent lifecycle, tool execution, prompt assembly, and multi-agent orchestration.

Intelligence Layer¶

The intelligence layer provides the agent with persistent knowledge, learning capabilities, and semantic retrieval. All components are optional and enabled via configuration flags.

Infrastructure Layer¶

The infrastructure layer provides foundational services that all other layers depend on.

Key Design Decisions¶

Callback pattern for async processing. Stores expose SetEmbedCallback and SetGraphCallback methods. When a knowledge entry or memory observation is saved, the callback enqueues an async request to the corresponding buffer (EmbeddingBuffer or GraphBuffer). This avoids import cycles between the intelligence subsystems.

Optional subsystems with graceful degradation. Every intelligence component checks a config flag during initialization. If a component fails to initialize (missing dependency, database error), the application continues without it. The initKnowledge, initMemory, initEmbedding, initGraphStore functions all return nil on failure rather than terminating the application.

Context-aware prompt assembly. The ContextAwareModelAdapter wraps the base LLM and intercepts every GenerateContent call. It runs knowledge retrieval, RAG search, and memory lookup in parallel using errgroup, then assembles the results into an augmented system prompt before forwarding to the AI provider.

Tool adaptation layer. Internal tools use a simple agent.Tool struct with a map-based parameter definition. The adk.AdaptTool() function converts these to the ADK's tool.Tool interface with proper JSON Schema, allowing tools to be defined without depending on ADK types directly.