Almanac Architecture

graph TD
    subgraph User["User Layer"]
        Browser["Browser"]
    end

    subgraph AlmanacApp["Almanac App"]
        FastAPI["FastAPI Server"]
        LoginAuth["Login OAuth
Google sign-in -> /auth/google/callback
session cookie key=almanac_session,
middleware name=almanac_state_session"]
        CalAuth["Connect-Calendar OAuth
connect calendar -> /callback
calendar OAuth state"]
        Invite["Invite Gate
new users only"]
        Encrypt["Fernet Encryption
tokens at rest"]
        Sync["Calendar Sync
90d back / 365d forward, per-provider
incremental: per-calendar syncToken, delta-only
fetches linked Google Docs per event"]
        FreshGate["Lazy Refresh-on-Read
ensure_fresh: kicks off background re-sync
for accounts older than TTL; serves current data
immediately, never blocks reads"]
        Encode["Calendar ID URL-encoding"]
        Public["Public Event Filter
strips raw JSON + attendees"]
        Events["calendar events
account email scopes ONE own calendar
attendee = meetings WITH others"]
        Categories["Per-Calendar Category
holiday / meeting / birthday
holidays excluded from hours + counts"]
        Insight["Day / Week / Month
Insights"]
        DocNotes["Meeting Notes Extraction
Google Doc -> action items / decisions / open questions
sources: attachments + description links + pinned docs"]
        Pin["Pin Standalone Doc
POST /api/events/{id}/pin-doc
propagates across recurring series"]
        WeeklyNotes["Weekly Meeting-Notes Feed
/api/weekly/meeting-notes
past-meeting context for Weekly + Gopher"]
        Rename["Account Rename
account rename"]
        Identity["AccountProvider
identity / accounts"]
    end

    subgraph Data["Data Layer"]
        SQLite[("SQLite
users + sessions + events + meeting notes
encrypted credentials
per-thread conns, WAL, busy_timeout")]
    end

    subgraph External["External Systems"]
        Google["Google Calendar API"]
        OAuthG["Google OAuth 2.0
identity + calendar.readonly + drive.readonly"]
        CalDAV["CalDAV Servers
iCloud, Nextcloud, etc.
caldav 3.x, auth_type=basic"]
        Drive["Google Drive API
Docs export + metadata gate"]
    end

    subgraph CrossApp["Cross-App"]
        Gopher["Gopher
tool calls via S2S JWT"]
        Weekly["Weekly
weekly insights
(via Gopher)"]
    end

    subgraph Infra["Infrastructure"]
        CF["Cloudflare Tunnel"]
        Docker["Docker Compose"]
        OwnOS["MyOwnLifeOS JWT
suite-shared signing key"]
    end

    Browser -->|HTTPS| CF
    CF -->|docker bridge| Docker
    Docker --> FastAPI
    FastAPI --> LoginAuth
    LoginAuth -->|session| SQLite
    LoginAuth -->|server-to-server| OwnOS
    FastAPI -->|invite check| Invite
    Browser -->|sign in| FastAPI
    FastAPI -->|redirect| OAuthG
    OAuthG -->|code + tokens| FastAPI
    Browser -->|connect calendar| FastAPI
    FastAPI --> CalAuth
    CalAuth -->|redirect| OAuthG
    OAuthG -->|code + tokens| CalAuth
    FastAPI -->|encrypt| Encrypt
    Encrypt -->|store| SQLite
    FastAPI -->|sync trigger| Sync
    Sync -->|encode calendar id| Encode
    Encode -->|Bearer access token| Google
    Google -->|events| Sync
    Sync -->|CalDAV date_search| CalDAV
    CalDAV -->|events| Sync
    Sync -->|scrape doc IDs| DocNotes
    DocNotes -->|export text| Drive
    Drive -->|action items / decisions| DocNotes
    DocNotes -->|attachment_notes| SQLite
    Sync -->|store| SQLite
    FastAPI -->|before any read| FreshGate
    FreshGate -.->|if stale, background delta re-sync| Sync
    FastAPI -->|read| SQLite
    SQLite -->|sanitize| Public
    Public -->|events JSON| Browser
    FastAPI -->|summaries| Insight
    Insight --> Browser
    Gopher -->|S2S JWT| FastAPI
    FastAPI -->|identity| Identity
    Identity -->|accounts| Gopher
    FastAPI -->|week summary| Insight
    Insight -->|weekly insights| Gopher
    Gopher -->|weekly context| Weekly
    FastAPI -->|read account-scoped| Events
    SQLite -->|events| Events
    Events -->|account email / attendee filter| Browser
    Events -->|account-scoped events| Gopher
    Sync -->|classify| Categories
    Categories -->|category tags| SQLite
    Categories -->|holiday vs working hours| Insight
    Browser -->|rename config| Rename
    Rename -->|update label| SQLite
    Browser -->|pin doc URL| Pin
    Pin -->|verify + fetch| Drive
    Pin -->|propagate recurring series| SQLite
    FastAPI -->|meeting-notes range| WeeklyNotes
    SQLite -->|attachment_notes| WeeklyNotes
    WeeklyNotes -->|past-meeting context| Gopher

    classDef user fill:#1a1a2e,stroke:#e85555,stroke-width:2px,color:#fff
    classDef app fill:#16213e,stroke:#3ecf6e,stroke-width:2px,color:#e0e0e0
    classDef data fill:#16213e,stroke:#64b5f6,stroke-width:2px,color:#e0e0e0
    classDef ext fill:#1a1a2e,stroke:#e85555,stroke-width:2px,color:#e0e0e0
    classDef infra fill:#0f0f0f,stroke:#8888a8,stroke-width:1px,color:#8888a8
    classDef cross fill:#1a1a2e,stroke:#c880ff,stroke-width:2px,color:#e0e0e0

    class Browser user
    class FastAPI,LoginAuth,CalAuth,Invite,Encrypt,Sync,FreshGate,Encode,Public,Events,Categories,Insight,DocNotes,Pin,WeeklyNotes,Rename,Identity app
    class SQLite data
    class Google,OAuthG,CalDAV,Drive ext
    class CF,Docker,OwnOS infra
    class Gopher,Weekly cross