Supametrics: Self-Hosted Analytics for Developers

Case Study: Supametrics

Project Overview

Supametrics is a self-hosted analytics platform designed for developers who want full control over their data. Unlike third-party analytics tools, Supametrics can be deployed on your own infrastructure, giving you privacy, flexibility, and full ownership of event data.

Developers integrate Supametrics into their applications with a simple client snippet:

// app/template.tsx
import dynamic from "next/dynamic";

const Analytics = dynamic(() => import("supametrics"), {
  ssr: false,
});

export default function Template({ children }) {
  return (
    <div>
      {children}
      <Analytics
        url="https://your-hosted-go-server.com"
        client="YOUR_CLIENT_KEY_HERE"
      />
    </div>
  );
}

On the backend, Supametrics uses Golang Fiber to serve analytics events via API keys. Internally, dashboards, authentication, team management, and user roles are powered by Hono, providing a fast, lightweight API layer.

Supametrics enables tracking of:

• Team and project management — invite members, assign roles, and control access
• Page views
• Custom events
• Referrers and UTM parameters
• Browser, OS, and device type
• Event duration

All while remaining completely self-hosted.

The Challenge

Developers and small teams often face challenges with analytics:

• Privacy Concerns: Third-party analytics services collect user data on external servers.
• Limited Customization: Hosted tools offer little control over event structure or retention policies.
• High Costs: SaaS analytics solutions often scale poorly or are expensive for self-managed projects.
• Complex Setup: Rolling out full-featured analytics typically requires multiple services and orchestration.

The goal was to build a self-hosted, lightweight, and flexible analytics tool that addresses these issues while remaining simple to integrate.

The Solution

Supametrics solves these problems by combining a Golang Fiber backend with a Next.js/TypeScript frontend SDK:

• Self-Hosted Deployment: Users run their own instance of the backend anywhere (Render, Railway, or on-premises).
• Simple Client Integration: Developers can integrate analytics with just a few lines of code in React, Next.js, or other frontend frameworks.
• Event Logging API: Backend APIs accept events with custom metadata, session info, and UTM/referrer tracking.
• Internal Dashboards: Using Hono, the system provides dashboards, user authentication, and project management.
• High Performance & Scalability: Postgres stores events reliably, while Redis caches counts and analytics for fast dashboard rendering.
• Privacy & Security: Events are stored on the developer’s own infrastructure; API keys ensure authorized access.

My Role & Process

I built Supametrics end-to-end as a full-stack developer. Key steps included:

1. Architecture & Planning:

   • Designed a self-hosted analytics solution that prioritizes privacy and flexibility.
   • Chose Golang Fiber for the backend due to its speed and simplicity.
   • Selected Next.js/TypeScript for the SDK and docs site for a modern developer experience.
   • Decided on Postgres + Redis for reliable storage and caching.

2. Backend Development:

   • Implemented event logging APIs in Fiber, supporting session IDs, visitor anonymization, and device/OS parsing.
   • Integrated MaxMind GeoLite2 for optional geolocation.
   • Added API key management to authorize project access.
   • Built internal dashboards and authentication using Hono.
   • Implemented team and project collaboration endpoints, allowing users to invite members, assign roles, and manage access per project.

3. Frontend SDK:

   • Built a React/Vanilla Js client library for seamless integration.
   • Captures page views, duration, referrers, UTM parameters, and custom events.
   • Ensures minimal performance overhead with efficient performance.now() tracking and beforeunload event handling.

4. Testing & Optimization:

   • Tested on multiple apps to ensure accurate event capture.
   • Optimized Redis caching for fast dashboard queries.
   • Ensured secure handling of API keys and user data.

5. Documentation:

   • Built the docs site with Next.js: Supametrics Docs
   • Included setup instructions, SDK examples, and API references.

Technical Stack

Results & Impact

• Full Self-Hosting: Users have complete control of analytics data on their infrastructure.
• Quick Integration: React/Next.js projects can integrate analytics with just a few lines of code.
• Detailed Event Tracking: Supports sessions, UTM/referrer, page duration, device info, and custom events.
• Scalable Backend: Handles large event volumes efficiently with Postgres + Redis caching.
• Developer Adoption: Early users report ease of use, privacy compliance, and flexibility in querying analytics.

Key Takeaways

• Privacy-First Design: Self-hosting ensures developers control their data and comply with privacy regulations.
• Full-Stack Development: Building both the backend API and frontend SDK deepened my understanding of distributed event tracking.
• Simplicity at Scale: Minimal integration overhead with high-performance event processing.
• Iterative Learning: Solving SPA referrer/UTM tracking, session persistence, and API key handling taught key lessons in analytics system design.

Installation & Usage

Install the SDK in your Next.js project:

npm install supametrics

Integrate in your app:

"use client";

import dynamic from "next/dynamic";
import { ReactNode } from "react";

const Analytics = dynamic(() => import("supametrics"), { ssr: false });

export default function Template({ children }: { children: ReactNode }) {
  return (
    <div>
      {children}
      <Analytics
        url="https://your-hosted-go-server.com"
        client="YOUR_CLIENT_KEY_HERE"
      />
    </div>
  );
}

Run and deploy your backend (get the code from Supametrics Go Backend):

go run main.go

View docs & API reference: Supametrics Docs

Screenshots

Project overview and events chart

Event logging and detailed analytics view

Manage client API keys securely

Conclusion

Supametrics is a self-hosted, developer-first analytics platform designed to give teams complete control of their data. By combining Golang Fiber for high-performance event processing, Hono for internal APIs, and Next.js for the frontend SDK and docs, I created a tool that is easy to integrate, scalable, and privacy-compliant.

This project strengthened my expertise in full-stack system design, analytics tracking, and self-hosted solutions, while teaching me the nuances of SPA tracking, session management, and distributed event logging.