# t3-oss/create-t3-turbo architecture

> Architecture diagram of the GitHub repository t3-oss/create-t3-turbo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/t3-oss/create-t3-turbo
- Repository: https://github.com/t3-oss/create-t3-turbo

## Overview

##### Project Type and Purpose
- It’s a monorepo template designed to build full-stack applications with separate frontends and backends.
- The README emphasizes two main frontend apps (Next.js for web and Expo for mobile) plus an auth-proxy (a Nitro server for OAuth flows) and several shared packages (api, auth, db, ui, validators).
- The goal is to provide code splitting, shared logic, and type safety while still keeping concerns separated.

##### Analyzing the File Structure
- Top-level directories include:
- apps: Contains distinct application frontends and servers:
- auth-proxy – a lightweight server for handling OAuth proxying.
- expo – the React Native/Expo app showcasing mobile functionality (e.g., using Expo Router, NativeWind).
- nextjs – the Next.js application for web with tRPC API routes and middleware.
- packages: Shared logic and libraries:
- api – where the tRPC router and server logic lives.
- auth – next-auth based authentication logic.
- db – database access logic using Drizzle and Supabase/Vercel Postgres.
- ui – a shared UI component library for the web (built using shadcn-ui).
- validators – input/logic validation code.
- tooling: Standardized configuration for eslint, prettier, tailwind, and TypeScript.
- Notice additional configuration like turbo.json, pnpm-workspace.yaml, and GitHub workflows that indicate CI, automated linting, and build steps.

##### Key Insights from the README
- The README calls out integration details, such as the special handling of NextAuth with Expo, using the auth-proxy for OAuth, and how the tRPC API is configured.
- There is a clear separation between the mobile Expo app and the Next.js web app, with both consuming shared packages (especially the API package) while keeping backend code isolated from client applications.
- Deployment details for each component (Next.js to Vercel, Auth Proxy as a Nitro/Vercel Edge function, and Expo build processes with EAS) also guide the architectural interactions.

a. Main Components:
- Frontend Applications:
- Next.js App (Web Frontend)
- Expo App (Mobile Frontend)
- Backend / API Components:
- Auth Proxy (OAuth handling via Nitro server)
- API Package (tRPC router and backend API endpoints)
- Auth Package (authentication logic via next-auth)
- DB Package (database layer using Drizzle, Supabase/Vercel Postgres driver)
- UI Library:
- UI Package (shared React components for the Next.js frontend)
- Development Tooling:
- Tooling configuration (eslint, prettier, tailwind, TypeScript shared settings)
- Validators:
- Input and business logic validation shared across apps

b. Relationships and Interactions:
- The Next.js app communicates with the backend API provided by the API package through tRPC endpoints.
- The Expo app interacts with the same API (for typesafe API calls) and depends on configuration in packages like auth and db.
- Both Next.js and Expo utilize the shared auth package to implement authentication mechanisms. However, due to mobile constraints, the Expo app might delegate OAuth flows to the auth-proxy.
- The auth-proxy acts as a mediator for OAuth requests, particularly in preview deployments for the Expo app, funneling authentication flows between the client (Next.js/Expo) and external OAuth providers.
- The UI package is exclusively consumed by the Next.js app for its component system.
- The DB package encapsulates database interactions and is used by the API package and possibly the auth package for secure, typesafe database calls.

c. Architectural Patterns and Design Principles:
- Modular Separation: Clear separation between frontends, backend, and shared packages for reusability and maintainability.
- Monorepo Management: Use of Turborepo to streamline builds, cache configurations, and ensure consistency across packages.
- Typesafety: Emphasis on using shared types through packages such as api, db, and validators.
- CI/CD Integration: Leveraging GitHub workflows and tooling configurations for code quality and deployment consistency.

d. Noting Relevant Technologies/Frameworks:
- Frameworks: Next.js, Expo, and React.
- Authentication: NextAuth (via the auth package) and Auth.js core (in the auth-proxy).
- Backend/API: tRPC for type-safe API routes.
- Database: Drizzle with Supabase/Vercel Postgres integration.
- Styling: Tailwind CSS along with NativeWind for Expo.
- Tooling: ESLint, Prettier, and shared TypeScript configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        NEXTJS["Next.js App"]:::frontend
        EXPO["Expo App"]:::frontend
    end

    %% Backend & API Layer
    subgraph "Backend & API Layer"
        AUTH_PROXY["Auth Proxy"]:::backend
        API["API Package"]:::backend
    end

    %% Shared Packages
    subgraph "Shared Packages"
        AUTH_PKG["Auth Package"]:::shared
        DB_PKG["DB Package"]:::shared
        UI_PKG["UI Package"]:::shared
        VALIDATORS["Validators"]:::shared
    end

    %% Tooling Configuration
    subgraph "Tooling & Config"
        TOOLING["Tooling Configuration"]:::tooling
    end

    %% Connections between components
    NEXTJS -->|"calls"| API
    EXPO -->|"calls"| API
    NEXTJS -->|"uses"| UI_PKG
    NEXTJS -->|"auth"| AUTH_PKG
    EXPO -->|"auth"| AUTH_PKG
    EXPO -->|"OAuthFlows"| AUTH_PROXY
    API -->|"dbCalls"| DB_PKG
    AUTH_PKG -->|"dbAccess"| DB_PKG

    %% Click Events
    click NEXTJS "https://github.com/t3-oss/create-t3-turbo/tree/main/apps/nextjs"
    click EXPO "https://github.com/t3-oss/create-t3-turbo/tree/main/apps/expo"
    click AUTH_PROXY "https://github.com/t3-oss/create-t3-turbo/tree/main/apps/auth-proxy"
    click API "https://github.com/t3-oss/create-t3-turbo/tree/main/packages/api"
    click AUTH_PKG "https://github.com/t3-oss/create-t3-turbo/tree/main/packages/auth"
    click DB_PKG "https://github.com/t3-oss/create-t3-turbo/tree/main/packages/db"
    click UI_PKG "https://github.com/t3-oss/create-t3-turbo/tree/main/packages/ui"
    click VALIDATORS "https://github.com/t3-oss/create-t3-turbo/tree/main/packages/validators"
    click TOOLING "https://github.com/t3-oss/create-t3-turbo/tree/main/tooling"

    %% Styles
    classDef frontend fill:#bbf,stroke:#2a2,stroke-width:2px;
    classDef backend fill:#fcc,stroke:#a22,stroke-width:2px;
    classDef shared fill:#cfc,stroke:#2aa,stroke-width:2px;
    classDef tooling fill:#ff9,stroke:#aa2,stroke-width:2px;
```
