Wakapi

Wakapi is a lightweight, self‑hosted backend that aggregates coding activity from IDEs and text editors. Designed to be a drop‑in replacement for the proprietary WakaTime service, it exposes a REST API that accepts JSON payloads from client plugins and stores them in a relational database. The core goal is to provide developers with fine‑grained statistics—project, language, editor, OS, and host—while keeping the stack minimal and fast. The application is written in Go (≥1.22), leveraging the standard library’s HTTP server, encoding/json, and a small set of third‑party packages for routing (chi), logging, and metrics.

Architecture & Technical Stack

• Language: Go (statistically typed, compiled, garbage‑collected) ensures a small binary footprint (~15 MB) and low runtime overhead.
• Web Framework: The standard net/http package with the lightweight router github.com/go-chi/chi/v5. This keeps request handling fast and eliminates the need for a heavy MVC framework.
• Persistence: By default, SQLite is used via modernc.org/sqlite for zero‑configuration deployments. Production setups can switch to MySQL or PostgreSQL by setting environment variables (DB_DRIVER, DB_DSN) in the configuration file.
• Metrics: Prometheus client (github.com/prometheus/client_golang) exposes /metrics for monitoring CPU, memory, request latency, and custom counters such as “sessions recorded”.
• Configuration: YAML (config.default.yml) is parsed with github.com/spf13/viper, allowing environment variable overrides and support for Docker secrets or Kubernetes ConfigMaps.
• Deployment: A single binary can be run locally, inside Docker (official image ghcr.io/muety/wakapi:latest), or on Kubernetes via the community Helm chart. The container image is built with multi‑stage Dockerfiles to keep runtime size under 30 MB.

Core Capabilities & APIs

• RESTful Endpoint: /api/v1/stats accepts POST requests with a JSON body containing user_id, project_name, language, editor, and duration. The endpoint validates payloads, inserts or updates rows in the database, and returns a 201 status.
• WakaTime Compatibility: Clients that send data in the WakaTime format are accepted with minimal transformation. This allows existing plugins (VS Code, JetBrains, Sublime) to point directly at a Wakapi instance.
• Badge Generation: An HTTP endpoint /badges/{user} renders SVG badges that can be embedded in README files. The badge includes total hours, active projects, and language distribution.
• Email Reports: A background goroutine can be enabled to send weekly summaries via SMTP. The configuration supports TLS, authentication, and templated HTML bodies.
• Webhooks: On successful ingestion, the server can emit a configurable webhook to external services (e.g., Slack, Discord) for real‑time notifications.

Deployment & Infrastructure

Wakapi’s architecture is intentionally minimal to reduce operational overhead:

• Self‑Hosting: No external services are required beyond the database. The binary is stateless, making it ideal for Docker Swarm or Kubernetes deployments.
• Scalability: While SQLite is great for low‑to‑medium traffic, the application supports sharding by user ID or time range when using MySQL/PostgreSQL. Horizontal scaling can be achieved with a load balancer and shared database.
• Containerization: The Docker image is built on golang:alpine for compile time and scratch for runtime, ensuring fast startup (<0.5 s) and low memory usage (~50 MiB).
• CI/CD: The project includes GitHub Actions that run unit tests, linting (golangci-lint), and SonarCloud analysis. Automated releases publish to GitHub Packages and Docker Hub.

Integration & Extensibility

• Plugin Ecosystem: The client side is agnostic; any editor that can send HTTP POSTs to /api/v1/stats will work. The official Wakapi client is available for VS Code, but developers can write custom scripts in Python, Rust, or Bash.
• Extensible API: Custom endpoints can be added by extending the router. For example, a /api/v1/leaderboard could aggregate top users by hours worked.
• Webhooks & Callbacks: Developers can register webhook URLs in the configuration file. The server sends a JSON payload containing user stats after each batch.
• Prometheus Exporter: Prometheus can scrape /metrics for real‑time monitoring, and Grafana dashboards can be built on top of the exported metrics.

Developer Experience

• Documentation: The README is comprehensive, and inline comments in the source code aid understanding. A dedicated docs/ directory contains API specs and configuration examples.
• Community Support: The project has an active GitHub issue tracker, a Discord channel for quick questions, and contributors from the open‑source community. Licensing is MIT, ensuring no restrictions on commercial use.
• Configuration Flexibility: Environment variables can override any YAML setting, making it easy to integrate with CI/CD pipelines or secret managers.

Use Cases

1. Personal Coding Dashboard – A solo developer can run Wakapi locally to track time spent across projects and generate badges for GitHub READMEs.
2. **