# dangvanthanh/remix-turborepo-boilerplate architecture

> Architecture diagram of the GitHub repository dangvanthanh/remix-turborepo-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dangvanthanh/remix-turborepo-boilerplate
- Repository: https://github.com/dangvanthanh/remix-turborepo-boilerplate

## Overview

##### Project Type & Purpose
- This is a **full-stack monorepo** managed by Turborepo and pnpm.
- The core application is a **Remix web app** (“apps/web”), which bundles both client and server logic.
- The monorepo also contains reusable **packages** for UI components, shared utilities, internationalization, and configuration.

##### File Structure
- Top-level directories:
- `/apps/web` (Remix app)
- `/packages/ui` (Shadcn-based React UI library)
- `/packages/shared` (generic hooks & functions)
- `/packages/i18n` (Lingui integration & locale files)
- `/packages/biome-config` & `/packages/typescript-config` (repo-wide lint/TS presets)
- Build/tool config files at root: `turbo.json`, `package.json`, `pnpm` workspace, Biome, Vite, Tailwind, etc.

##### README Insights
- Confirms:
- **pnpm** as package manager
- **Turborepo** for workspace orchestration & remote caching
- **TypeScript**, **Biome**, **Shadcn UI**, **Remix**, **Vite** as main technologies
- No external database or microservices—purely front-end/backend in one Remix app.

##### Main Components & Their Relationships
a. **Monorepo Root**
- Orchestrator: Turborepo CLI, pnpm workspace, shared configs (biome, TS).
b. **apps/web (Remix App)**
- **Client Bundle** (entry.client.tsx → Vite → browser)
- **Server Runtime** (entry.server.tsx → Remix server → Node)
- **Route Handlers** (`app/routes/*.tsx` invoking loaders/actions)
- **UI Components** imported from `packages/ui`
- **Shared Utilities** imported from `packages/shared`
- **i18n Layer** (Lingui) via `packages/i18n`
- **Styling**: Tailwind CSS config + global/styles.css
c. **packages/ui**
- React component library with Storybook stories
- Exposed via package imports to `apps/web`
d. **packages/shared**
- Utility functions & custom hooks
- Consumed by both server loaders and client code
e. **packages/i18n**
- Lingui tooling + locale files
- Provides translation loader hooks & Remix route integrations
f. **Config Packages**
- `biome-config`: centralized lint/format settings
- `typescript-config`: TS base/React/Next presets
g. **Build & Dev Toolchain**
- **Turbo**: orchestrates `pnpm run dev` / `build`, remote caching (Vercel)
- **pnpm**: physical linking of workspace packages
- **Vite**: dev server & bundler for the Remix client
- **Tailwind**: CSS utility framework
- **Biome**: linting/formatting

