TShirtize Architecture

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

    subgraph TShirtizeApp["TShirtize App"]
        FastAPI["FastAPI Server
auth / sizing / admin / settings / health
Monday create + E2E test-only routes"]
        Auth["Hybrid Auth
Google OAuth + OwnLifeOS app-token SSO
session_token cookie"]
        Sizer["Sizing Engine
sizer.py: gather context → prompt → persist
returns size, rationale, DoD, spike,
spike_reason, confidence, questions"]
        Monday["Monday.com Client
GraphQL read + gated writeback
URL parser/normalizer
epic → stories → tasks"]
        GitHub["GitHub Client
issue/PR/diff reader + commit history"]
        RepoCtx["Repo Context
recent commits as velocity signal"]
        Calibration["Calibration
rebuilds averages per size/input_type
≥3 completed sizings activates"]
        Admin["Admin / Calibration Dashboard
per-size stats, invites, tenant CRUD
role-based access (user / admin)"]
        Audit["Audit Logger
SQLite default, PostgreSQL optional"]
    end

    subgraph Frontend["Next.js Static Export"]
        Landing["Landing Page
marketing + sign-in
t-shirt test pyramid"]
        AppUI["Work Page
unified Monday / GitHub / free-text input
board item picker, connection state bar"]
        HistoryUI["History Page
past sizings, filters, results"]
        ProfileUI["Profile Page
user info, personal tenant"]
        AdminUI["Admin UI
calibration dashboard, invites"]
        SettingsUI["Settings Page
card-based: model picker, Monday key,
GitHub token, default repos"]
    end

    subgraph Intelligence["Local Intelligence"]
        LLM["LLM Providers
Ollama, Anthropic, OpenAI
user/tenant picks provider+model"]
    end

    subgraph Testing["Automated Tests"]
        UnitTests["Unit Tests
pytest: sizer, services, helpers"]
        APITests["API Tests
pytest: FastAPI endpoints
TestClient + tmp_path DB"]
        E2ETests["UI / E2E Tests
Playwright: browser flows
TEST_AUTH=1"]
    end

    subgraph Data["Data Layer"]
        SQLite[("SQLite
users (+role), sessions, tenants,
tenant_members, sizing_attempts
(+spike_reason), monday_created_items,
calibration_snapshots, invites,
github_credentials (+default_repos),
tenant_settings (+monday_board_id)
WAL mode, per-thread connections")]
    end

    subgraph External["External Systems"]
        MondayCom["Monday.com GraphQL"]
        GitHubCom["GitHub REST API"]
    end

    subgraph CrossApp["Cross-App Suite"]
        OwnOS["MyOwnLifeOS Hub
/api/launch/tshirtize SSO
/api/link connection registry"]
        Gopher["Gopher
reads /api/ownlifeos/* for context"]
    end

    subgraph Infra["Infrastructure"]
        CF["Cloudflare Tunnel"]
        Docker["Docker Compose"]
        SW["Service Worker
offline HTML shell"]
        PWA["PWA Manifest
standalone, amber theme"]
    end

    Browser -->|HTTPS| CF
    CF -->|HTTP| Docker
    Docker --> FastAPI
    FastAPI -->|serves static| Frontend
    Browser -->|GET /static/*| Frontend
    Browser -->|installs, caches shell| SW
    Browser -->|GET /architecture| FastAPI
    Browser -.->|PWA manifest| PWA

    Landing -->|/auth/google| Auth
    Landing -->|/auth/ownlifeos| Auth
    Auth -->|get_or_create_user| SQLite
    Auth -->|best-effort link| OwnOS

    AppUI -->|POST /api/size| Sizer
    Sizer -->|input_type=monday| Monday
    Sizer -->|input_type=github| GitHub
    Sizer -->|input_type=text| Sizer
    Sizer -->|LLM call| LLM
    Monday -->|GraphQL| MondayCom
    GitHub -->|REST| GitHubCom
    GitHub -->|commit velocity| RepoCtx
    Sizer -->|persist result| SQLite
    Sizer -->|rebuild if completed| Calibration
    Calibration -->|averages| SQLite
    AppUI -->|adjust / actual-effort / resolved-pr| SQLite
    AppUI -->|rebuild| Calibration
    AppUI -->|POST /api/monday/*| Monday
    Monday -->|record created item| SQLite
    HistoryUI -->|GET /api/history| SQLite
    ProfileUI -->|GET /api/me| SQLite
    AdminUI -->|calibration dashboard| Admin
    Admin -->|read stats| SQLite
    SettingsUI -->|/api/models| LLM
    SettingsUI -->|/api/tenants/*/settings| SQLite

    UnitTests -->|covers| Sizer
    UnitTests -->|covers| Monday
    UnitTests -->|covers| GitHub
    APITests -->|hits| FastAPI
    E2ETests -->|drives| Browser
    E2ETests -->|uses| FastAPI
    E2ETests -->|mocks| MondayCom

    Gopher -->|Bearer OwnLifeOS JWT
GET /api/ownlifeos/stats
GET /api/ownlifeos/sizings
POST /api/ownlifeos/size| FastAPI
    OwnOS -->|discover capabilities| FastAPI

    FastAPI -->|audit events| Audit
    Audit -->|SQLite / PostgreSQL| SQLite

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

    class Browser user
    class FastAPI,Auth,Sizer,Monday,GitHub,RepoCtx,Calibration,Admin,Audit app
    class Landing,AppUI,HistoryUI,ProfileUI,AdminUI,SettingsUI frontend
    class SQLite data
    class LLM llm
    class CF,Docker,SW,PWA infra
    class MondayCom,GitHubCom ext
    class OwnOS,Gopher cross
    class UnitTests,APITests,E2ETests tests