How carlosziegler/fullstack-start-template works
Project Type and Purpose
• This is a modern full-stack web application boilerplate:
• Frontend: React + Vite + Vinxi (SSR) + TanStack Router
• Backend/API: tRPC server + file-based routing
• Database: Drizzle ORM on Neon Postgres (serverless)
• AI & Email: OpenAI/Vercel AI SDK, RAG, Resend transactional email
• Auth: Better Auth (session, OTP, passkeys)
• DX: TypeScript, Bun, Biome, Vitest, Docker, GitHub Actions
File-Structure Analysis
• src/components: shared UI (shadcn/ui, Tailwind)
• src/features: feature-scoped UI + logic (auth, ai, files, user, admin, org)
• src/lib: core libraries (auth-client/middleware, db schema & migrations, env, trpc init, intl, resend)
• src/routes: TanStack Router file-based routes (public, auth, dashboard, api/ai, api/auth, api/trpc)
• src/server: server routes + tRPC router
• src/server.ts: server-side entry (SSR + API)
• Supporting: Dockerfile(.dev), compose.yaml, GitHub Actions, nginx.conf
Main Components (
A. Client Tier
– Browser renders React (hydration + CSR)
– TanStack Router drives navigation
– TanStack Query/DB manage server & client state
– Static assets (public/) served via CDN / nginx
B. Server Tier (Bun-based SSR + API)
– SSR engine (Vinxi/Vite)
– File-based HTTP routes (public pages + dashboard UI)
– tRPC endpoints (client↔server type-safe RPC)
– AI routes: chat, RAG, image-generation, MCP adapter
– Auth routes & middleware (Better Auth)
C. Data Tier
– Drizzle ORM → Neon Postgres (serverless)
– Migrations and schema under src/lib/db
– pg_vector extension for embeddings
D. External Services
– Resend (email delivery)
– Sentry (monitoring)
– Vercel/v0 or OpenAI (AI models)
– GitHub Container Registry (CI/CD)
E. Deployment Infrastructure
– Docker / Docker Compose for local/dev
– GitHub Actions workflow builds multi-stage image
– nginx reverse proxy (nginx.conf)
– Environment variables via .env (auto-populated by neon plugin or manual)
Relationships & Data Flows
• Client → nginx → Bun server (HTTP/SSR)
• Client API calls → tRPC over HTTP → server.router → trpc handlers → lib/db → Neon Postgres
• AI chat UI → /api/ai/* endpoints → AI SDK → external AI provider → server → client
• File uploads → /api/ai embeddings → pg_vector extension → Drizzle ORM → Postgres
• Auth flows → Better Auth middleware → session store → db
• Email triggers → lib/resend → Resend API
• Monitoring hooks → Sentry SDK → Sentry service
Architectural Patterns & Principles
• Separation of concerns: UI (components/features) vs. API vs. DB
• Type-safe end-to-end (TypeScript, tRPC, Zod, Drizzle)
• SSR + CSR hybrid for performance & SEO
• Reactive client data (TanStack Query + TanStack DB live queries)
• File-based routing for both client (TanStack Router) and server (Vinxi/Vite)
• Micro-frontend-like features: each feature folder self-contained
• CI/CD via multi-stage Docker & GitHub Actions