Architecture

How TapTally's components fit together on Kubernetes.

TapTally is deployed as two Helm charts — a backend and a frontend — backed by a PostgreSQL database and an S3-compatible object store. An optional ingress log collector runs alongside the backend to turn controller access logs into tallies.

Components

Component	Chart	Description
Backend API	`taptally-backend`	The TapTally API. Serves the dashboard's data, records tap/click events, and ingests collected logs. Configured via a mounted `config.yaml` plus `TAPTALLY_`-prefixed secrets.
Ingress log collector	`taptally-backend` (optional)	Reads nginx/traefik controller access logs from the Kubernetes API and ships request counts to the backend. One lightweight Deployment per source.
Frontend	`taptally-frontend`	The JavaScript / PWA dashboard client, served as static assets.
PostgreSQL	external	Primary datastore (`taptally` database on port `5432`).
Object storage	external	Any S3-compatible bucket (AWS S3, MinIO, etc.) for stored files.

How it fits together

                          ┌──────────────────────────┐
   Browser / PWA  ───────▶│   taptally-frontend       │
                          │   (static dashboard)      │
                          └────────────┬──────────────┘
                                       │  API calls
                                       ▼
   nginx / traefik            ┌──────────────────────────┐      ┌───────────────┐
   access logs                │   taptally-backend        │────▶ │  PostgreSQL   │
        │                     │   (API + event recorder)  │      └───────────────┘
        │  read via K8s API   │                           │      ┌───────────────┐
        ▼                     │                           │────▶ │  S3 / MinIO   │
   ┌─────────────┐  HTTP      │                           │      └───────────────┘
   │  collector  │───────────▶│  POST collected counts    │
   └─────────────┘  write:logs└──────────────────────────┘

Data flow

Direct tap/click events are sent from your site or app to the backend API and recorded (feature-flagged via config.record_events).
Ingress request tallies are collected out-of-band: the collector polls the nginx/traefik controller pod logs through the Kubernetes API, parses them according to the configured logFormat, and posts request counts to the backend using a write:logs-scoped API key.
The backend persists state to PostgreSQL and stores files in S3 / MinIO.
The frontend renders everything for the user.

Configuration model

The backend uses a hybrid configuration approach with a clear precedence order:

Environment variables with the TAPTALLY_ prefix (highest priority)
The mounted config file at /app/config/config.yaml
Built-in defaults

Non-sensitive settings live in a ConfigMap; credentials (database, JWT, S3) live in a Secret and are injected as TAPTALLY_-prefixed environment variables. See Configuration for the full reference.

Note: The TapTally application source code is being finalized and will be released once it has passed the project's internal security and performance criteria. These charts deploy the published container images (jayonplatforms/taptally-backend and jayonplatforms/taptally-frontend).

Found an issue in the docs? Open an issue on GitHub.