Skip to main content

​
Architecture

SMO1 follows a service-oriented architecture with dedicated services for each concern.

​
Service Map

Figure 1 — SMO1 Service Map. The marketing landing page and dashboard both communicate with purr-api. Analytics flow to ClickHouse, while link data is persisted in Neon PostgreSQL and cached in Upstash Redis. The edge redirect service reads from Cloudflare KV, which is synchronised from purr-api.
Trace IDRequirementRationaleTest Case
SMO1-ARCH-001Link redirects shall be served from Cloudflare edge locations with P99 latency below 50 msEdge-based resolution eliminates origin round-trips for the highest-volume operationTC-SMO1-ARCH-001
SMO1-ARCH-002Cloudflare KV shall be synchronised from purr-api within 5 seconds of a link create/updateEnsures redirect freshness while decoupling read and write pathsTC-SMO1-ARCH-002
SMO1-ARCH-003Click events shall be recorded in ClickHouse for analytics with at-least-once deliveryAccurate analytics require durable event capture, and ClickHouse handles high write throughputTC-SMO1-ARCH-003

​
Services

​
purr-api (Backend)

  • Stack: Go 1.24, Gin, pgx, go-redis, zerolog
  • Responsibilities: Link CRUD, user management, analytics, billing
  • Deployed on: Railway

​
meow-web (Dashboard)

  • Stack: Next.js 15, React 19, TypeScript, Tailwind CSS
  • Responsibilities: User dashboard, link management, analytics views
  • Deployed on: Vercel

​
whiskers-landing (Marketing)

  • Stack: Next.js, React, TypeScript, Tailwind CSS
  • Responsibilities: Marketing landing page, pricing, blog
  • Deployed on: Vercel

​
zoomies-edge (Redirects)

  • Stack: Cloudflare Workers, Hono, TypeScript
  • Responsibilities: Ultra-fast link redirects at the edge
  • Deployed on: Cloudflare Workers

​
litter-box (DevTools)

  • Stack: Docker Compose, Prometheus, Grafana
  • Responsibilities: Local dev environment, monitoring dashboards

​
catnip-packages (Shared)

  • Stack: TypeScript, pnpm
  • Responsibilities: Shared types, utilities, configurations

​
Data Flow

  1. User creates a short link via meow-web -> purr-api -> PostgreSQL
  2. Link data syncs to Cloudflare KV via purr-api’s KV sync service
  3. Visitor clicks short link -> zoomies-edge reads from KV -> instant redirect
  4. Click event sent to purr-api -> stored in ClickHouse for analytics
  5. User views analytics in meow-web -> fetched from purr-api -> ClickHouse