Architecture Overview

Technical architecture documentation for the GaugeWell platform.

System Architecture


┌─────────────────────────────────────────────────────────────┐
│                     Client Browser                          │
└──────────┬──────────────────────────────────┬───────────────┘
           │                                  │
           ▼                                  ▼
┌─────────────────────┐          ┌─────────────────────┐
│   Client Portal     │          │   Admin Portal      │
│   (Next.js)         │          │   (Next.js)         │
│   portal.gaugewell  │          │   admin.gaugewell   │
└──────────┬──────────┘          └──────────┬──────────┘
           │                                │
           ▼                                ▼
┌─────────────────────────────────────────────────────────────┐
│                    Shared Database (Neon PostgreSQL)         │
│  portal_users, portal_organizations, cms_clients,           │
│  crm_leads, crm_clients, goals, kpis, action_items, ...    │
└──────────┬──────────────────────────────────┬───────────────┘
           │                                  │
           ▼                                  ▼
┌─────────────────────┐          ┌─────────────────────┐
│  Integration Layer  │          │  Northstar Auditor  │
│  (Python services)  │          │  (Scanner API)      │
│  CRM, CMS, Content  │          │  11-stage pipeline  │
│  Billing, Social    │          │  Score calculation   │
└─────────────────────┘          └─────────────────────┘

Technology Stack

Layer	Technology	Purpose
Frontend	Next.js 16, React 19, TypeScript	Server & client rendering
Styling	Tailwind CSS v3, `@gaugewell/theme`	Shared design system
Auth (Portal)	Custom JWT + 2FA/TOTP	Portal user authentication
Auth (Admin)	Custom JWT + RBAC	Admin role-based access
Database	Neon PostgreSQL (serverless)	Primary data store
Background Jobs	Inngest	Async task processing
Payments	Stripe	Subscriptions and billing
Hosting	Vercel	Edge deployment
Error Tracking	Sentry	Runtime error monitoring
Analytics	Vercel Analytics	Performance monitoring
Integrations	Python microservices	CRM, CMS, Content AI, Social

Application Structure

Monorepo Layout


GaugeWell Web/           # Next.js monorepo (pnpm workspaces)
├── apps/
│   ├── admin/           # Admin portal (admin.gaugewell.io)
│   ├── portal/          # Client portal (portal.gaugewell.io)
│   ├── docs/            # Documentation site (docs.gaugewell.io)
│   └── landing/         # Marketing site (gaugewell.io)
├── packages/
│   └── theme/           # Shared design system (@gaugewell/theme)
├── migrations/          # SQL migration files
└── scripts/             # Utility scripts

GaugeWell Integrations/  # Python microservices monorepo
├── apps/
│   ├── billing-integration/
│   ├── cms-integration/
│   ├── content-ai/
│   ├── crm-integration/
│   ├── northstar-auditor/
│   ├── proofing-integration/
│   └── social-integration/
└── shared/              # Shared utilities

Authentication Model

The platform uses two parallel authentication systems:

Portal Authentication — For client users:

Custom JWT stored in portal_token cookie
UUID-based user IDs (portal_users table)
Organization membership via portal_org_members
Optional 2FA via TOTP

Admin Authentication — For GaugeWell staff:

Custom JWT stored in admin_token cookie
Integer-based user IDs (admin_users table)
Role-based access control (RBAC) with granular permissions
Session validation against admin_sessions table

GaugeWell staff access client portals via impersonation, not membership. Staff emails (@gaugewell.io) should never be added to portal_org_members or cms_memberships.

Multi-Tenant Architecture

Each client organization can have:

A shared database connection (default — uses the platform’s Neon database)
A dedicated tenant database (provisioned via Neon branching for data isolation)

Tenant resolution follows this priority:

cms_tenant_databases — Dedicated database if provisioned
cms_memberships — Shared database with client scoping
DATABASE_URL fallback — Shared database for dev/demo accounts

Key Design Principles

Server Components First — Use React Server Components by default; client components only for interactivity
Shared Theme Package — All UI tokens, components, and chart themes live in @gaugewell/theme
Granular Permissions — Every admin API route uses specific AuthConfigs (e.g., clientsRead, contentManage)
Audit Everything — All mutations are automatically logged to admin_audit_logs
Graceful Degradation — Portal pages handle missing data with empty states and skeleton loading
Vertical Awareness — Scoring, dashboards, and content adapt to the client’s business type

Decision Records

See Architecture Decision Records for documented decisions on technology choices, patterns, and trade-offs.