Building a Claude Code Usage Analytics Platform: Architecture Deep Dive

graph TB
    subgraph "CLIENT SIDE - User Machines"
        subgraph "Developer"
            CLI1[roiAI CLI<br/>Work Laptop]
            DB1[(Local SQLite)]
            CLI1 --> DB1
        end
        
        subgraph "Same User - Different Device"
            CLI2[roiAI CLI<br/>Home Desktop]
            DB2[(Local SQLite)]
            CLI2 --> DB2
        end
        
        subgraph "Cloud Development"
            CLI3[roiAI CLI<br/>Cloud VM/Codespace]
            DB3[(Local SQLite)]
            CLI3 --> DB3
        end
    end
    
    subgraph "CLOUDFLARE EDGE"
        CF[Cloudflare<br/>DNS/CDN/WAF/SSL]
    end
    
    subgraph "SERVER SIDE - Cloud Infrastructure"
        subgraph "Kubernetes Cluster"
            subgraph "Ingress Layer"
                INGRESS[NGINX Ingress<br/>roiai.fyi / api.roiai.fyi]
            end
            
            subgraph "Application Layer"
                WEB[Web Service<br/>Next.js:3000]
                API[API Service<br/>/api endpoints]
            end
            
            subgraph "Background Workers"
                STATS[Stats Worker<br/>Port: 3001]
                RANK[Ranking Worker<br/>Port: 3002]
            end
            
            subgraph "Data Layer"
                PG[(PostgreSQL<br/>10Gi PV)]
            end
            
            INGRESS --> WEB
            INGRESS --> API
            WEB --> PG
            API --> PG
            STATS --> PG
            RANK --> PG
        end
    end
    
    CLI1 -.->|HTTPS| CF
    CLI2 -.->|HTTPS| CF
    CLI3 -.->|HTTPS| CF
    CF ==>|Proxied| INGRESS
    
    classDef clientStyle fill:#ffe0e0,stroke:#c0392b,stroke-width:2px
    classDef dbStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef serverStyle fill:#e0ffe0,stroke:#27ae60,stroke-width:2px
    classDef workerStyle fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    classDef cloudflareStyle fill:#f6821f,stroke:#f48120,stroke-width:3px,color:#fff
    
    class CLI1,CLI2,CLI3 clientStyle
    class DB1,DB2,DB3,PG dbStyle
    class WEB,API,INGRESS serverStyle
    class STATS,RANK workerStyle
    class CF cloudflareStyle

sequenceDiagram
    participant User
    participant CLI as roiAI CLI<br/>[Client Machine]
    participant Server as roiAI Server<br/>[Cloud]
    participant DB as PostgreSQL<br/>[Cloud]

    User->>CLI: roiai cc login
    CLI->>User: Prompt for credentials
    User->>CLI: Email/Username + Password
    CLI->>CLI: Collect machine info
    
    Note over CLI,Server: Client → Server Communication
    CLI->>Server: POST /api/v1/cli/login
    Note over CLI,Server: CliLoginRequest with machine_info
    
    Server->>Server: Validate request schema
    Server->>Server: Authenticate user credentials
    Server->>Server: Generate API key + hash
    Server->>DB: Store API key with machine info
    Server->>CLI: CliLoginResponse (user + api_key)
    
    CLI->>CLI: Store credentials locally
    CLI->>User: Success confirmation

sequenceDiagram
    participant User
    participant CLI as roiAI CLI<br/>[Client Machine]
    participant LocalDB as SQLite<br/>[Client Machine]
    participant Server as roiAI Server<br/>[Cloud]
    participant DB as PostgreSQL<br/>[Cloud]

    User->>CLI: roiai cc push
    CLI->>LocalDB: Check sync status
    
    alt Local sync needed
        CLI->>CLI: Process .jsonl files
        CLI->>LocalDB: Store new messages
    end
    
    Note over CLI,Server: Client → Server Communication
    CLI->>Server: GET /api/v1/cli/health
    Server->>CLI: Authentication confirmation
    
    CLI->>LocalDB: Analyze push queue
    CLI->>User: Display statistics
    
    loop For each batch
        CLI->>LocalDB: Select batch messages
        CLI->>CLI: Build PushRequest
        Note over CLI,Server: Client → Server Batch Upload
        CLI->>Server: POST /api/v1/cli/upsync
        Note over CLI,Server: Batch of messages + entities
        
        Server->>Server: Validate request
        Server->>Server: Transform entities
        Server->>DB: Begin transaction
        Server->>DB: Process entities
        Server->>DB: Process messages
        Server->>DB: Update child counts
        Server->>DB: Collect stats deltas
        Server->>DB: Commit transaction
        Server->>CLI: PushResponse with results
        
        CLI->>LocalDB: Mark messages as synced
        CLI->>User: Update progress
    end
    
    CLI->>User: Final summary

graph LR
    A[Services] -->|metrics| B[Prometheus]
    B -->|query| C[Alert Manager]
    C -->|notify| D[Email/Slack]
    B -->|visualize| E[Grafana]
    CF[Cloudflare] -->|analytics| F[CF Dashboard]
    
    subgraph Alerts
        G[Memory > 90%]
        H[Pending > 10k]
        I[Pod Restarts]
        J[CF Rate Limits]
    end
    
    C --> Alerts
    F --> J