# carlosziegler/fullstack-start-template architecture

> Architecture diagram of the GitHub repository carlosziegler/fullstack-start-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carlosziegler/fullstack-start-template
- Repository: https://github.com/carlosziegler/fullstack-start-template

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client LAN"
        direction TB
        Browser["Browser (React + Vite)"]:::frontend
        Router["TanStack Router"]:::frontend
        Query["TanStack Query/DB"]:::frontend
        Static["Static Assets (public/)"]:::frontend
    end

    %% DMZ
    subgraph "DMZ"
        direction TB
        CDN["CDN"]:::infra
        NGINX["nginx Reverse Proxy"]:::infra
    end

    %% Backend/API Tier
    subgraph "Backend Network"
        direction TB
        SSR["SSR Engine (Bun + Vinxi/Vite)"]:::backend
        Routes["File-based HTTP Routes"]:::backend
        tRPC["tRPC API Layer"]:::backend
        subgraph "Business Logic"
            direction TB
            AuthBL["Auth (Better Auth)"]:::backend
            AIBL["AI Endpoints & Logic"]:::backend
            FilesBL["File Upload & Embeddings"]:::backend
            OtherFeatures["Other Features (Admin, Org)"]:::backend
        end
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        ORM["Drizzle ORM"]:::db
        Postgres["Neon Postgres\n(pg_vector)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Resend["Resend Email Service"]:::external
        Sentry["Sentry Monitoring"]:::external
        AIProv["AI Providers\n(OpenAI/Vercel)"]:::external
        Registry["Container Registry"]:::external
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Deployment"
        direction TB
        Actions["GitHub Actions"]:::infra
        Image["Docker Image"]:::infra
        Compose["Docker Compose / Dev"]:::infra
    end

    %% Flows
    Browser -->|"Hydrated SSR HTML"| NGINX
    Router -->|"SPA Navigation"| NGINX
    Static --> CDN --> NGINX
    NGINX -->|"HTTP/SSR"| SSR
    SSR --> Routes
    SSR --> tRPC
    SSR --> ORM
    tRPC -->|"POST /trpc"| tRPCRouter[/"tRPC Router"/]:::backend
    tRPCRouter --> ORM
    Routes --> AuthBL
    Routes --> AIBL
    Routes --> FilesBL
    Routes --> OtherFeatures
    AuthBL --> ORM
    AIBL --> AIProv
    AIBL --> ORM
    FilesBL --> ORM
    ORM --> Postgres
    ORM -->|"SQL Queries"| Postgres
    AIBL -->|"Embeddings"| ORM
    AuthBL --> Resend
    AuthBL --> Sentry
    AIBL --> Sentry
    Actions --> Image --> Registry
    Registry -->|"Deploy"| Compose
    Compose --> NGINX

    %% Click Events
    click Router "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/router.tsx"
    click Router "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routeTree.gen.ts"
    click Browser "https://github.com/carlosziegler/fullstack-start-template/blob/main/vite.config.ts"
    click Static "https://github.com/carlosziegler/fullstack-start-template/tree/main/public/"
    click SSR "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/server.ts"
    click SSR "https://github.com/carlosziegler/fullstack-start-template/blob/main/vite.config.ts"
    click tRPCRouter "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/trpc/init.ts"
    click tRPCRouter "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/trpc/react.ts"
    click tRPCRouter "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/trpc/root-provider.tsx"
    click tRPCRouter "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/trpc/$.ts"
    click tRPCRouter "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/server/router.ts"
    click Routes "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/routes/(auth)/"
    click Routes "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/routes/(public)/"
    click Routes "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/routes/dashboard/"
    click Routes "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/__root.tsx"
    click Routes "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/[.]well-known.oauth-authorization-server.ts"
    click AIBL "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/features/ai/"
    click AIBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/ai/chat.image.generation.ts"
    click AIBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/ai/chat.rag.ts"
    click AIBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/ai/chat.ts"
    click AIBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/ai/mcp/$transport.ts"
    click AIBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/ai/vercel/chat.ts"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/features/auth/"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/auth/auth-client.ts"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/auth/auth-middleware.ts"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/auth/auth.ts"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/auth/permissions.ts"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/api/auth/$.ts"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/(auth)/login.tsx"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/(auth)/register.tsx"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/(auth)/forgot-password.tsx"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/routes/(auth)/reset-password.tsx"
    click AuthBL "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/routes/(auth)/two-factor/"
    click ORM "https://github.com/carlosziegler/fullstack-start-template/blob/main/drizzle.config.ts"
    click ORM "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/lib/db/schema/"
    click ORM "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/lib/db/migrations/"
    click ORM "https://github.com/carlosziegler/fullstack-start-template/blob/main/scripts/setup-vector-extension.ts"
    click Resend "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/lib/resend.ts"
    click Resend "https://github.com/carlosziegler/fullstack-start-template/tree/main/src/components/emails/"
    click Actions "https://github.com/carlosziegler/fullstack-start-template/blob/main/.github/workflows/build-docker.yml"
    click Compose "https://github.com/carlosziegler/fullstack-start-template/tree/main/Dockerfile"
    click Compose "https://github.com/carlosziegler/fullstack-start-template/blob/main/Dockerfile.dev"
    click Compose "https://github.com/carlosziegler/fullstack-start-template/blob/main/compose.yaml"
    click NGINX "https://github.com/carlosziegler/fullstack-start-template/blob/main/nginx.conf"
    click Static "https://github.com/carlosziegler/fullstack-start-template/blob/main/src/styles.css"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFF7DF,stroke:#22863a,color:#22863a;
    classDef db fill:#FFF5B1,stroke:#bf8700,color:#bf8700;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef infra fill:#EDEBF8,stroke:#6f42c1,color:#6f42c1;
```
