```mermaid
%% MCP Application Architecture
%% Updated from codebase analysis -- March 2026

graph TD
    %% =========================================================================
    %% SUPERVISION TREE
    %% =========================================================================
    subgraph Supervisor["Mcp.Supervisor (one_for_one)"]
        direction TB
        UsersDB["Sqler<br/>:users_db"]
        CompileLogDB["Sqler<br/>:compile_log_db"]
        Manager["MCPServer.Manager"]
        HTTPS["Bandit HTTPS :8443<br/>MCPServer.Router"]
        AC["AutoCompile"]
        LS["LogSubscriber"]
        AL["Alarm"]
        PO["Pushover"]
        MCT["MCPClientTracker"]
        ChatDB["Sqler<br/>:chat_db"]
        SCT["ServerChatTracker"]
        SchedDB["Sqler<br/>:scheduler"]
        A2ADB["Sqler<br/>:a2a_db"]
        TasksDB["Sqler<br/>:tasks_db"]
        PSDB["Sqler<br/>:page_scraper_db"]
        PSReg["Registry<br/>PageScraperRegistry"]
        ZmqReg["Registry<br/>ZmqCounter"]
        WsReg["Registry<br/>WsRegistry"]
        ToolAudit["ToolAudit"]
        MonSrv["MonitorServer"]
        APP["App"]
        WFExec["WorkflowExecutor"]
        MCPConnReg["MCPConnectionRegistry"]
        MCPConnRegR["Registry<br/>MCPConnectionRegistry"]
        MCPConnSup["MCPConnectionRegistry<br/>Supervisor"]
        KnowledgeDB["Sqler<br/>:knowledge_db"]
        ContactFormsDB["Sqler<br/>:contact_forms_db"]
        LLMFinch["LLMGateway.Finch"]
        LLMGwDB["Sqler<br/>:llm_gateway_db"]
        PermPubSub["Registry<br/>PermissionPubSub"]
        SseReg["Registry<br/>SseRegistry"]
        SessionReg["Registry<br/>McpSessionRegistry"]
        BFW["BlogFileWatcher"]
        SLW["ServerLogWriter"]
        Tidewave["Bandit :4001<br/>Tidewave (dev)"]
    end

    %% =========================================================================
    %% EXTERNAL ACTORS
    %% =========================================================================
    Browser(("Browser<br/>(User)"))
    IEx(("IEx<br/>Console"))
    FS(("Filesystem<br/>Events"))
    PushAPI(("Pushover<br/>API"))
    AnthropicAPI(("Anthropic<br/>API"))
    OpenRouterAPI(("OpenRouter<br/>API"))
    PerplexityAPI(("Perplexity<br/>API"))
    GeminiAPI(("Google<br/>Gemini API"))
    OpenAIAPI(("OpenAI<br/>API"))
    PythonProc(("Python<br/>ZeroMQ"))
    ApifyMCP(("Apify Weather<br/>MCP Server"))
    VoyagerAPI(("VoyageAI<br/>Embeddings"))
    WhatsAppBridge(("WhatsApp<br/>Node.js Bridge"))
    ElevenLabsAPI(("ElevenLabs<br/>TTS API"))
    YouTubeAPI(("YouTube<br/>Data API v3"))
    GoogleWS(("Google Workspace<br/>MCP Server"))
    AgentMailAPI(("AgentMail<br/>API"))
    GoogleOIDC(("Google<br/>OIDC"))
    ClaudeCLI(("Claude Code<br/>CLI"))

    %% =========================================================================
    %% HTTP REQUEST FLOW
    %% =========================================================================
    Browser -- "HTTPS :8443" --> HTTPS
    ClaudeCLI -- "SSE :8443<br/>Bearer token" --> HTTPS
    ClaudeCLI -- "HTTP :4001<br/>Tidewave MCP" --> Tidewave

    subgraph RouterLogic["MCPServer.Router (Plug.Router)"]
        direction TB
        Auth["require_authentication<br/>cookie decrypt / bearer token"]
        CSRF["csrf_protection"]
        Routes["Routes:<br/>POST /login . POST /message . GET /sse<br/>GET /chat . GET /blogs . GET /tasks<br/>GET /nis . GET /monitor . GET /access-control<br/>GET /summaries . GET /workflow . GET /workflows<br/>GET /knowledge . GET /mcp-connections<br/>POST /mcp . POST /a2a . /api/*"]
        GetUser["get_user/1<br/>Auth.AuthContext.for_user!"]
    end

    HTTPS --> Auth
    Auth --> CSRF
    CSRF --> Routes
    Routes --> GetUser

    %% =========================================================================
    %% MCP SERVER LAYER
    %% =========================================================================
    subgraph MCPLayer["MCP Server Layer (~100+ tools)"]
        direction TB
        Manager
        MCP["MCPServer<br/>(Hermes.Server behaviour)"]
        subgraph PermLayer["Permissions Layer (AccessControlled)"]
            direction LR
            PPlatform["Platform"]
            PWhatsApp["WhatsApp"]
            PNis["NIS"]
            PSummaries["Summaries"]
            PBlogs["Blogs"]
            PAdmin["Admin"]
            PMonitor["Monitor"]
            PYouTube["YouTube"]
            PWorkflow["Workflow"]
            PKnowledge["Knowledge"]
            PAgentMail["AgentMail"]
            PChat["Chat"]
            PMCPConn["MCPConnection"]
        end
    end

    Routes -- "tools/call . tools/list<br/>resources/list . resources/read<br/>(user.id)" --> Manager
    Manager -- "Auth.AuthContext.for_user!/1" --> UserMod
    Manager -- "handle_tool_call/3<br/>MCP.Telemetry.span_tool_call" --> MCP
    MCP -- "permission-gated dispatch" --> PermLayer
    MCP -- "fallback: proxy to<br/>external MCP servers" --> MCPConnReg

    %% =========================================================================
    %% MCP CONNECTION REGISTRY (External MCP Proxy)
    %% =========================================================================
    subgraph MCPConnLayer["MCP Connection Registry"]
        direction TB
        MCPConnReg
        MCPConnSup
        MCPClient["MCPClient<br/>(per-connection)"]
    end

    MCPConnReg -- "start_link per server" --> MCPClient
    MCPClient -- "Streamable HTTP" --> GoogleWS

    %% =========================================================================
    %% MCP CLIENT LAYER
    %% =========================================================================
    subgraph ClientLayer["MCP Client Layer"]
        direction TB
        MCT
        Client["MCPClient<br/>(GenServer, per-user)"]
    end

    IEx -- "Example.run_demo/0" --> MCT
    MCT -- "get_or_start(user_id)" --> Client
    Client -- "call_tool/3 . list_tools/1<br/>list_resources/1 . read_resource/2" --> Manager

    %% =========================================================================
    %% CHAT LAYER
    %% =========================================================================
    subgraph ChatLayer["Chat Layer (LLM Integration)"]
        direction TB
        SCT
        SC["ServerChat<br/>(GenServer, per-user<br/>30-min idle timeout)"]
        subgraph Providers["Pluggable Providers (ServerChat.Provider behaviour)"]
            direction LR
            ProvAnthropic["ServerChat.Anthropic"]
            ProvOpenRouter["ServerChat.OpenRouter"]
            ProvPerplexity["ServerChat.Perplexity"]
        end
    end

    Routes -- "POST /chat . /api/chat/*" --> SCT
    SCT -- "get_or_start(user_id)" --> SC
    SC -- "list_tools . call_tool" --> Manager
    SC -- "call_llm/4<br/>(with MCP tools)" --> Providers
    ProvAnthropic -- "HTTP POST<br/>/v1/messages" --> AnthropicAPI
    ProvOpenRouter -- "HTTP POST<br/>/v1/chat/completions" --> OpenRouterAPI
    ProvPerplexity -- "HTTP POST<br/>/v1/responses" --> PerplexityAPI
    SC -- "persist history" --> ChatDB

    %% =========================================================================
    %% USER & AUTH & ACCESS CONTROL
    %% =========================================================================
    subgraph UserAuth["User, Auth & Access Control"]
        direction TB
        UserMod["User<br/>create . authenticate<br/>sessions . delete"]
        Argon["Argon2<br/>password hashing"]
        AccessCtrl["AccessControl<br/>roles . grants . TTL keys<br/>AES-256-CTR encryption<br/>PubSub broadcast"]
        GoogleAuth["GoogleAuth<br/>OIDC Sign-In"]
    end

    GetUser --> UserMod
    Routes -- "POST /login<br/>authenticate" --> UserMod
    Routes -- "GET /auth/google/*" --> GoogleAuth
    GoogleAuth -- "OIDC verify" --> GoogleOIDC
    UserMod --> Argon
    UserMod -- "SQL queries" --> UsersDB
    UserMod -- "grant/revoke" --> AccessCtrl
    AccessCtrl -- "SQL queries (encrypted)" --> UsersDB
    AccessCtrl -- "broadcast" --> PermPubSub
    Manager -- "get_permissions" --> AccessCtrl

    %% =========================================================================
    %% WORKFLOW ENGINE
    %% =========================================================================
    subgraph WorkflowSystem["Workflow Engine"]
        direction TB
        WFExec
        WF["Workflow<br/>steps . branches . joins<br/>templates . scheduling"]
        WFWeb["WorkflowWeb<br/>SPA (create + list)"]
        WFDB["Sqler<br/>:workflow_db"]
    end

    Routes -- "/workflow . /workflows<br/>/api/workflow/*" --> WFWeb
    WFExec -- "poll ready steps<br/>watchdog stuck steps" --> WF
    WFExec -- "call_tool" --> Manager
    WFExec -- "schedule retries<br/>scheduled start" --> AL
    WF --> WFDB

    %% =========================================================================
    %% KNOWLEDGE BASE
    %% =========================================================================
    subgraph KnowledgeSystem["Knowledge Base"]
        direction TB
        Knowledge["Knowledge<br/>vector + FTS search<br/>tags . chunked docs"]
    end

    Routes -- "/knowledge . /api/knowledge/*" --> Knowledge
    Knowledge -- "embeddings" --> VoyagerAPI
    Knowledge --> KnowledgeDB

    %% =========================================================================
    %% WHATSAPP
    %% =========================================================================
    subgraph WhatsAppSystem["WhatsApp Integration"]
        direction TB
        WA["WhatsApp<br/>(GenServer, singleton)"]
        WAClaude["WhatsAppClaude<br/>(AI auto-responder)"]
    end

    WA -- "ZeroMQ REQ/REP + SUB<br/>JSON messages" --> WhatsAppBridge
    WAClaude -- "incoming messages" --> WA
    WAClaude -- "call_tool . list_tools" --> Manager

    %% =========================================================================
    %% NIS CRM
    %% =========================================================================
    subgraph NisSystem["NIS -- Personal CRM"]
        direction TB
        Nis["Nis<br/>contacts . companies<br/>websites . activities"]
        NisDB["Sqler<br/>:nis_db (per-user<br/>30-min idle timeout)"]
    end

    Routes -- "/nis . /api/nis/*" --> Nis
    Nis --> NisDB

    %% =========================================================================
    %% TASK MANAGEMENT
    %% =========================================================================
    subgraph TaskSystem["Task Management"]
        direction TB
        TaskMgr["TaskManager<br/>60+ query functions<br/>recurrence engine"]
        TaskW["TaskWeb<br/>HTML rendering"]
        TaskCap["TaskCapture<br/>NL parsing"]
    end

    Routes -- "/tasks . /api/tasks/*" --> TaskW
    TaskW --> TaskMgr
    TaskCap --> TaskMgr
    TaskMgr --> TasksDB

    %% =========================================================================
    %% SUMMARIES
    %% =========================================================================
    subgraph SummarySystem["Article Summaries"]
        direction TB
        Summary["Summary<br/>async LLM summarization<br/>vector + FTS search"]
        SummDB["Sqler<br/>:summaries_db"]
    end

    Routes -- "/summaries . /api/summaries/*" --> Summary
    Summary -- "LLM summarize" --> AnthropicAPI
    Summary -- "embeddings" --> VoyagerAPI
    Summary --> SummDB

    %% =========================================================================
    %% BLOG SYSTEM
    %% =========================================================================
    subgraph BlogSystem["Blog System"]
        direction TB
        Blog["Blog<br/>file-based posts<br/>Summernote editor"]
        BlogStoreM["BlogStore<br/>chunks . vector + FTS<br/>semantic search"]
        BlogsDB["Sqler<br/>:blogs_store_db"]
        BFW
    end

    Routes -- "/blog* . /blogs . /api/blogs/*" --> Blog
    Blog -- "read/write" --> BlogFiles["asset/blogs/"]
    BFW -- "file change" --> BlogStoreM
    BlogStoreM -- "embeddings" --> VoyagerAPI
    BlogStoreM --> BlogsDB

    %% =========================================================================
    %% AGENTMAIL
    %% =========================================================================
    subgraph AgentMailSystem["AgentMail"]
        direction TB
        AM["AgentMail<br/>per-user inbox<br/>send . reply . forward"]
    end

    MCP -- "agentmail_*" --> AM
    AM -- "HTTP REST" --> AgentMailAPI

    %% =========================================================================
    %% LLM GATEWAY
    %% =========================================================================
    subgraph LLMGatewaySystem["LLM Gateway"]
        direction TB
        LLMGw["LLMGateway<br/>reverse proxy<br/>audit + security scanning"]
        LLMFinch
    end

    Routes -- "/llm-gateway/*" --> LLMGw
    LLMGw -- "proxy" --> AnthropicAPI
    LLMGw -- "proxy" --> OpenAIAPI
    LLMGw -- "audit log" --> LLMGwDB

    %% =========================================================================
    %% MONITOR
    %% =========================================================================
    subgraph MonitorSystem["System Monitor"]
        direction TB
        Monitor["Monitor<br/>stateless metrics"]
        MonSrv
    end

    Routes -- "/monitor . /api/monitor/*" --> MonSrv
    MonSrv -- "periodic polling<br/>anomaly detection" --> Monitor

    %% =========================================================================
    %% YOUTUBE
    %% =========================================================================
    YouTube["YouTube<br/>OAuth2 refresh-token<br/>list subscriptions"] -- "HTTP GET<br/>subscriptions.list" --> YouTubeAPI

    %% =========================================================================
    %% TTS
    %% =========================================================================
    TTS["Tts<br/>text-to-speech"] -- "HTTP POST<br/>eleven_multilingual_v2" --> ElevenLabsAPI

    %% =========================================================================
    %% PAGE SCRAPER
    %% =========================================================================
    subgraph PageScraperSystem["PageScraper (Browser DOM Extraction)"]
        direction TB
        PS["PageScraper<br/>URL patterns + DB"]
        PSS["PageScraperServer<br/>(per user+pattern)"]
        PSH["Handler<br/>(e.g. GithubPR)"]
    end

    Browser -- "WebSocket<br/>page_visit . dom_result" --> WsH["WsHandler"]
    WsH -- "match_url" --> PS
    WsH -- "get_or_start" --> PSS
    PSS -- "on_match . on_extraction" --> PSH
    PSS -- "dom_command" --> WsH
    PSS --> PSDB

    %% =========================================================================
    %% A2A PROTOCOL
    %% =========================================================================
    subgraph A2ALayer["A2A Protocol (Google Agent-to-Agent)"]
        direction TB
        A2AS["A2AServer<br/>JSON-RPC 2.0"]
        A2AC["A2AClient<br/>stateless HTTP"]
    end

    Routes -- "POST /a2a<br/>GET /.well-known/agent.json" --> A2AS
    A2AS -- "call_tool_as" --> Manager
    A2AS --> A2ADB

    %% =========================================================================
    %% DATABASE LAYER
    %% =========================================================================
    subgraph Database["Database Layer (SQLite via Sqler, 15+ instances)"]
        direction LR
        UsersDB
        CompileLogDB
        ChatDB
        SchedDB
        A2ADB
        TasksDB
        PSDB
        SummDB
        BlogsDB
        NisDB
        KnowledgeDB
        ContactFormsDB
        LLMGwDB
        WFDB
        AlarmDB["Sqler<br/>(alarm, inline)"]
        AppDB["Sqler<br/>(app, inline)"]
    end

    %% =========================================================================
    %% COMPILATION & LOGGING
    %% =========================================================================
    subgraph CompileFlow["Auto-Compilation"]
        direction TB
        AC
        CL["CompileLog<br/>log compilations<br/>with git diff"]
    end

    FS -- "file changes" --> AC
    AC -- "Code.compile_file/1" --> AC
    AC -- "log compilation" --> CL
    CL -- "SQL insert" --> CompileLogDB

    %% =========================================================================
    %% LOGGING PIPELINE
    %% =========================================================================
    subgraph LogPipeline["Logging Pipeline"]
        direction LR
        Logger["Logger"]
        LN["LoggerNotifier<br/>(gen_event backend)"]
        Notifier["Notifier<br/>(gproc pub/sub)"]
        LS
        SLW
    end

    Logger -- "log events" --> LN
    LN -- "notify" --> Notifier
    Notifier -- "cast" --> LS
    LS -- "IO.puts<br/>ANSI colors" --> IEx
    SLW -- "write to disk" --> LogFiles["priv/logs/"]

    %% =========================================================================
    %% ALARM, TIMER & SCHEDULER
    %% =========================================================================
    subgraph AlarmSystem["Alarm, Timer & Scheduler"]
        direction TB
        AL
        TI["Timer<br/>(Process.send_after)"]
        Sched["Scheduler<br/>(callback orchestration)"]
        PO
    end

    AL -- "set_timer" --> TI
    TI -- "fire alarm" --> AL
    AL --> AlarmDB
    Sched -- "set_alarm/3<br/>(stores {m,f,a})" --> AL
    Sched -- "SQL persistence" --> SchedDB
    PO -- "HTTP POST" --> PushAPI
    AL -- "scheduled push" --> PO

    %% =========================================================================
    %% ZEROMQ BRIDGE
    %% =========================================================================
    subgraph ZmqLayer["ZeroMQ Bridge"]
        direction TB
        ZmqReg
        ZMQ["ZmqCounter<br/>(GenServer, per-instance<br/>chumak or erlzmq backends)"]
    end

    ZMQ -- "MuonTrap + ZeroMQ<br/>TCP/IPC . JSON messages" --> PythonProc

    %% =========================================================================
    %% STANDALONE UTILITIES
    %% =========================================================================
    subgraph Utilities["Standalone Utilities"]
        direction TB
        subgraph WeatherScripts["Weather Chat Scripts (demo/test)"]
            direction LR
            WC["WeatherChat<br/>(Claude + MCP)"]
            WCG["WeatherChatGemini"]
            WCO["WeatherChatOpenAI"]
        end
        Voyager["VoyagerEmbeddings<br/>voyage-3 . 1024-dim"]
        SysTZ["SystemTimezone<br/>cross-platform TZ"]
        TxtChunk["TextChunker<br/>sentence-aware splitting"]
    end

    WC -- "tool calling" --> AnthropicAPI
    WCG -- "function calling" --> GeminiAPI
    WCO -- "tool calling" --> OpenAIAPI
    WC -- "MCP weather tool" --> ApifyMCP
    Voyager -- "HTTP POST" --> VoyagerAPI

    %% =========================================================================
    %% APP MODULE
    %% =========================================================================
    APP -- "term storage" --> AppDB

    %% =========================================================================
    %% DOCS & MANUALS
    %% =========================================================================
    Routes -- "/docs/* . /manuals/*" --> DocsRouter["DocsRouter"]
    DocsRouter -- "static files" --> DocsFiles["asset/docs/<br/>asset/manuals/"]

    %% =========================================================================
    %% CONTACT FORM
    %% =========================================================================
    Routes -- "POST /contact" --> ContactForm["ContactForm"]
    ContactForm --> ContactFormsDB

    %% =========================================================================
    %% TELEMETRY
    %% =========================================================================
    Manager -- ":telemetry events" --> ToolAudit

    %% =========================================================================
    %% STYLING
    %% =========================================================================
    classDef genserver fill:#4a9eff,stroke:#2d6cb4,color:#fff
    classDef database fill:#50c878,stroke:#2d8b4e,color:#fff
    classDef external fill:#ff9f43,stroke:#b36f2f,color:#fff
    classDef router fill:#a55eea,stroke:#7b3fb5,color:#fff
    classDef module fill:#778ca3,stroke:#4b6078,color:#fff
    classDef provider fill:#e056a0,stroke:#a03d74,color:#fff
    classDef utility fill:#45aaf2,stroke:#2d7abf,color:#fff

    class Manager,Client,MCT,AC,LS,AL,TI,PO,APP,SC,SCT,Sched,ZMQ,WA,WAClaude,MonSrv,ToolAudit,PSS,WFExec,MCPConnReg,BFW,SLW genserver
    class UsersDB,CompileLogDB,SchedDB,AlarmDB,AppDB,ChatDB,A2ADB,TasksDB,PSDB,SummDB,BlogsDB,NisDB,KnowledgeDB,ContactFormsDB,LLMGwDB,WFDB database
    class Browser,IEx,FS,PushAPI,AnthropicAPI,OpenRouterAPI,PerplexityAPI,GeminiAPI,OpenAIAPI,PythonProc,ApifyMCP,VoyagerAPI,WhatsAppBridge,ElevenLabsAPI,YouTubeAPI,GoogleWS,AgentMailAPI,GoogleOIDC,ClaudeCLI external
    class HTTPS,Routes,Auth,CSRF,DocsRouter router
    class MCP,UserMod,CL,LN,Notifier,GetUser,Argon,Blog,BlogStoreM,TaskMgr,TaskW,TaskCap,A2AS,A2AC,PS,PSH,Summary,Nis,Monitor,YouTube,TTS,AccessCtrl,GoogleAuth,WF,WFWeb,Knowledge,AM,LLMGw,ContactForm module
    class ProvAnthropic,ProvOpenRouter,ProvPerplexity provider
    class WC,WCG,WCO,Voyager,SysTZ,TxtChunk utility
    class PPlatform,PWhatsApp,PNis,PSummaries,PBlogs,PAdmin,PMonitor,PYouTube,PWorkflow,PKnowledge,PAgentMail,PChat,PMCPConn module
```