# kubamichalowski/wakatime-proxy architecture

> Architecture diagram of the GitHub repository kubamichalowski/wakatime-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubamichalowski/wakatime-proxy
- Repository: https://github.com/kubamichalowski/wakatime-proxy

## Overview

##### What this project is (type + purpose)
This repo is a **tiny PHP web service** (a “BFF/proxy”) whose job is to:
- accept **browser-friendly requests** (same-origin from a frontend) like `/id/{username}`,
- **call the public WakaTime API** server-side (so the browser avoids CORS),
- optionally **cache responses in Redis** to improve latency and reduce upstream calls,
- return the response to the client.

##### What the file tree implies architecturally
Given the tree:

- `index.php`
Likely the **single entrypoint** (front controller) handling routing, request parsing, calling WakaTime, caching, and responding.

- `.htaccess` (and `logs/.htaccess`)
Strong signal this is meant for **Apache** with URL rewriting (pretty routes like `/id/...` mapped to `index.php`) and log protection.

- `composer.json`, `composer.lock`

- `.env.example`
Runtime config (Redis enablement, connection mode, TTL). This implies:
- caching is **feature-flagged** (`ENABLE_REDIS`)
- Redis connectivity may be via **UNIX socket** or **TCP host/port**
- cache TTL is configurable

- `logs/`

Net: architecture is **monolithic, single endpoint service** with **optional Redis** and **one external upstream**.

##### What the README adds (runtime behavior + interfaces)
From README:
- External dependency: **WakaTime API** (public data; no API key)
- Non-functional requirement: **CORS bypass** for browser clients
- Performance feature: **Redis caching** (10x speed improvement)

##### Apache/Nginx → PHP app (index.php)

**Cache decision**
##### PHP app → Redis
- Redis → PHP app: `cached JSON (hit)` OR `miss`

**Upstream call on miss**

##### WakaTime API → PHP app

**Cache fill**
##### PHP app → Redis

**Response**

##### Architectural patterns used here

- **Reverse-proxy / BFF pattern**: server-side call to avoid browser CORS constraints
- **Cache-aside** (lazy caching): read from cache, on miss fetch upstream and populate cache
- **Front controller**: `index.php` handles all routes (implied by `.htaccess`)
- **Config-driven optional dependency**: Redis is enabled/disabled via `.env`

##### Significant technologies
- PHP >= 8.1
- Apache or Nginx (with rewrite / .htaccess compatibility)
- Redis >= 6 (optional)
- External: WakaTime API

##### Required elements
- **Clear labels** on every node (include runtime + responsibility)
- Clients (e.g., rounded rectangles)
- Compute/services (rectangles)

##### Context (C4 Level 1)
Browser client, wakatime-proxy, WakaTime API, Redis (optional). High-level trust boundaries.

##### Container/Runtime (C4 Level 2)
Apache/Nginx container, PHP app container/process, Redis container/service, external WakaTime. Show networking.

Two sequences: cache hit and cache miss, showing cache-aside behavior and response headers (CORS).

