CHALK Documentation
Learn how to develop, run, and scale your institutional ERP using the CHALK architecture.
Architecture & Stack
CHALK is a multi-tenant SaaS ERP for institutions and organisations. It features 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, and development modules:
pnpm dev
pnpm native
pnpm --filter mobile android
pnpm --filter mobile ios
pnpm db:seed
pnpm migrate:generate <name>
pnpm db:migrate
pnpm clean