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

# Overview

> Getting started with CharleOS development

CharleOS is an agency management system built with modern web technologies. This guide will help you set up your development environment and understand the codebase structure.

## Quick Start

Get up and running in minutes:

<Steps>
  <Step title="Prerequisites">
    Ensure you have Node.js 18+, npm, and Git installed
  </Step>

  <Step title="Clone & Install">
    ```bash theme={null}
    git clone https://github.com/charle-agency/charle-os.git
    cd charle-os
    npm install
    ```
  </Step>

  <Step title="Environment Setup">
    The `.env.local` file is already in the repository - no need to pull from Vercel
  </Step>

  <Step title="Run Development Server">
    ```bash theme={null}
    npm run dev
    ```

    Open [http://localhost:3000](http://localhost:3000)
  </Step>
</Steps>

See [Local Setup](/developer/getting-started/local-setup) for detailed step-by-step instructions.

## Tech Stack

CharleOS is built with a modern, type-safe stack optimized for developer experience and performance:

<CardGroup cols={2}>
  <Card title="Next.js 16" icon="react">
    **Framework**

    * App Router architecture
    * React 19
    * TypeScript throughout
    * Server components by default
  </Card>

  <Card title="Better Auth" icon="lock">
    **Authentication**

    * Google OAuth integration
    * Session management
    * Role-based permissions
    * Client portal access
  </Card>

  <Card title="PostgreSQL + Drizzle" icon="database">
    **Database**

    * Type-safe ORM with Drizzle
    * Hosted on Neon (serverless)
    * Schema-first migrations
    * Drizzle Studio for browsing
  </Card>

  <Card title="Tailwind + shadcn/ui" icon="paintbrush">
    **Styling**

    * Utility-first CSS
    * Pre-built components
    * Dark mode support
    * Responsive by default
  </Card>
</CardGroup>

### Full Stack

* **Framework**: Next.js 16 (App Router)
* **Language**: TypeScript 5
* **Database**: PostgreSQL with Drizzle ORM
* **Auth**: Better Auth (Google OAuth)
* **Styling**: Tailwind CSS 4 + shadcn/ui
* **State Management**: SWR for data fetching
* **Forms**: React Hook Form + Zod validation
* **Testing**: Vitest (unit) + Playwright (E2E)
* **Deployment**: Vercel
* **Monitoring**: Sentry
* **Search**: Algolia

## Development Workflow

CharleOS follows a structured development process:

<Tabs>
  <Tab title="Local Development">
    **Day-to-day development**

    1. Pull latest changes from `main`
    2. Create a feature branch
    3. Make changes and test locally
    4. Run linters and tests
    5. Push branch and create PR
    6. Deploy preview automatically on Vercel
  </Tab>

  <Tab title="Database Changes">
    **Schema modifications**

    1. Update schema in `lib/db/schema.ts`
    2. Push changes locally: `npm run db:push`
    3. Test changes with Drizzle Studio
    4. Generate migration for production: `npm run db:generate`
    5. Commit schema + migration files
    6. Migrations run automatically on deploy
  </Tab>

  <Tab title="Testing">
    **Quality assurance**

    **Unit Tests** (Vitest):

    ```bash theme={null}
    npm run test           # Run once
    npm run test:watch     # Watch mode
    npm run test:coverage  # With coverage
    ```

    **E2E Tests** (Playwright):

    ```bash theme={null}
    npm run test:e2e       # Headless
    npm run test:e2e:ui    # Interactive UI
    ```
  </Tab>
</Tabs>

## Project Structure

CharleOS uses Next.js App Router with feature-based organization:

```
charle-os/
├── app/                      # Next.js App Router
│   ├── (dashboard)/         # Main app (authenticated)
│   ├── client-portal/       # Client-facing portal
│   ├── (auth)/              # Auth pages (sign-in, etc.)
│   └── api/                 # API routes
├── components/              # React components
│   ├── ui/                  # shadcn/ui base components
│   ├── tasks/               # Task-related components
│   ├── quotes/              # Quote-related components
│   └── ...                  # Feature-based organization
├── lib/                     # Shared utilities
│   ├── db/                  # Database schema & queries
│   │   ├── schema.ts        # Drizzle schema
│   │   └── index.ts         # Database client
│   ├── services/            # Business logic services
│   ├── utils/               # Utility functions
│   └── constants/           # App constants
├── hooks/                   # Custom React hooks
├── __tests__/               # Unit tests (Vitest)
├── e2e/                     # E2E tests (Playwright)
└── drizzle/                 # Database migrations
```

See [Project Structure](/developer/getting-started/project-structure) for detailed explanation.

## Key Concepts

### App Router Architecture

CharleOS uses Next.js App Router with route groups:

* **`(dashboard)/`** - Main authenticated app for team members
* **`client-portal/`** - Client-facing portal (separate auth context)
* **`(auth)/`** - Authentication pages (sign-in, callbacks)
* **`api/`** - API routes for data fetching and mutations

### Server vs Client Components

By default, components are Server Components for better performance:

* **Server Components**: Data fetching, static content, no interactivity
* **Client Components**: Forms, interactivity, browser APIs
* Mark with `"use client"` only when needed

### Data Fetching with SWR

CharleOS uses SWR for client-side data fetching:

```typescript theme={null}
import useSWR from 'swr';

export function useTaskDetail(id: string) {
  return useSWR(`/api/tasks/${id}`, fetcher);
}
```

**Benefits:**

* Automatic caching and revalidation
* Optimistic updates
* Error handling
* Loading states

### Type Safety

Everything is typed with TypeScript:

* **Database schema** → Drizzle generates types
* **API routes** → Request/response types
* **Components** → Props interfaces
* **Forms** → Zod schemas for validation

## Available Scripts

Common commands you'll use during development:

| Command               | Description                                                                |
| --------------------- | -------------------------------------------------------------------------- |
| `npm run dev`         | Start development server at [http://localhost:3000](http://localhost:3000) |
| `npm run build`       | Build production bundle                                                    |
| `npm run lint`        | Run ESLint                                                                 |
| `npm run type-check`  | Run TypeScript compiler (no emit)                                          |
| `npm run test`        | Run unit tests                                                             |
| `npm run test:e2e`    | Run E2E tests                                                              |
| `npm run db:push`     | Push schema changes to database (local dev)                                |
| `npm run db:generate` | Generate migration file (for production)                                   |
| `npm run db:studio`   | Open Drizzle Studio (visual DB browser)                                    |
| `npm run db:seed`     | Seed development data                                                      |

See `package.json` for the full list of scripts.

## Getting Help

### Documentation

* [Local Setup](/developer/getting-started/local-setup) - Detailed setup instructions
* [Project Structure](/developer/getting-started/project-structure) - Codebase organization
* [Environment Variables](/developer/getting-started/environment) - Configuration reference
* [Database](/developer/database) - Working with Drizzle and PostgreSQL
* [Authentication](/developer/auth) - Better Auth setup and permissions

### Internal Resources

* **Internal Docs** - Check `docs/developer/` for technical documentation
* **Code Comments** - Complex logic is documented inline
* **Type Definitions** - Let TypeScript guide you

### Troubleshooting

Common issues and solutions:

<AccordionGroup>
  <Accordion title="CORS Error on Sign In" icon="triangle-exclamation">
    **Symptom:** Error mentioning `https://charle.agency` when signing in locally

    **Cause:** Auth URLs in `.env.local` are pointing to production

    **Fix:** Update `.env.local`:

    ```bash theme={null}
    BETTER_AUTH_URL="http://localhost:3000"
    NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000"
    ```
  </Accordion>

  <Accordion title="Database Connection Error" icon="database">
    **Symptom:** Can't connect to database

    **Possible causes:**

    * `DATABASE_URL` not set in `.env.local`
    * VPN interfering with connection
    * Need to re-pull env vars from Vercel

    **Fix:** Run `vercel env pull .env.local` to get latest credentials
  </Accordion>

  <Accordion title="Pending Role After Sign In" icon="user">
    **Symptom:** Can sign in but see "Pending Approval" message

    **Cause:** New accounts start with `pending` role

    **Fix:** Ask an admin to update your role in the database
  </Accordion>

  <Accordion title="Module Not Found" icon="cube">
    **Symptom:** Import errors or missing modules

    **Fix:**

    ```bash theme={null}
    # Clear cache and reinstall
    rm -rf node_modules .next
    npm install
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Local Setup" icon="rocket" href="/developer/getting-started/local-setup">
    Follow the step-by-step guide to set up your local environment
  </Card>

  <Card title="Project Structure" icon="folder-tree" href="/developer/getting-started/project-structure">
    Understand how the codebase is organized
  </Card>

  <Card title="Environment Variables" icon="key" href="/developer/getting-started/environment">
    Learn about all configuration options
  </Card>

  <Card title="Database" icon="database" href="/developer/database">
    Working with Drizzle ORM and PostgreSQL
  </Card>
</CardGroup>