THUNDER Stack Documentation

Learn how to develop, run, deploy, and scale applications using the THUNDER architecture stack.

Database & Drizzle Guide

PostgreSQL connection setup, Aiven SSL fix, schema breakdown, and complete pnpm db:* CLI reference.

Vercel & Cloudflare Deploy Guide

Step-by-step instructions to deploy Next.js to Vercel/Cloudflare Pages and Hono API to Cloudflare Workers.

Architecture & Stack

THUNDER Stack is a high-performance, developer-first boilerplate optimized for serverless runtime environments. It links multiple modules in a unified monorepo: a PostgreSQL database with Drizzle ORM, a Cloudflare Workers Hono backend, a Next.js App Router web client, and an Expo mobile client.

Backend API (Hono)

The backend is powered by Hono, running inside a Cloudflare Workers (Wrangler) sandbox. It provides lightweight, extremely fast execution and exposes REST endpoints for user profiles, database queries, and role-based permissions.

Web Client (Next.js)

Built on Next.js 15 (App Router) and React 19. It uses a custom global DashboardContext hook to fetch and synchronize user profiles, permissions, and active roles once at the layout level. This eliminates redundant page-load requests and provides instantaneous page transitions.

Mobile App (Expo)

An Expo 54 client using Expo Router for dynamic file-based mobile navigation. It features a custom CustomTabBar layout rendering direct links and dynamic overflow menus. Session tokens are securely cached in the mobile hardware-encrypted SecureStore.

Database & Drizzle

Uses PostgreSQL as the datastore. Connections are lazily evaluated in Drizzle ORM to avoid serverless cold starts. The connection pool dynamically caps concurrent queries and automatically reaps dead connection sockets to prevent locks and deadlocks inside wrangler.

Authentication (Better Auth)

Secured using Better Auth. It handles standard email/password authentication (verified using 6-digit email OTPs) as well as Google Social OAuth. Web clients utilize credentials sharing across ports, while mobile clients use secure HTTP headers.

Command Reference

Execute the following package manager commands in the workspace root to control different services, migrations, deployments, and development modules:

# Start Development Servers (Backend Hono + Web Next.js)

pnpm dev

# Build Next.js Web Client for Production (Vercel)

pnpm build

# Build Next.js Web Client for Cloudflare Pages

pnpm build:web:cf

# Deploy Hono Backend API to Cloudflare Workers

pnpm deploy:server

# Check Migration & DB SSL Health Status

pnpm db:status

# Seed Database (Roles, Permissions, Users)

pnpm db:seed

# Apply All Database Migrations

pnpm db:migrate

# Start the Expo Mobile App (with Cache Clearing)

pnpm native