Club London Docs

▣ Architecture Overview

High-level infrastructure and service topology.

                 Cloudflare CDN
          clublondon.app  ·  *.clublondon.app

        ┌────────────────────────┐
        │    Hetzner CPX22        │
        │    Helsinki (cl-app)    │
        │                         │
        │  ┌────────────────┐   │
        │  │  Traefik v3     │   │
        │  │  (SSL auto)     │   │
        │  └────┬──────┬────┘   │
        │       │       │        │
        │  ┌────┴─┐ ┌──┴────┐ │
        │  │  API  │ │ Admin  │ │
        │  │ :3000 │ │  :80   │ │
        │  └───┬──┘ └───────┘ │
        │      │                 │
        │  ┌───┴───┐ ┌──────┐ │
        │  │Postgres│ │Redis │ │
        │  │  16    │ │  7   │ │
        │  └───────┘ └──────┘ │
        └────────────────────────┘

        ┌────────────────────────┐
        │   Expo / EAS Build    │
        │  iOS + Android apps    │
        │  → App Store / Play    │
        └────────────────────────┘

Domains

📁 Monorepo Structure

Turborepo-powered workspace organization.

clublondon/
├── apps/
│   ├── mobile/              # Expo SDK 54 / React Native
│   │   ├── app/             # Expo Router screens (30 screens)
│   │   │   ├── (auth)/      # Login, Register, Onboarding
│   │   │   ├── (tabs)/      # Home, Events, Travel, Matching, Profile
│   │   │   └── *.tsx        # Modal screens (wallet, concierge, etc.)
│   │   ├── assets/images/   # Generated hero images
│   │   ├── lib/             # API client, theme, stores
│   │   └── app.json         # Expo configuration
│   │
│   ├── admin/               # React 19 + Vite 6 admin panel
│   │   ├── src/
│   │   │   ├── App.tsx      # All pages + hash router
│   │   │   ├── api.ts       # API client
│   │   │   └── main.tsx     # Entry point
│   │   ├── Dockerfile       # Multi-stage → nginx
│   │   └── nginx.conf       # SPA routing config
│   │
│   └── api/                 # NestJS 11 + Fastify
│       ├── src/
│       │   ├── modules/     # Auth, Users, Events, Travel, etc.
│       │   ├── drizzle/     # ORM schema + migrations
│       │   ├── seed.ts      # Test data seeder
│       │   ├── app.module.ts
│       │   └── main.ts      # Bootstrap + CORS
│       └── Dockerfile       # Multi-stage build
│
├── packages/
│   ├── shared-types/        # TypeScript interfaces
│   └── validators/          # Zod schemas
│
├── infrastructure/
│   ├── docker/              # docker-compose.prod.yml + dev.yml
│   ├── cloudflare/          # DNS setup scripts
│   └── hetzner/             # Server provisioning
│
├── skills/
│   └── clublondon-deploy/   # Deploy automation (9 scripts)
│
├── .github/workflows/       # CI + deploy + EAS build
├── eas.json                 # EAS Build profiles
├── turbo.json               # Turborepo pipeline config
├── pnpm-workspace.yaml      # Workspace definition
└── CLAUDE.md                # AI assistant context

⚙ Technology Stack

Complete list of technologies across all layers.

Mobile App

Admin Panel

API Backend

Infrastructure

▶ Getting Started

Set up your local development environment.

Prerequisites

• Node.js >= 20
• pnpm >= 9.15.0
• Docker & Docker Compose
• Expo CLI (npm install -g eas-cli)

Installation

# Clone repository
git clone https://github.com/alegkoshyk/clublondon.git
cd clublondon

# Install dependencies
pnpm install

# Start local database & Redis
docker compose -f infrastructure/docker/docker-compose.dev.yml up -d

# Copy env file
cp .env.example .env.local
# Edit .env.local with your values

# Push database schema
pnpm db:push

# Seed test data
cd apps/api && npx ts-node src/seed.ts && cd ../..

# Start all apps
pnpm dev

Development URLs

Test Accounts

📱 Mobile App (Expo)

30 screens built with Expo SDK 54 and React Native.

Auth Flow

Tab Navigation (5 tabs)

Detail Screens

Feature Screens

Other Screens

State Management

• Auth: Zustand store with JWT in SecureStore
• Data: TanStack Query for server state
• Forms: React Hook Form + Zod validation

Theme

const colors = {
  bg:    '#0D0D1A',       // Primary background
  bg2:   '#1A1A2E',       // Secondary
  bg3:   '#16213E',       // Tertiary
  gold:  '#C4A35A',       // Primary accent
  gold2: '#D4B96A',       // Light gold
  white: '#FFFFFF',
  green: '#4CAF50',       // Success
  red:   '#F44336',       // Error
}

const fonts = {
  display: 'Cormorant Garamond',  // Headings
  body:    'DM Sans',               // Body text
}

EAS Build Profiles

# Build commands
eas build --profile preview --platform all
eas build --profile production --platform ios
eas submit --platform ios --latest
eas update --branch production --message "hotfix: ..."

💻 Admin Panel (React)

React 19 admin dashboard with hash-based routing.

URL Routing

CRUD Operations

Login

• URL: admin.clublondon.app
• Auth: JWT (stored in localStorage)
• Credentials: same as API accounts

⚡ API Backend (NestJS)

NestJS 11 with Fastify adapter and modular architecture.

Modules

Middleware & Security

