flowchart TD
    USER((External User)) --> ENTRY

    subgraph traefik["Traefik Edge Gateway"]
        direction LR
        ENTRY["EntryPoints: web(:80), websecure(:443), traefik(:8080), metrics(:8082)"]
        ROUTERS["Routers: api-rtr (/*), public-rtr (/r/*), health-rtr (/health)"]
        MIDDLEWARES["Middlewares: HTTPS Redirect, CORS, Security Headers, IP Whitelist"]
        SERVICES["Services: api-svc(:8000)"]
        ENTRY --> | Apply TLS | ROUTERS
        ROUTERS --> MIDDLEWARES --> SERVICES
    end

    traefik --> api_service

    subgraph api_service["API Service (FastAPI Application)"]
         direction LR
         APP["FastAPI App"]
         QR["QR Logic"]
         DB[("PostgreSQL DB")]
         APP --> QR
         APP --> DB
         DB --> DB_VOL["Volume: postgres_data"]
         style APP fill:#ccf,stroke:#333,stroke-width:2px
    end

    subgraph monitoring["Observatory Monitoring Stack"]
        direction LR
        PROMETHEUS[("Prometheus<br/>Metrics Collection")]
        LOKI[("Loki<br/>Log Aggregation")]
        GRAFANA[("Grafana<br/>8 Dashboard Suite<br/>+ Log Analysis")]
        PROMETHEUS --> GRAFANA
        LOKI --> GRAFANA
        style PROMETHEUS fill:#fff3e0,stroke:#333,stroke-width:2px
        style LOKI fill:#e3f2fd,stroke:#333,stroke-width:2px
        style GRAFANA fill:#e8f5e8,stroke:#333,stroke-width:2px
    end

    api_service --> monitoring

    subgraph docker_build["Docker Build Process"]
        direction LR
        subgraph builder["Builder Stage"]
            B["python:3.12-slim + build deps + venv + requirements.txt"]
        end

        subgraph runtime["Runtime Stage"]
            R["python:3.12-slim + runtime deps (curl, postgresql-client) + app code + scripts"]
            ENV_VARS["ENV: PORT=8000, WORKERS, PG_DATABASE_URL, etc."]
            HEALTH["Healthcheck: /health (curl)"]
        end

        builder --> runtime
        runtime --> DOCKER_IMAGE[("Docker Image: qr-generator")]
    end


    subgraph compose["Docker Compose Orchestration"]
        direction LR
        subgraph compose_services["Services"]
            API_SVC["API Service (qr_generator_api)"]
            POSTGRES_SVC["PostgreSQL (qr_generator_postgres)"]
            PROXY_SVC["Traefik Proxy (qr_generator_traefik)"]
        end

        subgraph compose_env["Environment"]
            direction LR
            subgraph DEV["Development (default)"]
                DEV_FEATURES["Features: Hot reload, Debug, App mounting"]
                TEST_MODE["Testing: Test Database (pytest)"]
            end

            PROD["Production Env: Optimized, No hot reload"]
        end

        subgraph compose_storage["Storage & Network"]
            direction LR
            VOLUMES["Named Volumes: qr_data, postgres_data, qr_logs, traefik_certs, traefik_logs"]
            NET["Network: qr_generator_network (bridge)"]
        end

        compose_services -- Manages --> api_service
        compose_services -- Uses --> compose_env
        compose_services -- Uses --> compose_storage
    end

    docker_build --> compose
    compose -- Deploys --> api_service
    compose -- Deploys --> traefik

    %% Logging Flow
    subgraph logs["Logging Output"]
        direction LR
        LOG_VOL["Volumes: qr_logs, traefik_logs"] --> LOG_FILES["Log Files:<br>/logs/api/*<br>/logs/database/*<br>/logs/traefik/*"]
        API_SVC -- Logs --> LOG_VOL
        PROXY_SVC -- Logs --> LOG_VOL
    end