This gives both structure and behavior—and matches the repo’s simplicity without inventing components.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% Context (C4 L1)
  %% =======================
  subgraph "Context (C4 Level 1) — Who talks to whom"
    direction TB

    Browser["Browser-based Frontend\n(Same-origin requests)\nCORS-constrained"]:::client
    OtherClients["Other Clients\n(curl / server-to-server)"]:::client

    subgraph "wakatime-proxy Service (Edge BFF / Proxy)"
      direction TB
      WebServer["Apache (or Nginx)\nURL rewrite to front controller"]:::web
      PHPApp["PHP 8.1+ Proxy App\nSingle entrypoint: index.php"]:::app
    end

    Redis[("Redis 6+ (Optional)\nCache-aside\nTTL=REDIS_TTL\nENABLE_REDIS")]:::cache
    WakaTime["WakaTime Public API\n(External SaaS)"]:::external

    Browser -->|"GET /id/{username}"| WebServer
    OtherClients -->|"GET /id/{username}"| WebServer
    WebServer -->|"rewrite -> index.php"| PHPApp

    PHPApp -->|"GET key=id:{username}"| Redis
    Redis -->|"hit: cached JSON"| PHPApp

    PHPApp -->|"miss: GET public stats"| WakaTime
    WakaTime -->|"JSON response"| PHPApp
    PHPApp -->|"SET key=id:{username} TTL=REDIS_TTL"| Redis

    PHPApp -->|"return JSON + CORS headers\n(CORS solved here)"| Browser
    PHPApp -->|"return JSON"| OtherClients
  end

  %% =======================
  %% Container/Runtime (C4 L2)
  %% =======================
  subgraph "Container/Runtime (C4 Level 2) — How it runs"
    direction TB

    ClientNet["Client Network / Internet"]:::boundary

    subgraph "Host / VM / Container Runtime"
      direction TB

      subgraph "Web Tier"
        direction TB
        ApacheRuntime["Apache (or Nginx)\nserves HTTPS + rewrite rules"]:::web
        Htaccess[".htaccess\n(pretty route rewrite)"]:::config
        LogsProtect["logs/.htaccess\n(deny direct access)"]:::config
      end

      subgraph "App Tier (PHP)"
        direction TB
        PHPFPM["PHP runtime\n(executes index.php)"]:::app
        Entry["Front Controller\nindex.php"]:::app

        subgraph "index.php internal modules"
          direction TB
          Router["Router / Request Handler\nparses /id/{username}"]:::module
          Config["Config Loader\n.env-driven flags"]:::module
          CacheAdapter["Cache Layer (Redis adapter)\nENABLE_REDIS gate"]:::module
          Upstream["WakaTime API Client\nHTTP GET upstream"]:::module
          Response["Response Formatter\nJSON + CORS headers"]:::module
        end

        Composer["Composer dependencies\n(vendor autoload)"]:::config
        Docs["README\nendpoint contract + behavior"]:::doc
      end

      subgraph "Data Tier (Optional)"
        direction TB
        RedisSvc[("Redis 6+\nTCP host/port OR UNIX socket")]:::cache
      end

      FileLogs[("Local file logs\nlogs/error.log")]:::log
    end

    ExternalSaaS["WakaTime Public API\nExternal SaaS"]:::external

    ClientNet -->|"HTTPS GET /id/{username}"| ApacheRuntime
    ApacheRuntime -->|"uses rewrite rules"| Htaccess
    ApacheRuntime -->|"forwards request to PHP"| PHPFPM
    PHPFPM -->|"executes"| Entry

    Entry --> Router
    Entry --> Config
    Entry --> CacheAdapter
    Entry --> Upstream
    Entry --> Response

    CacheAdapter -->|"connect via TCP or socket"| RedisSvc
    Upstream -->|"HTTPS GET public stats"| ExternalSaaS

    Entry -->|"write errors"| FileLogs
    LogsProtect -->|"protects /logs from direct web access"| FileLogs

    Composer -->|"autoload / deps"| Entry
    Docs -->|"documents /id/[username]\n& caching behavior"| Entry
  end

  %% =======================
  %% Sequence (Behavior)
  %% =======================
  subgraph "Core Request Behavior (Sequence-like view) — Cache hit vs miss"
    direction TB

    SClient["Client\n(Browser)"]:::client
    SWeb["Web Server\n(Apache/Nginx)"]:::web
    SApp["PHP Proxy App\n(index.php)"]:::app
    SRedis[("Redis\n(optional)")]:::cache
    SUp["WakaTime API\n(external)"]:::external

    subgraph "Flow A — Cache HIT"
      direction TB
      A1["1) GET /id/{username}"]:::step
      A2["2) rewrite -> index.php"]:::step
      A3["3) GET key=id:{username}"]:::step
      A4["4) return cached JSON"]:::step
      A5["5) respond JSON + CORS"]:::step
    end

    subgraph "Flow B — Cache MISS"
      direction TB
      B1["1) GET /id/{username}"]:::step
      B2["2) rewrite -> index.php"]:::step
      B3["3) GET key=id:{username} (miss)"]:::step
      B4["4) HTTPS GET public stats"]:::step
      B5["5) receive JSON"]:::step
      B6["6) SET key=id:{username}\nTTL=REDIS_TTL"]:::step
      B7["7) respond JSON + CORS"]:::step
    end

    SClient -->|"A1"| SWeb
    SWeb -->|"A2"| SApp
    SApp -->|"A3"| SRedis
    SRedis -->|"A4"| SApp
    SApp -->|"A5"| SClient

    SClient -->|"B1"| SWeb
    SWeb -->|"B2"| SApp
    SApp -->|"B3"| SRedis
    SApp -->|"B4"| SUp
    SUp -->|"B5"| SApp
    SApp -->|"B6"| SRedis
    SApp -->|"B7"| SClient
  end

  %% =======================
  %% Click Events (from component_mapping)
  %% =======================
  click PHPApp "https://github.com/kubamichalowski/wakatime-proxy/blob/main/index.php"
  click Entry "https://github.com/kubamichalowski/wakatime-proxy/blob/main/index.php"
  click Router "https://github.com/kubamichalowski/wakatime-proxy/blob/main/index.php"
  click Upstream "https://github.com/kubamichalowski/wakatime-proxy/blob/main/index.php"
  click CacheAdapter "https://github.com/kubamichalowski/wakatime-proxy/blob/main/index.php"
  click Config "https://github.com/kubamichalowski/wakatime-proxy/blob/main/.env.example"
  click Htaccess "https://github.com/kubamichalowski/wakatime-proxy/blob/main/.htaccess"
  click Composer "https://github.com/kubamichalowski/wakatime-proxy/blob/main/composer.json"
  click Docs "https://github.com/kubamichalowski/wakatime-proxy/blob/main/README.md"
  click LogsProtect "https://github.com/kubamichalowski/wakatime-proxy/blob/main/logs/.htaccess"
  click FileLogs "https://github.com/kubamichalowski/wakatime-proxy/blob/main/logs/error.log"

  %% =======================
  %% Styles
  %% =======================
  classDef client fill:#D7F3FF,stroke:#0B5C75,stroke-width:1.5px,color:#06394A
  classDef web fill:#E8E0FF,stroke:#4B33A8,stroke-width:1.5px,color:#23105A
  classDef app fill:#DFF7E7,stroke:#1B7A3A,stroke-width:1.5px,color:#0F4B24
  classDef module fill:#F2FFDF,stroke:#6C9B1E,stroke-width:1px,color:#2C3C0C
  classDef cache fill:#FFE9CC,stroke:#B85C00,stroke-width:1.5px,color:#5A2E00
  classDef external fill:#FFE0E0,stroke:#A61B1B,stroke-width:1.5px,color:#5A0C0C,stroke-dasharray: 5 3
  classDef config fill:#FFF6C9,stroke:#8A6D00,stroke-width:1.2px,color:#3D3200
  classDef log fill:#E6E6E6,stroke:#555555,stroke-width:1.2px,color:#1F1F1F
  classDef doc fill:#E3F2FD,stroke:#1565C0,stroke-width:1.2px,color:#0D2F57
  classDef boundary fill:#FFFFFF,stroke:#888888,stroke-width:1.2px,color:#222222,stroke-dasharray: 3 3
  classDef step fill:#FFFFFF,stroke:#666666,stroke-width:1px,color:#222222
```