• CORS: Configured for admin, mobile, localhost, Expo
• Helmet: Security headers
• Validation: Global ValidationPipe (whitelist + transform)
• Auth: JWT Bearer tokens via Passport.js
• Global Prefix: /api/v1

🗃 Database Schema

PostgreSQL 16 with Drizzle ORM. 9 tables total.

users

events

trips

rsvps

tripBookings

conciergeRequests

notifications

walletTransactions

sessions

🔒 Authentication

JWT-based authentication with access and refresh tokens.

Flow

1. POST /auth/login { email, password }
   → { accessToken, refreshToken, user }

2. All requests: Authorization: Bearer {accessToken}

3. Token expired → POST /auth/refresh { refreshToken }
   → { accessToken, refreshToken }

4. POST /auth/logout { refreshToken }

Token Configuration

🔗 API Endpoints

Complete REST API reference. Base URL: /api/v1

Auth

Users

Events

Travel

Concierge

Wallet

Notifications

☁ Infrastructure

Server setup, Docker containers, and Cloudflare configuration.

Server: Hetzner CPX22

• Location: Helsinki, Finland
• Resources: 3 vCPU, 4 GB RAM, 80 GB NVMe
• OS: Ubuntu 24.04

Docker Containers (Production)

Cloudflare

• DNS Records: A records for @, api, admin, staging-api
• SSL: Full (strict)
• Storage: R2 bucket cl-media

🚀 CI/CD Pipelines

GitHub Actions workflows for testing, building, and deploying.

GitHub Actions Workflows

1. CI (ci.yml)

• Trigger: PR to develop/main, push to develop
• Steps: Install → Lint → TypeCheck → Build → Test

2. Deploy Staging (deploy-staging.yml)

• Trigger: Push to develop
• Steps: Build → Push images (:staging) → SSH deploy → Health check

3. Deploy Production (deploy-production.yml)

• Trigger: Push to main
• Steps: Build → Push images (:latest + :sha) → SSH deploy → Health check

4. EAS Build (eas-build.yml)

• Trigger: Manual dispatch
• Inputs: platform (ios/android/all), profile (dev/preview/prod)

Git Branching

main       ← production deploys
  ↑
develop    ← staging deploys (auto)
  ↑
feature/*  ← development (squash merge to develop)
hotfix/*   ← from main (merge commit)

🔧 Deploy Scripts

Automation scripts in skills/clublondon-deploy/scripts/

Manual Deploy

# Build images locally
docker build --platform linux/amd64 -t cl-api:latest -f apps/api/Dockerfile .
docker build --platform linux/amd64 -t cl-admin:latest -f apps/admin/Dockerfile .

# Save, transfer, load
docker save cl-api:latest | gzip | ssh -i ~/.ssh/cl-deploy root@server "gunzip | docker load"
docker save cl-admin:latest | gzip | ssh -i ~/.ssh/cl-deploy root@server "gunzip | docker load"

# Restart containers on server
ssh -i ~/.ssh/cl-deploy root@server "cd /opt/clublondon && docker compose up -d"

🔑 Environment Variables

Required and optional configuration variables.

Required

# Database
DATABASE_URL=postgresql://clublondon:password@localhost:5432/clublondon

# Redis
REDIS_URL=redis://:password@localhost:6379

# JWT
JWT_SECRET=your-secret-key
JWT_REFRESH_SECRET=your-refresh-secret

# Cloudflare R2
CLOUDFLARE_R2_ACCESS_KEY_ID=
CLOUDFLARE_R2_SECRET_ACCESS_KEY=
CLOUDFLARE_R2_BUCKET=cl-media

# Expo (mobile)
EXPO_PUBLIC_API_URL=https://api.clublondon.app

Optional

# App
NODE_ENV=development
PORT=3000
APP_URL=https://clublondon.app
ADMIN_URL=https://admin.clublondon.app

# Stripe (future)
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Hetzner (deploy)
HCLOUD_TOKEN=

# Cloudflare (DNS)
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_ZONE_ID=
CLOUDFLARE_ACCOUNT_ID=

# EAS (builds)
EXPO_TOKEN=

🎨 Design System

Colors, typography, spacing, and component patterns.

Colors

Typography

Spacing

Border Radius

Component Patterns

• Cards: rgba(255,255,255,0.04) bg + rgba(255,255,255,0.06) border + 16px radius
• Badges: Colored text + tinted background + pill radius
• Buttons Primary: Gold bg + dark text + 600 weight
• Buttons Secondary: Transparent bg + white border + white text
• Inputs: rgba(255,255,255,0.04) bg + 8px radius + white text
• Tables: Collapsed borders + hover rgba(255,255,255,0.02)

⌨ Key Commands Reference

Quick reference for all development, build, and deploy commands.

# Development
pnpm dev              # All apps parallel
pnpm dev:api          # API only (port 3000)
pnpm dev:mobile       # Mobile Expo (port 8081)
pnpm dev:admin        # Admin Vite (port 5173)

# Database
pnpm db:generate      # Generate Drizzle migrations
pnpm db:push          # Push schema to PostgreSQL
pnpm db:studio        # Open Drizzle Studio GUI

# Build
pnpm build            # Build all
pnpm build:api        # Build API
pnpm build:admin      # Build Admin

# Quality
pnpm lint             # ESLint all apps
pnpm typecheck        # TypeScript check all
pnpm test             # Run tests

# Mobile
eas build --profile preview --platform all
eas submit --platform ios --latest
eas update --branch production --message "fix"

# Deploy
bash skills/clublondon-deploy/scripts/status.sh
bash skills/clublondon-deploy/scripts/deploy.sh prod