##### Architectural Patterns & Design Principles
- **Monorepo Pattern**: single repo, multiple packages & apps
- **Code Reuse**: UI & shared logic abstracted into packages
- **Separation of Concerns** within the Remix app: client vs. server entrypoints, routes vs. components
- **Orchestration**: Turborepo’s pipeline for parallel builds & caching

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root
    subgraph "Monorepo Root"
        direction TB
        Orchestrator["Turborepo & pnpm"]:::root
        LintTSConfig["Root Lint & TS Configs"]:::config
    end

    %% Remix Web App
    subgraph "apps/web (Remix Web App)" 
        direction TB
        WebApp["Remix App"]:::app
        ClientEntry["entry.client.tsx"]:::app
        ServerEntry["entry.server.tsx"]:::app
        RootFile["root.tsx"]:::app
        RoutesFolder["routes/"]:::app
        Styles["styles.css"]:::app
        ViteConfig["vite.config.ts"]:::app
        TailwindConfig["tailwind.config.ts"]:::app
        WebBiomeConfig["biome.json"]:::app
        WebTsConfig["tsconfig.json"]:::app
        WebApp --> ClientEntry
        WebApp --> ServerEntry
        WebApp --> RootFile
        WebApp --> RoutesFolder
        WebApp --> Styles
        WebApp --> ViteConfig
        WebApp --> TailwindConfig
        WebApp --> WebBiomeConfig
        WebApp --> WebTsConfig
    end

    %% UI Package
    subgraph "packages/ui (UI Component Library)" 
        direction TB
        UI["UI Library"]:::package
        UIComponents["src/components"]:::package
        UIHooks["src/hooks"]:::package
        UIUtils["src/utils"]:::package
        Storybook[".storybook"]:::package
        UI --> UIComponents
        UI --> UIHooks
        UI --> UIUtils
        UI --> Storybook
    end

    %% Shared Package
    subgraph "packages/shared (Shared Utilities)" 
        direction TB
        Shared["Shared Utils"]:::package
        SharedFuncs["src/functions"]:::package
        SharedHooks["src/hooks"]:::package
        SharedClient["src/client-only.tsx"]:::package
        Shared --> SharedFuncs
        Shared --> SharedHooks
        Shared --> SharedClient
    end

    %% i18n Package
    subgraph "packages/i18n (Internationalization)" 
        direction TB
        I18n["i18n Package"]:::package
        I18nIndex["src/index.ts"]:::package
        LinguiServer["src/lingui.server.ts"]:::package
        ReactRouterServer["src/react-router.server.ts"]:::package
        I18nUtils["src/utils.ts"]:::package
        I18nLocales["locales/"]:::package
        LinguiConfig["lingui.config.ts"]:::package
        I18n --> I18nIndex
        I18n --> LinguiServer
        I18n --> ReactRouterServer
        I18n --> I18nUtils
        I18n --> I18nLocales
        I18n --> LinguiConfig
    end

    %% Config Packages
    subgraph "Config Packages"
        direction TB
        BiomeConfigPkg["biome-config"]:::package
        BiomeJson["biome.json"]:::package
        TsConfigPkg["typescript-config"]:::package
        TSBase["base.json"]:::package
        TSReact["react-library.json"]:::package
        TSNext["nextjs.json"]:::package
        BiomeConfigPkg --> BiomeJson
        TsConfigPkg --> TSBase
        TsConfigPkg --> TSReact
        TsConfigPkg --> TSNext
    end

    %% Build & Dev Tools
    subgraph "Build & Dev Toolchain"
        direction TB
        Turbo["Turbo CLI"]:::tool
        PNPM["pnpm workspace"]:::tool
        Vite["Vite"]:::tool
        Tailwind["Tailwind CSS"]:::tool
        Biome["Biome"]:::tool
        Turbo -->|orchestrates| WebApp
        Turbo -->|orchestrates| UI
        Turbo -->|orchestrates| Shared
        Turbo -->|orchestrates| I18n
        Turbo -->|orchestrates| BiomeConfigPkg
        Turbo -->|orchestrates| TsConfigPkg
        PNPM -->|links| UI
        PNPM -->|links| Shared
        PNPM -->|links| I18n
        Vite -->|bundles| ClientEntry
        Tailwind -->|styles| Styles
        Biome -->|lint/format| WebApp
    end

    %% External Services
    Vercel["Vercel Remote Cache"]:::external

    %% Dependencies
    WebApp -->|uses| UI
    WebApp -->|uses| Shared
    WebApp -->|uses| I18n
    WebApp -->|uses| BiomeConfigPkg
    WebApp -->|uses| TsConfigPkg
    Turbo -->|caches| Vercel

    %% Click Events
    click Orchestrator "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//turbo.json"
    click Orchestrator "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//package.json"
    click Orchestrator "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//.npmrc"
    click LintTSConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//biome.json"
    click LintTSConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//tsconfig.json"
    click WebApp "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//apps/web"
    click ClientEntry "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/app/entry.client.tsx"
    click ServerEntry "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/app/entry.server.tsx"
    click RootFile "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/app/root.tsx"
    click RoutesFolder "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//apps/web/app/routes"
    click Styles "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/app/styles.css"
    click ViteConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/vite.config.ts"
    click TailwindConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/tailwind.config.ts"
    click WebBiomeConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/biome.json"
    click WebTsConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//apps/web/tsconfig.json"
    click UI "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/ui"
    click UIComponents "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/ui/src/components"
    click UIHooks "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/ui/src/hooks"
    click UIUtils "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/ui/src/utils"
    click Storybook "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/ui/.storybook"
    click Shared "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/shared"
    click SharedFuncs "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/shared/src/functions"
    click SharedHooks "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/shared/src/hooks"
    click SharedClient "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/shared/src/client-only.tsx"
    click I18n "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/i18n"
    click I18nIndex "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/i18n/src/index.ts"
    click LinguiServer "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/i18n/src/lingui.server.ts"
    click ReactRouterServer "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/i18n/src/react-router.server.ts"
    click I18nUtils "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/i18n/src/utils.ts"
    click I18nLocales "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/i18n/locales"
    click LinguiConfig "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/i18n/lingui.config.ts"
    click BiomeConfigPkg "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/biome-config"
    click BiomeJson "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/biome-config/biome.json"
    click TsConfigPkg "https://github.com/dangvanthanh/remix-turborepo-boilerplate/tree/main//packages/typescript-config"
    click TSBase "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/typescript-config/base.json"
    click TSReact "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/typescript-config/react-library.json"
    click TSNext "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//packages/typescript-config/nextjs.json"
    click LinguiConfigRoot "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//lingui.config.ts"
    click BunLock "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//bun.lock"
    click PNPM "https://github.com/dangvanthanh/remix-turborepo-boilerplate/blob/main//package.json"

    %% Styles
    classDef root fill:#cce5ff,stroke:#004085,color:#004085
    classDef app fill:#d4edda,stroke:#155724,color:#155724
    classDef package fill:#fff3cd,stroke:#856404,color:#856404
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef tool fill:#ffe5b4,stroke:#bf5700,color:#bf5700
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
