Architecture
Handbook
A personalized fitness platform — ~50 SEO calculators plus a SaaS app with AI coaching, tracking, and billing in one server-rendered codebase.
Chapters
01 · System Overview
Purpose, quality goals, C4 context and container views, and the tech stack.
02 · Codebase Map
Where code lives: layers, modules, ownership, and where to add things.
03 · Request Lifecycle
Rendering modes, middleware, ISR caching, and per-route authorisation.
04 · Data Model
The 71-table Postgres schema, Drizzle conventions, and migration flow.
05 · AI Platform
The in-house AI Gateway, five providers, Mastra agents, cost and failover.
06 · Identity & Billing
Better Auth sessions, plans, Xendit billing, and entitlements.
07 · Notifications & Offline Sync
Notification center, web push, client storage, and sync contracts.
08 · Deployment & Operations
Dual Vercel and Railway deploys, build config, and runtime operations.
09 · Security Posture
Trust boundaries, the controls deployed on each, and the hardening lessons that shaped them.
Architecture Decision Records
ADR-0001 · One Astro SSR app with Svelte islands
Why the marketing site and SaaS ship as a single server-rendered app.
ADR-0002 · Vercel and Railway from one config
Two deploy targets selected by DEPLOY_TARGET, one codebase.
ADR-0003 · ISR by default with an exclusion list
Public pages cache at the edge; personalised routes are explicitly excluded.
ADR-0004 · Feature gating through entitlements
Access is gated by plan entitlements, never user.role.
ADR-0005 · In-house AI Gateway with failover
Five LLM providers behind one gateway; each activates only when its key is set.