Skip to content

System Overview

Tomoda is a real-time social platform for organising spontaneous in-person events. The product surfaces a friends-and-events map, real-time chat, ephemeral "moments", and discovery of nearby people and venues. It is delivered as a single Expo codebase shipping to iOS, Android, and the web, backed by a Go monolith that fronts Postgres, Redis, object storage, and a handful of third-party services.

High-level component map

Clients (one Expo codebase)
Expo iOS
Expo Android
Expo Web
↓
Ingress / Load Balancer
↓
Go binary (single process)
HTTP API (chi)
WebSocket Hub
Asynq Worker
Scheduler
↙   ↓   ↘
Data plane
Postgres + PostGIS
Redis
S3 / RustFS
External providers
Photon OSM
Google Places
Stripe
Resend
Google / Apple OAuth
All four runtimes share the same Go binary and the same data plane; external providers are reached only from the API and worker.

The backend is a single Go binary built from backend/cmd/server/main.go. On boot it loads layered YAML config (config.yaml plus environment-specific overrides), initialises a Zap logger, connects to Postgres (pool sized 10 idle / 100 open in backend/internal/database), applies the goose migrations in non-production environments via db.Migrate, wires the dependency graph via Wire (backend/internal/wiring/providers.go), seeds category data, then starts three concurrent runtimes inside the same process:

  • the HTTP server (chi over net/http) on :8080,
  • the WebSocket Hub goroutine (hub.Run()),
  • the Asynq worker server (background tasks) and the scheduler manager (cron-style enqueuers).

Request lifecycle (authenticated REST)

A typical authenticated request — e.g. POST /api/v1/events — traverses a deterministic middleware chain before reaching a handler:

Client request POST /api/v1/events
↓
chi router
↓
Middleware chain (fixed order)
Recovery
Logger
TraceID
CORS
SecurityHeaders
IPBlocker
JWTAuth
↓
Handler parses DTO
↓
Service business logic
↓
Store only DB caller
↓
Postgres
The middleware order is fixed in SetupRouter; only the JWTAuth (purple) layer is identity-gated. Handlers stay thin, DTOs in, JSON out, while services own business logic and the per-domain store is the only layer that touches the database (via sqlc-generated queries over pgx).

The middleware order is fixed in backend/internal/wiring/router.go (SetupRouter) via r.Use(...): Recovery → Logger → TraceID → Observability (metrics + tracing) → CORS → SecurityHeaders → IPBlocker.BlockMiddleware → IPBlocker.SuspiciousActivityMiddleware, with JWTAuth (and access-policy gates where applicable) applied per-group on protected routes via r.With / r.Group. Each middleware is a func(http.Handler) http.Handler. Handlers are thin: they parse DTOs, call into a service, and return JSON. Services hold business logic; the per-domain store is the only layer that touches the database, running that domain's sqlc-generated queries over pgx.

Tracing

The TraceID middleware assigns a per-request UUID and threads it through Zap log fields, making it possible to follow a single request across handler, service, store, and worker boundaries.

Real-time lifecycle

WebSocket traffic is routed through a separate top-level group:

r.Route("/ws", func(r chi.Router) {
    r.Use(middleware.JWTAuth(app.AuthService))
    r.Get("/chats/{id}", app.Handlers.ChatHandler.HandleWebSocket)
})

JWTs are passed via the token query parameter (browser WebSocket APIs cannot set headers). The handler upgrades the connection, registers a Client on the in-process Hub, and the Hub manages per-chat rooms with broadcast fan-out. See Real-time for the full picture.

Background job lifecycle

Background work uses Asynq on top of Redis. Three queues are configured in backend/internal/async/server.go:

Queue Weight Used for
critical 6 Time-sensitive notifications
default 3 Standard async work
low 1 Cleanup, purges, opportunistic jobs

The scheduler (backend/internal/async/scheduler.go) is a separate, Redis-coordinated cron runner that enqueues recurring jobs:

Job Cadence Purpose
status_update 5 min Roll events between scheduled / active / completed
redis_sync 5 min Reconcile Redis caches with Postgres
token_cleanup 1 hr Purge expired refresh tokens / sessions
account_suspension 12 hr Apply scheduled suspensions
purge 24 hr General hard-delete sweep
deactivated_acct_purge 24 hr Hard-delete accounts past their deactivation grace
moment_cleanup 5 min Soft-delete expired non-journaled moments
moment_purge 24 hr Hard-delete moments soft-deleted > 7 days
message_expiry 30 s Hard-delete disappearing messages past expires_at
Scheduler cron tick
↓ enqueue
Asynq client
↓ LPUSH
Redis queue critical / default / low
↓ BRPOP
Asynq worker
↓ dispatch
TaskHandler ack / retry
Scheduler and worker live in the same Go binary as the API; Redis is the only handoff between them.

Deployment topology

In production the same Go binary runs on a k3s cluster (OVH bare metal) behind Traefik and Cloudflare, with images built by GitHub Actions (.github/workflows/images.yml), pushed to GHCR, and rolled out by Argo CD from a separate devops/ repo. Postgres runs in-cluster on CloudNativePG (PostGIS, PGroonga, pgvector), Redis in-cluster, object storage is Cloudflare R2 via the S3 API (RustFS locally), and Photon runs in-cluster for self-hosted geocoding. The web frontend is built by the same workflow (frontend/Dockerfile, EXPO_PUBLIC_* passed as Docker build-args per environment), pushed to GHCR, and deployed via Argo CD. The native mobile binaries are built locally (expo prebuild then task native:beta:ios / task native:beta:android), signed with Apple/Google credentials, and submitted to the stores by hand; JS-only changes ship over-the-air through a self-hosted Xavia OTA server.