# xenous-inc/turbo-web-template architecture

> Architecture diagram of the GitHub repository xenous-inc/turbo-web-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xenous-inc/turbo-web-template
- Repository: https://github.com/xenous-inc/turbo-web-template

## Overview

##### Main Components
a. Frontend Application:
- Located in apps/client, which is a Next.js application.
- Contains multiple React Providers (AuthProvider, TRPCProvider, RwdotProvider, ThemeProvider, ToastProvider). These providers indicate separation of cross-cutting concerns such as authentication, theme management, and notifications.
- Acts as the UI layer and client-side entry point.

b. API & Server Components:
- The Next.js application also includes API routes (under apps/client/src/app/api) for authentication (including a sign-up flow) and for tRPC.
- The tRPC endpoints facilitate client-server communication using the typesafe RPC mechanism.

c. Supporting Packages in the Monorepo:
- packages/api: Implements API core logic and routing.
- packages/auth: Handles authentication logic and sign-up flows.
- packages/db: Contains Prisma schema and database access code.
- packages/http: Provides HTTP client functionality along with interceptors and error handling.
- packages/logger: Implements logging utilities.
- packages/schema: Defines common constants, helper functions, and model definitions ensuring type safety.
- packages/ui: Provides reusable UI components such as Button, Spinner, Theme, and Toast.

d. Shared Tooling & Configurations:
- Tooling directories (for ESLint, Prettier, Tailwind, etc.) ensure standardization across both apps and packages.
- Configuration files like .env.example, turbo.json, and pnpm-workspace.yaml help manage environment variables, build pipelines, and dependency management across the monorepo.

##### Out the Relationships & Interactions
- The Next.js client (frontend) uses its various Providers to wrap the application. The TRPCProvider, for example, directly communicates with the API endpoints (e.g., apps/client/src/app/api/trpc) to fetch and mutate data.
- API endpoints in the client delegate functionality to the separate backend packages (or even call shared logic available in packages/api, packages/auth, etc.).
- The authentication flow demonstrates a layered interaction: the client triggers API calls, which are then handled by packages/auth (for sign-up and login logic) and further integrated with packages/db for persisting user data.
- Shared UI components (from packages/ui) and helper libraries (from packages/schema, packages/http, etc.) serve both client-side and backend needs, underscoring reusability across layers.
- Tooling and configuration packages act as the backbone, ensuring the consistency of the development and deployment pipelines.

##### Important Architectural Patterns & Design Principles
- Modularization: The monorepo splits functionality into clearly defined packages where each package addresses a specific domain (authentication, database, HTTP, etc.).
- Separation of Concerns: The frontend and backend are distinctly separated (e.g., Next.js app versus business logic in packages) using clear boundaries.
- Providers Pattern: In the Next.js application, multiple Provider components inject capabilities (authentication, theming, notifications) into the component tree.
- Type Safety & Reusability: Packages like packages/schema ensure type consistency across different layers (for example, between API and client).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Next.js)"
        FE["Next.js App"]:::frontend
        subgraph "Providers"
            AP["AuthProvider"]:::provider
            TP["TRPCProvider"]:::provider
            RP["RwdotProvider"]:::provider
            THP["ThemeProvider"]:::provider
            TSP["ToastProvider"]:::provider
        end
        subgraph "API Routes"
            ARA["API: Authentication"]:::api
            ART["API: tRPC"]:::api
        end
    end

    subgraph "Backend Services"
        APL["API Core Logic Package"]:::backend
        ALP["Authentication Logic Package"]:::backend
        DBP["Database Access Package"]:::backend
        HCP["HTTP Client Package"]:::backend
        LP["Logging Utilities Package"]:::backend
        SDP["Schema Definitions Package"]:::backend
        UICP["UI Components Package"]:::backend
        TPConf["Tooling & Configurations"]:::tooling
    end

    %% Relationships
    FE --> AP
    FE --> TP
    FE --> RP
    FE --> THP
    FE --> TSP

    TP -->|"calls"| ART
    AP -->|"calls"| ARA

    ART -->|"delegates"| APL
    ARA -->|"delegates"| ALP
    ALP -->|"accesses"| DBP

    TP -->|"httpCalls"| HCP

    ARA -->|"logs"| LP
    ART -->|"logs"| LP

    FE -->|"uses"| UICP

    %% Click Events
    click FE "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client"
    click AP "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/(_providers)/AuthProvider"
    click TP "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/(_providers)/TRPCProvider"
    click RP "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/(_providers)/RwdotProvider"
    click THP "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/(_providers)/ThemeProvider"
    click TSP "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/(_providers)/ToastProvider"
    click ARA "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/api/auth"
    click ART "https://github.com/xenous-inc/turbo-web-template/tree/main/apps/client/src/app/api/trpc"
    click APL "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/api"
    click ALP "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/auth"
    click DBP "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/db"
    click HCP "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/http"
    click LP "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/logger"
    click SDP "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/schema"
    click UICP "https://github.com/xenous-inc/turbo-web-template/tree/main/packages/ui"
    click TPConf "https://github.com/xenous-inc/turbo-web-template/tree/main/tooling"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef provider fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef api fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef backend fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef tooling fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
```
