How kubamichalowski/wakatime-proxy works
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.