Gopher Architecture

graph LR
    subgraph User["User Layer"]
        Browser["Browser / Mobile"]
    end

    subgraph GopherApp["Gopher App"]
        FastAPI["FastAPI Server"]
        Auth["Google OAuth + Session
session cookie key=session_token,
middleware name=gopher_session"]
        S2SAuth["S2S JWT
signs + verifies trusted app tokens"]
        AuditMW["Audit Middleware
wraps every request"]
        ModelSelect["Per-user Model Override
stored in user_settings(model) column"]
        AIAgent["AI Agent Loop
ollama.AsyncClient, gemma4:e4b-mlx-bf16
(env OLLAMA_MODEL), keep_alive=-1"]
        Dispatch["Tool Dispatch
+ sanitizer: formats tool results as plain English,
strips pagination + internal metadata"]
        ProactiveSvc["Proactive Messages
checks cached app_states for inbox0 must/should
and summarizer action counts; lazy refresh every 5 min"]
        RerunStrip["Rerun Handler
strips last assistant turn from message history"]
        LoopGuard["Loop Guard
3x same-tool = synthesize and return"]
        PollutionGuard["History-Pollution Guard
transient reminder injected into user's prompt
when re-asking a live-data question in same thread"]
        ToolFallback["Tool-Support Fallback
model lacks tool calling = friendly pick-a-model message, not 500"]
        Resolver["IdentityResolver
groups accounts by shared email/phone,
not login provider; _IDENTITY_APPS: inbox0, summarizer, ownscribe, almanac, weekly"]
        GopherFanout["Gopher Fan-out (api_weekly_context)
fans out to all apps in default context via httpx,
extracts tasks/focus/calendar/holidays/outstanding"]
    end

    subgraph ProtectWorker["Protect Worker (fully implemented)
protect/worker.py 829 lines]"]
        WSHandle["Binary WebSocket Protocol
parse events from UniFi NVR
_parse_ws_message() with dedup + buffering"]
        FaceMatch["InsightFace face recognition
buffalo_l model: extract + match faces
face.py for embedding extraction"]
        PlateDetect["License plate detection"]
        VehicleDetect["Vehicle make/model/color detection"]
        SnapshotMgmt["Snapshot download + disk storage
served via /api/protect/snapshot/{filename}"]
        EventQueue["Event queue processor
smartDetectZone add+update buffering
status tracking + dedup"]
    end

    subgraph Intelligence["Local Intelligence"]
        Ollama["Ollama"]
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL
14 tables")]
        Audit(("PostgreSQL Audit
cross-app aggregator
gopher writes here"))
    end

    subgraph CrossApp["Cross-App Integrations"]
        Inbox0API["inbox0
identity / accounts
OwnLifeOS tasks"]
        SummarizerAPI["Summarizer
identity / accounts"]
        OwnScribeAPI["OwnScribe
identity / accounts (confirmed)"]
        AlmanacAPI["Almanac
identity / accounts
weekly insights + 7-day meeting prep window
+ meeting notes from Google Doc linked on each event"]
        WeeklyAPI["Weekly
identity / accounts
consumed by Gopher's weekly context fan-out"]
    end

    subgraph Media["Media"]
        Immich["Immich"]
        UniFiNVR["UniFi Protect NVR"]
    end

    subgraph Infra["Infrastructure"]
        CF["Cloudflare Tunnel"]
        Docker["Docker Compose"]
    end

    Browser -->|HTTPS| CF
    CF -->|docker bridge| Docker
    Docker --> FastAPI
    FastAPI --> AuditMW
    AuditMW --> Auth
    Auth -->|sessions| PG
    FastAPI -->|store and fetch conversations| PG
    FastAPI -->|audit log| Audit
    FastAPI --> ModelSelect
    FastAPI --> ProactiveSvc
    FastAPI --> RerunStrip
    ModelSelect -->|model preference| PG
    ModelSelect --> AIAgent
    PollutionGuard -->|force tool call| AIAgent
    AIAgent -.->|no tool support| ToolFallback
    ToolFallback -->|graceful chat reply| FastAPI
    AIAgent -->|chat completions| Ollama
    AIAgent -->|tool calls| Dispatch
    RerunStrip --> AIAgent
    FastAPI -->|sync JSON + image injection| Browser
    Dispatch -->|sanitize: plain English, strip pagination
+ metadata| Inbox0API
    Dispatch -->|loop guard| LoopGuard
    LoopGuard -->|3x same tool| AIAgent
    Dispatch -->|fetch context| Resolver
    Resolver -->|signed S2S JWT + /api/identity/accounts to inbox0, summarizer, ownscribe, almanac, weekly| Inbox0API
    Resolver -->|value-based contexts
shared email/phone| FastAPI
    GopherFanout -->|S2S tasks/focus| Inbox0API
    GopherFanout -->|S2S tasks| SummarizerAPI
    GopherFanout -->|S2S ownlifeos links| OwnScribeAPI
    GopherFanout -->|weekly insights + meetings
7-day window| AlmanacAPI
    Dispatch -->|S2S JWT tool calls
get_events, get_meeting_notes, get_week/day/month_insight| AlmanacAPI
    Resolver -->|value-based contexts
shared email/phone| WeeklyAPI
    Dispatch -->|discover: probe /api/ownlifeos/link
when get_connections returns empty| Inbox0API
    Dispatch -->|direct httpx query
_execute_immich_tool + _execute_protect_tool| Immich
    FastAPI -->|detect tool endpoints:
/api/protect/persons/plates/vehicles/people/:id/video/cameras/snapshot
_get_user_immich / _get_user_protect for creds| UniFiNVR

    classDef user fill:#1a1a2e,stroke:#e85555,stroke-width:2px,color:#fff
    classDef app fill:#16213e,stroke:#e8a020,stroke-width:2px,color:#e0e0e0
    classDef data fill:#1a1a2e,stroke:#64b5f6,stroke-width:2px,color:#e0e0e0
    classDef llm fill:#16213e,stroke:#3ecf6e,stroke-width:2px,color:#e0e0e0
    classDef audit fill:#16213e,stroke:#ff6b9d,stroke-width:2px,color:#e0e0e0
    classDef infra fill:#0f0f0f,stroke:#8888a8,stroke-width:1px,color:#8888a8
    classDef integration fill:#1a1a2e,stroke:#c880ff,stroke-width:2px,color:#e0e0e0
    classDef media fill:#1a1a2e,stroke:#64b5f6,stroke-width:2px,color:#e0e0e0

    class Browser user
    class FastAPI,Auth,S2SAuth,Dispatch,GopherFanout,ModelSelect,AIAgent,ProactiveSvc,RerunStrip,AuditMW,LoopGuard,PollutionGuard,ToolFallback,Resolver,WSHandle,FaceMatch,PlateDetect,VehicleDetect,SnapshotMgmt,EventQueue app
    class PG data
    class Ollama llm
    class Audit audit
    class CF,Docker infra
    class Inbox0API,SummarizerAPI,OwnScribeAPI,AlmanacAPI,WeeklyAPI integration
    class Immich,UniFiNVR media