Medama Analytics

Medama Analytics is a self‑hosted, cookie‑free web analytics engine that emphasizes minimal client footprint and strict privacy compliance. The core tracker is a single JavaScript file under 1 KB, which emits event payloads over HTTPS to an OpenAPI‑defined backend. This design allows developers to embed analytics in any site without adding cookies, IP logging, or third‑party identifiers, thereby sidestepping common GDPR and PECR pitfalls. The server exposes a comprehensive RESTful API that can be consumed by custom dashboards, CI/CD pipelines, or other internal tooling.

Technical Stack & Architecture

• Runtime: The backend is a Go 1.22 application compiled into a single static binary. This eliminates external dependencies and simplifies deployment to containers or bare‑metal VMs.
• Frameworks: The API layer uses the Echo web framework for routing and middleware, while data ingestion is handled by a lightweight event queue powered by NATS or in‑memory channels for low‑latency processing.
• Database: Persistent storage is provided by PostgreSQL 15, with a schema that normalizes page views, custom properties, and session data. For small deployments, SQLite can be used as a drop‑in alternative.
• Frontend: The dashboard is built with SvelteKit, which communicates with the backend via GraphQL‑style queries over the same OpenAPI surface. The UI is fully responsive and can be packaged as a static SPA served by the same binary.
• Containerization: A Dockerfile exposes a multi‑stage build that compiles the Go binary and copies the SvelteKit assets into a minimal Alpine image. Kubernetes manifests are available, including a Helm chart that configures Ingress, persistence, and auto‑scaling.

Core Capabilities & APIs

• Event Ingestion: The /api/v1/events endpoint accepts JSON payloads for page views, custom events, and properties. Payload validation is performed against a JSON Schema defined in the OpenAPI spec.
• Real‑Time Analytics: A WebSocket endpoint (/ws/updates) streams live metrics to connected clients, enabling dashboards that reflect traffic as it arrives.
• Custom Properties: Developers can attach arbitrary key‑value pairs to events, which are indexed for fast aggregation. The API supports bulk uploads via /api/v1/events/bulk.
• Data Export: Raw event logs can be exported in CSV or Parquet format through /api/v1/export. The backend integrates with AWS S3-compatible storage for long‑term retention.
• Authentication: Token‑based auth (JWT) is optional; when enabled, API keys can be scoped to specific projects or dashboards.

Deployment & Infrastructure

• Self‑Hosting: A single binary runs on any Linux VM with 256 MB RAM. The application automatically starts a lightweight PostgreSQL container if one is not detected, simplifying the “one‑click” install for developers.
• Scalability: Horizontal scaling is achieved by running multiple instances behind a load balancer. The stateless API layer can be replicated, while the PostgreSQL database is configured for read replicas to handle high query volumes.
• Observability: Built‑in Prometheus metrics (/metrics) expose request latency, event counts, and database health. Logging is structured JSON, facilitating ingestion into ELK or Loki stacks.
• CI/CD Integration: A medama-cli tool (CLI) provides commands for schema migrations, data cleanup, and health checks, making it easy to incorporate into automated pipelines.

Integration & Extensibility

• Plugin System: Developers can extend Medama by implementing custom event processors in Go, compiled as shared libraries and loaded at runtime. This allows for real‑time filtering, enrichment, or routing to external services.
• Webhooks: The /api/v1/webhooks endpoint lets users register URLs that receive POST notifications on specific event types, enabling integration with Slack, PagerDuty, or custom microservices.
• SDKs: While the tracker is language‑agnostic, a small JavaScript SDK ships with helper functions for setting custom properties and handling errors. Additional SDKs (Python, Ruby) are planned to aid server‑side event emission.

Developer Experience

• Documentation: The project hosts a comprehensive API reference with interactive Swagger UI, along with tutorials for deployment, configuration, and advanced use cases. The documentation is maintained in Markdown on GitHub and rendered via Docusaurus.
• Community: An active Discord channel provides real‑time support, while GitHub Discussions serve as a forum for feature requests and bug reports. The open‑source license (Apache 2.0 + MIT) encourages contributions without restrictive copyleft.
• Configuration: Environment variables control all aspects—database DSN, cache settings, feature flags. A config.yaml template is included for those who prefer file‑based overrides.

Use Cases

• Privacy‑First Websites: Any site that must avoid cookies (e.g., health portals, financial services) can embed the lightweight tracker and rely on Medama’s GDPR‑compliant data handling.
• Internal Dashboards: Companies can expose custom metrics to internal tooling by consuming the OpenAPI endpoints, creating tailored reports for product teams.
• Educational Projects: The minimal footprint and self‑hosting model make it ideal for teaching web analytics concepts in a sandboxed environment.
• Hybrid Cloud: Deploy the binary on a Kubernetes cluster while using managed PostgreSQL, benefiting from auto‑sc