NxM Agent Architecture

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#21262d', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'edgeLabelBackground': '#0d1117'}}}%%
flowchart TD
    subgraph sched ["Scheduler"]
        cron_bran["⏰ cron 06:00 daily"]
        cron_varys["⏰ cron every 15 min"]
    end

    subgraph agents ["One-Shot Agents"]
        bran["bran-changelog"]
        varys["varys-monitor"]
    end

    subgraph research ["Research Agent"]
        sam["sam-research :8500"]
        searxng["SearXNG :8600"]
    end

    subgraph notify ["Notification Agent"]
        raven["raven-notify :8400"]
        discord["Discord webhook"]
        email["Gmail SMTP"]
    end

    subgraph external ["External Sources"]
        github["GitHub API"]
        opnsense["OPNsense changelog"]
        web_ext["Web (search results)"]
    end

    subgraph llm ["LLM Layer"]
        hodor["hodor-gateway :8200"]
        ollama["Ollama :11434"]
    end

    subgraph infra ["Infrastructure — 12 services"]
        svc["portainer · gitea · open-webui · npm\nuptime-kuma · headscale · vaultwarden\nplane · homarr · netbox · hodor · citadel"]
    end

    subgraph storage ["Shared Storage — /opt/"]
        sites["sites/\nchangelog/  varys/  bran/  sam/  citadel/  raven/"]
        agentOS["agent-os/logs/\nbran-changelog/  varys-monitor/  sam-research/  citadel-mcp/  raven-notify/"]
    end

    subgraph serving ["Serving Layer"]
        nginx["agent-sites nginx"]
        citadel["citadel-mcp :8300"]
    end

    subgraph gui ["User Interface"]
        web["agents.nxm.co.za"]
        openwebui["Open WebUI :3010"]
    end

    cron_bran --> bran
    cron_varys --> varys

    bran -->|fetch releases| github
    bran -->|fetch changelog| opnsense
    github --> bran
    opnsense --> bran
    bran -->|POST /ask| hodor
    hodor <-->|api/chat| ollama
    hodor --> bran

    varys -->|HTTP GET| svc
    varys -->|POST /notify on down/recovery| raven
    raven -->|webhook| discord
    raven -->|SMTP| email

    sam -->|GET /search| searxng
    searxng -->|results| web_ext
    web_ext --> searxng
    sam -->|POST /api/chat| ollama
    ollama --> sam

    openwebui -->|web_search MCP tool| citadel
    citadel -->|GET /search| searxng
    openwebui -->|sam_research MCP tool| citadel
    citadel -->|POST /research| sam

    bran -->|index.html + last-output.md| sites
    bran -->|last-run.json| agentOS
    varys -->|index.html + last-output.md| sites
    varys -->|last-run.json| agentOS
    sam -->|index.html + last-output.md| sites
    sam -->|last-run.json| agentOS
    citadel -->|index.html + last-output.md| sites
    citadel -->|last-run.json| agentOS
    raven -->|index.html + last-output.md| sites
    raven -->|last-run.json| agentOS

    sites --> nginx
    nginx -->|NPM proxy| web

    agentOS -->|list_agents / get_agent_status| citadel
    sites -->|get_agent_output| citadel
    citadel -->|MCP tools| openwebui