> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builderbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> The Builder Box follows a modular, scalable architecture designed for maintainability and rapid development. This document outlines the key architectural decisions and patterns used throughout the project.

## Monorepo Structure

```
apps/
├── web/           # Next.js frontend application
├── server/        # Backend server with tRPC + Hono
├── cms/          # Headless CMS
└── email/        # Email service
```

## Web Application Structure

The web application (`apps/web`) follows a feature-based architecture:

```
src/
├── app/              # Next.js App Router pages
├── components/       # Reusable UI components
├── features/         # Feature-specific components and logic
├── hooks/           # Custom React hooks
├── layouts/         # Next.js layouts
├── lib/             # Core utilities and configurations
├── services/        # API and external service integrations
├── stores/          # State management
├── styles/          # Global styles and Tailwind config
├── types/           # TypeScript type definitions
└── utils/           # Helper functions and utilities
```

### Key Directories

#### `app/`

* Contains all Next.js pages and layouts
* Follows the App Router convention
* Includes route handlers and API endpoints

#### `components/`

* Shared UI components
* Organized by type (ui, layout, forms, etc.)
* Includes shadcn/ui components

#### `features/`

* Feature-specific components and logic
* Each feature is self-contained
* Includes business logic and UI components

#### `services/`

* API client configurations
* External service integrations
* tRPC client setup

## Server Structure

The server application (`apps/server`) follows a clean architecture pattern:

```
src/
├── controllers/     # Request handlers
├── lib/            # Core utilities
├── routers/        # tRPC routers
├── services/       # Business logic
└── utils/          # Helper functions
```

### Key Components

#### `controllers/`

* Business logic implementation
* Handles incoming requests
* Input validation
* Response formatting

#### `routers/`

* tRPC router definitions
* API endpoint organization
* Middleware configuration

#### `services/`

* Database operations
* External service integrations

## CMS Architecture

The CMS (`apps/cms`) is powered by Payload CMS and is structured for extensibility and integration with the rest of the monorepo. Only the essential structure is shown below:

```
apps/cms/
├── src/
│   ├── collections/      # Collection definitions (Posts, Media, Users, etc.)
│   └── payload.config.ts # Main Payload CMS configuration
```

* `collections/`: Contains all collection schemas for Payload (e.g., Posts, Media, Users, Privacy).
* `payload.config.ts`: The entry point for configuring Payload CMS, plugins, adapters, and collections.

> For detailed configuration and customization, refer to the [Payload CMS documentation](https://payloadcms.com/).

## Database Architecture

The project uses Prisma with Supabase (PostgreSQL):

```
prisma/
├── schema.prisma    # Database schema
└── migrations/      # Database migrations
```

## Authentication Flow

The authentication system uses BetterAuth:

1. User initiates auth (email, OAuth)
2. BetterAuth handles the flow
3. Session is created and stored
4. User metadata is synced to database

## API Architecture

The API layer uses tRPC for type-safe communication:

1. Frontend makes type-safe API calls
2. tRPC router processes the request
3. Controller handles the business logic
4. Response is returned to the client

## State Management

* React Context for global state
* Server state handled by tRPC

## Styling Architecture

* Tailwind CSS for utility-first styling
* shadcn/ui for component library
* CSS Modules for component-specific styles
* Dark mode support built-in