# better-t-stack/create-better-t-stack architecture

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

- Interactive diagram: https://gitdiagram.com/better-t-stack/create-better-t-stack
- Repository: https://github.com/better-t-stack/create-better-t-stack

## Overview

The project “Better-T-Stack” is a monorepo that provides a modern CLI tool for scaffolding end-to-end type-safe TypeScript projects. Its primary purpose is to generate new projects with best practices in place, including integration of type safety across database, backend, and frontend components using technologies such as tRPC, React, and various backend frameworks. There are also templates for multiple configurations (with authentication, different ORMs, and even mobile/desktop specifics with Tauri, Expo, and more) and a documentation website.

##### Main Components
- CLI Tool (Scaffolding Engine): Located in apps/cli. This layer handles interactive prompts, configuration management, dependency installation, and project generation based on templates.
- Template Engine & Templates: The CLI tool uses a rich directory tree under apps/cli/template, which includes:
- Base templates for standard projects
- Specialized templates (with-auth, with-drizzle-postgres/sqlite, with-prisma, with-husky, etc.)
- Examples (such as the “todo” example)
These components are crucial to show how new projects are generated with varying configurations.
- Documentation Website: Found in apps/web, this is the public-facing website offering guides, documentation, and additional information about the scaffolded projects.
- Monorepo & Build Tools: The project is structured as a monorepo and uses Turborepo (turbo.json) to manage its packages. This infrastructure is a key part of the overall architecture.

##### Relationships and Interactions
- User initiates the CLI (via npx, bun, or pnpm) which then runs the scaffolding process.
- Interactive Prompts: The CLI launches a set of prompts (located in apps/cli/src/prompts) to gather user input (e.g., project name, backend framework, database, authentication options).
- Helper Functions: Based in apps/cli/src/helpers and apps/cli/src/utils, these modules process the configuration and orchestrate the project generation.
- Template Selection and Rendering: Depending on the user’s selections, the CLI invokes the appropriate template from apps/cli/template (or apps/cli/template/examples) and copies & customizes files to scaffold the new project.
- External Integration: The scaffolding process sets up projects that include configuration for external libraries and frameworks (e.g., tRPC, Drizzle, Prisma, Hono/Elysia, Tailwind, etc).

##### Architectural Patterns and Design Principles
- Modular Design: Separating responsibilities into prompts, helpers, utils, and templates ensures each module is independently testable and maintainable.
- Monorepo Organization: The project uses a monorepo pattern with Turborepo for consistency and coordinated development of multiple packages (CLI tool, documentation, etc.).
- Customizability and Extensibility: The template engine is designed to support multiple variants (authentication, database options, etc.), highlighting extensibility.

##### Relevant Technologies and Frameworks
- TypeScript for end-to-end type safety.
- Node.js runtime (run with npm, bun, or pnpm).
- CLI frameworks and libraries for interactive command-line prompts.
- Turborepo for managing the monorepo.
- Frontend technologies (React, Next.js-like folder structure for apps/web).
- Multiple backend styles with tRPC integration, and technology-specific configurations (e.g., for mobile native apps, desktop apps using Tauri).

##### Essential Architectural Elements
- Detail the interactions: for instance, show how the CLI invokes helper functions which in turn interact with specific template directories to tailor the project output based on user choices.

## Diagram (Mermaid)

```mermaid
graph TD
    M["Monorepo & Build Tools"]:::build
    CLI["CLI Tool (Scaffolding Engine)"]:::cli
    TE["Template Engine & Templates"]:::template
    DW["Documentation Website"]:::docs
    GP["Generated Type-Safe Project"]:::process
    UI["User/CLI Invocation"]:::process

    subgraph "CLI Components"
        CP["Interactive Prompts"]:::cli
        HF["Helper Functions"]:::cli
        UT["Utils"]:::cli
        CM["Configuration Manager"]:::cli
        TR["Template Rendering/Project Generation"]:::process
    end

    subgraph "Template Details"
        BT["Base Templates"]:::template
        ST["Specialized Templates"]:::template
        EX["Examples"]:::template
        EI["External Integrations (tRPC,React,Drizzle,Prisma,Tauri)"]:::process
    end

    M --> CLI
    M --> DW

    UI --> CP
    CP --> HF
    HF --> UT
    UT --> CM
    CM --> TR
    TR --> TE
    TE --> BT
    TE --> ST
    TE --> EX
    BT --> EI
    ST --> EI
    EX --> EI
    EI --> GP

    click M "https://github.com/better-t-stack/create-better-t-stack/blob/main/turbo.json"
    click CLI "https://github.com/better-t-stack/create-better-t-stack/tree/main/apps/cli"
    click CP "https://github.com/better-t-stack/create-better-t-stack/tree/main/apps/cli/src/prompts"
    click HF "https://github.com/better-t-stack/create-better-t-stack/tree/main/apps/cli/src/helpers"
    click UT "https://github.com/better-t-stack/create-better-t-stack/tree/main/apps/cli/src/utils"
    click TE "https://github.com/better-t-stack/create-better-t-stack/tree/main/apps/cli/template"
    click DW "https://github.com/better-t-stack/create-better-t-stack/tree/main/apps/web"

    classDef cli fill:#f9d5e5,stroke:#333,stroke-width:2px;
    classDef template fill:#d5f9e5,stroke:#333,stroke-width:2px;
    classDef docs fill:#e5d5f9,stroke:#333,stroke-width:2px;
    classDef process fill:#f9f9d5,stroke:#333,stroke-width:2px;
    classDef build fill:#d5e5f9,stroke:#333,stroke-width:2px;
```
