# 0x4d31/galah architecture

> Architecture diagram of the GitHub repository 0x4d31/galah, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0x4d31/galah
- Repository: https://github.com/0x4d31/galah

## Overview

##### Project Type and Purpose
- Galah is a backend service (written in Go) that acts as an LLM-powered web honeypot.
- It exposes an HTTP interface, dynamically generates responses to arbitrary HTTP requests using various LLM providers, applies optional Suricata rule matching, caches responses, and logs events.

##### File Structure Analysis
- cmd/galah: CLI entry point (main.go).
- internal/: core service implementation
- internal/server: HTTP server setup
- internal/app: application orchestration (wiring CLI flags → config → service)
- internal/config: config loader (YAML) and rule loader
- internal/cache: response cache (SQLite or file DB)
- internal/logger: event logger, session context
- pkg/: external integrations
- pkg/llm: adapters for LLM providers (OpenAI, GoogleAI, Anthropic, Cohere, Ollama, etc.)
- pkg/enrich: post-processing/middleware for HTTP responses
- pkg/suricata: Suricata rule engine support
- config/: YAML templates for prompts and Suricata rules
- data/: sample event logs
- templates/: JSON response templates
- deploy/: Docker/Kubernetes manifests
- docs/: architecture and usage examples

##### Key Architecture Points from README
- HTTP server receives arbitrary requests on configurable ports
- Requests optionally go through Suricata rule inspection
- Response flow:
a) Check cache → if hit, return cached HTTP response
b) If miss, invoke LLM adapter → generate HTTP headers & body in JSON
c) Store in cache (per-port, configurable TTL)
d) Log full event (request + response + metadata + Suricata matches)
- Supports multiple LLM providers via the pkg/llm package
- Exposed as CLI or embedded as a Go library

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% CLI and Library Entry Points
    subgraph "Entry Points"
        CLI["CLI (cmd/galah/main.go)"]:::ingress
        Library["Library API (galah/service.go)"]:::ingress
    end

    %% Application Orchestration
    App["App Orchestration\n(internal/app/app.go,\nargs.go)"]:::ingress

    %% Configuration Management
    subgraph "Configuration"
        ConfigCode["Config Loader\n(internal/config)"]:::config
        ConfigYAML["config/config.yaml &\nconfig/rules.yaml"]:::config
    end

    %% Main Service Layers
    subgraph "HTTP Ingress & Routing"
        HTTP["HTTP Server\n(internal/server/server.go)"]:::ingress
        Suricata["Suricata Engine\n(pkg/suricata)"]:::rule
    end

    subgraph "Cache Layer"
        Cache["Cache DB (SQLite)\n(internal/cache/cache.go)"]:::cache
    end

    subgraph "LLM Adapter Layer"
        LLM["LLM Adapters\n(pkg/llm)"]:::llm
        ExternalLLM["External LLM Providers"]:::external
    end

    %% Event Logging
    Logger["Event Logger\n(internal/logger/logger.go)"]:::logger

    %% Response Templates & Enrichment
    Enrich["Response Enrichment\n(pkg/enrich/enrich.go)"]:::llm
    Templates["JSON Templates\n(templates/*.json)"]:::config

    %% Deployment & Samples
    subgraph "Deployment & Samples"
        Docker["Dockerfile"]:::deploy
        K8s["deploy/galah.yml"]:::deploy
        SampleLogs["Sample Event Logs\n(data/*.json)"]:::deploy
    end

    %% Data Flow
    Client --> CLI
    Client --> Library
    CLI --> App
    Library --> App
    App --> ConfigCode
    App --> HTTP

    ConfigCode --> Suricata
    ConfigYAML --> Suricata
    ConfigCode --> LLM
    ConfigYAML --> LLM
    Templates --> Enrich

    HTTP -->|Optional via --suricata-enabled| Suricata
    Suricata --> HTTP

    HTTP -->|"Cache Lookup"| Cache
    Cache -->|Hit| HTTP
    Cache -->|Miss| LLM

    LLM --> Enrich
    Enrich --> ExternalLLM
    ExternalLLM --> LLM
    LLM -->|"Store Response"| Cache

    HTTP -->|"Send Response"| Client

    HTTP --> Logger
    Cache --> Logger
    LLM --> Logger
    Suricata --> Logger

    %% Deployment flows
    Docker --> HTTP
    K8s --> HTTP
    Logger --> SampleLogs

    %% Click Events
    click CLI "https://github.com/0x4d31/galah/blob/main/cmd/galah/main.go"
    click HTTP "https://github.com/0x4d31/galah/blob/main/internal/server/server.go"
    click App "https://github.com/0x4d31/galah/blob/main/internal/app/app.go"
    click Enrich "https://github.com/0x4d31/galah/blob/main/pkg/enrich/enrich.go"
    click Cache "https://github.com/0x4d31/galah/blob/main/internal/cache/cache.go"
    click LLM "https://github.com/0x4d31/galah/blob/main/pkg/llm/llm.go"
    click Suricata "https://github.com/0x4d31/galah/blob/main/pkg/suricata/rules.go"
    click ConfigCode "https://github.com/0x4d31/galah/blob/main/internal/config/config.go"
    click ConfigYAML "https://github.com/0x4d31/galah/blob/main/config/config.yaml"
    click Templates "https://github.com/0x4d31/galah/blob/main/templates/default.json"
    click Logger "https://github.com/0x4d31/galah/blob/main/internal/logger/logger.go"
    click Docker "https://github.com/0x4d31/galah/tree/main/Dockerfile"
    click K8s "https://github.com/0x4d31/galah/blob/main/deploy/galah.yml"
    click SampleLogs "https://github.com/0x4d31/galah/tree/main/data/"

    %% Styles
    classDef ingress fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef rule fill:#fff9c4,stroke:#f57f17,color:#f57f17;
    classDef cache fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32;
    classDef llm fill:#ffe0b2,stroke:#ef6c00,color:#ef6c00;
    classDef logger fill:#eceff1,stroke:#455a64,color:#455a64;
    classDef config fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a;
    classDef deploy fill:#fce4ec,stroke:#880e4f,color:#880e4f;
    classDef external fill:#ffffff,stroke:#000000,color:#000000,stroke-dasharray: 2 2;
```
