Project Structure

CharleOS uses Next.js 16 App Router with a feature-based organization. This guide explains how the codebase is structured and where to find (or add) code.

Overview

charle-os/
├── app/                      # Next.js App Router (pages & routes)
├── components/               # React components (feature-based)
├── lib/                      # Shared utilities & business logic
├── hooks/                    # Custom React hooks
├── __tests__/                # Unit tests (Vitest)
├── e2e/                      # E2E tests (Playwright)
├── drizzle/                  # Database migrations
├── trigger/                  # Background jobs (Trigger.dev)
├── emails/                   # Email templates (React Email)
├── scripts/                  # Utility scripts
└── public/                   # Static assets

App Directory (`/app`)

The app/ directory contains all routes and pages using Next.js App Router.

Route Groups

CharleOS uses route groups to organize pages without affecting URLs:

`(dashboard)/` - Main App

The authenticated team member application:

app/(dashboard)/
├── layout.tsx               # Dashboard layout (sidebar, header)
├── page.tsx                 # Dashboard home (/dashboard)
├── clients/                 # Client management
│   ├── [id]/               # Client detail page
│   └── page.tsx            # Client list
├── tasks/                   # Task management
├── quotes/                  # Quote management
├── projects/                # Project management
├── schedule/                # Schedule & calendar
├── help-desk/               # Support tickets
├── admin/                   # Admin settings
└── ...

Key features:

Shared layout with sidebar navigation
Role-based access control
Real-time updates via Pusher

`client-portal/` - Client Portal

Separate app for clients to view their work:

app/client-portal/
├── (authenticated)/        # After sign-in
│   ├── quotes/            # View quotes
│   ├── tasks/             # View tasks
│   ├── help-desk/         # Submit tickets
│   └── roadmap/           # Project roadmap
├── sign-in/               # Client login
├── invite/                # Client invitation flow
└── layout.tsx             # Client portal layout

Separate from main app:

Different authentication (Better Auth with client context)
Different branding and navigation
Restricted to client-facing features only

`(auth)/` - Authentication Pages

Team member authentication flow:

app/(auth)/
├── auth/
│   └── route.tsx          # Better Auth API handler
├── pending-approval/       # Pending role screen
└── layout.tsx             # Minimal auth layout

`api/` - API Routes

All backend API endpoints:

app/api/
├── dashboard/              # Dashboard data
│   ├── day-rates/
│   ├── utilisation/
│   └── ...
├── clients/                # Client CRUD
├── tasks/                  # Task CRUD
├── quotes/                 # Quote CRUD
├── schedule/               # Schedule management
├── time-entries/           # Time tracking
├── admin/                  # Admin operations
└── auth/                   # Better Auth endpoints

Convention:

Each route exports GET, POST, PUT, PATCH, DELETE handlers
Use lib/services/ for business logic (keep routes thin)
Return structured responses with proper error handling

Special Files

File	Purpose
`layout.tsx`	Shared UI wrapper for child routes
`page.tsx`	Route content (actual page)
`loading.tsx`	Loading state (Suspense fallback)
`error.tsx`	Error boundary
`not-found.tsx`	404 page
`route.ts`	API endpoint handler

Components Directory (`/components`)

All React components organized by feature:

Feature-Based Organization

components/
├── ui/                      # shadcn/ui base components
│   ├── button.tsx
│   ├── input.tsx
│   ├── dialog.tsx
│   └── ...                 # 100+ UI primitives
├── tasks/                   # Task-specific components
│   ├── task-card.tsx
│   ├── task-filters.tsx
│   └── wizard/             # Task creation wizard
├── quotes/                  # Quote components
├── calendar/                # Calendar & schedule
├── dashboard/               # Dashboard widgets
├── data-table/              # Reusable table components
├── badge/                   # Status badges
├── client-portal/           # Client portal components
└── ...

Component Naming

PascalCase for components: TaskCard.tsx
Feature prefixes for clarity: TaskStatusBadge, QuoteApprovalCard
Index files for clean imports: components/tasks/index.ts

UI Components (`/components/ui`)

Base components from shadcn/ui:

Built on Radix UI primitives
Styled with Tailwind CSS
Fully customizable
Don’t edit directly - use composition

Example usage:

import { Button } from "@/components/ui/button";
import { Dialog } from "@/components/ui/dialog";

Lib Directory (`/lib`)

Shared utilities, business logic, and configuration:

Services (`/lib/services`)

Business logic layer - keeps API routes thin:

lib/services/
├── tasks.ts                 # Task operations
├── quotes.ts                # Quote operations
├── clients.ts               # Client operations
├── metrics.ts               # Metric calculations
├── billing.ts               # Billing logic
├── schedule-calculator.ts   # Schedule generation
└── ...

Pattern:

Functions accept validated input
Return typed results or throw errors
Used by API routes and server components

Example:

// lib/services/tasks.ts
export async function createTask(data: CreateTaskInput) {
  // Validate, calculate, insert
  return task;
}

// app/api/tasks/route.ts
export async function POST(req: Request) {
  const data = await req.json();
  const task = await createTask(data);
  return Response.json(task);
}

Database (`/lib/db`)

Database schema and client:

lib/db/
├── schema.ts                # Drizzle schema (all tables)
├── index.ts                 # Database client
└── doc-chunks.ts            # RAG document chunks

Key files:

schema.ts - Single source of truth for database structure
Types auto-generated from schema
All tables, relations, enums defined here

Utils (`/lib/utils`)

Utility functions grouped by purpose:

lib/utils/
├── billing.ts               # Billing formula (MIN/MAX)
├── tshirt-sizes.ts          # T-shirt size calculations
├── day-rate.ts              # Day rate calculations
├── prorated-revenue.ts      # Revenue proration
├── working-days.ts          # Working day calculations
├── date-formatting.ts       # Date utilities
└── ...

Constants (`/lib/constants`)

Configuration and constants:

lib/constants/
├── tshirt-sizes.ts          # T-shirt size definitions
├── capacity.ts              # Capacity constants
├── status.ts                # Status enums & labels
├── target-metrics.ts        # Target thresholds
└── ...

Schemas (`/lib/schemas`)

Zod validation schemas for forms and API:

lib/schemas/
├── task.ts                  # Task validation
├── quote.ts                 # Quote validation
├── client.ts                # Client validation
└── ...

Usage:

import { createTaskSchema } from "@/lib/schemas/task";

const parsed = createTaskSchema.parse(formData);

AI (`/lib/ai`)

AI features (Alan assistant):

lib/ai/
├── agents/                  # AI agents
│   ├── general.ts          # General queries
│   ├── schedule.ts         # Schedule management
│   └── instructions/       # System prompts
├── tools/                   # AI tool functions
│   ├── tasks.ts
│   ├── schedule.ts
│   └── ...
└── rag.ts                   # RAG (doc search)

Hooks Directory (`/hooks`)

Custom React hooks for data fetching and state:

hooks/
├── use-task-detail.ts       # Fetch task by ID
├── use-task-list.ts         # Fetch tasks with filters
├── use-client-detail.ts     # Fetch client by ID
└── ...

Pattern (SWR-based):

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

Tests

Unit Tests (`/tests`)

Vitest tests for utilities and logic:

__tests__/
├── billing.test.ts          # Billing formula tests
├── tshirt-sizes.test.ts     # T-shirt size calculations
├── working-days.test.ts     # Date utilities
└── ...

Run tests:

npm run test          # Run once
npm run test:watch    # Watch mode

E2E Tests (`/e2e`)

Playwright tests for critical flows:

e2e/
├── auth.spec.ts             # Authentication flow
├── tasks.spec.ts            # Task creation
├── quotes.spec.ts           # Quote workflow
└── global-setup.ts          # Test setup

Run tests:

npm run test:e2e      # Headless
npm run test:e2e:ui   # Interactive

Other Directories

Drizzle (`/drizzle`)

Database migrations (auto-generated):

drizzle/
├── 0001_initial.sql
├── 0002_add_users.sql
├── meta/                    # Migration metadata
└── ...

Don’t edit manually - generate with npm run db:generate

Trigger (`/trigger`)

Background jobs (Trigger.dev):

trigger/
├── calculate-day-rates.ts   # Daily metric calculation
├── schedule-reminders.ts    # Notification jobs
└── ...

Emails (`/emails`)

React Email templates:

emails/
├── quote-approved.tsx
├── task-assigned.tsx
└── components/
    └── layout.tsx           # Email layout

Scripts (`/scripts`)

Utility scripts:

scripts/
├── seed-dev-data.ts         # Seed development data
├── index-user-guide.ts      # Index docs for Algolia
└── ...

File Naming Conventions

Type	Convention	Example
Components	PascalCase	`TaskCard.tsx`
Utilities	kebab-case	`tshirt-sizes.ts`
Hooks	camelCase with `use` prefix	`use-task-detail.ts`
API routes	kebab-case	`route.ts` in `day-rates/`
Types	PascalCase	`TaskStatus`
Constants	SCREAMING_SNAKE_CASE	`DEFAULT_CAPACITY`

Code Organization Principles

1. Colocation

Keep related code close together:

Task components in components/tasks/
Task services in lib/services/tasks.ts
Task schemas in lib/schemas/task.ts
Task API in app/api/tasks/

2. Feature-Based Structure

Organize by feature, not by type: ✅ Good:

components/
├── tasks/
│   ├── task-card.tsx
│   ├── task-filters.tsx
│   └── task-wizard.tsx

❌ Bad:

components/
├── cards/
│   └── task-card.tsx
├── filters/
│   └── task-filters.tsx
└── wizards/
    └── task-wizard.tsx

3. Shared vs Feature Code

Shared code → lib/, components/ui/, hooks/
Feature code → Feature-specific directories

4. Thin Routes, Fat Services

API routes should be thin wrappers:

// ✅ Good: Thin route, logic in service
export async function POST(req: Request) {
  const data = await req.json();
  const task = await taskService.create(data);
  return Response.json(task);
}

// ❌ Bad: Business logic in route
export async function POST(req: Request) {
  // 100 lines of validation, calculation, database queries...
}

Adding New Features

When adding a new feature, follow this structure:

Create Database Schema

Add tables to lib/db/schema.ts and run npm run db:push

Add Service Layer

Create lib/services/your-feature.ts with business logic

Create API Routes

Add routes in app/api/your-feature/route.ts

Build Components

Add components in components/your-feature/

Create Hooks

Add hooks/use-your-feature.ts for data fetching

Add Pages

Create pages in app/(dashboard)/your-feature/

Import Paths

CharleOS uses path aliases for clean imports:

// ✅ Good: Path aliases
import { Button } from "@/components/ui/button";
import { createTask } from "@/lib/services/tasks";
import { useTaskDetail } from "@/hooks/use-task-detail";

// ❌ Bad: Relative paths
import { Button } from "../../../components/ui/button";

Configured in tsconfig.json:

@/* → Root directory
@/components/* → Components
@/lib/* → Library code

Local Setup

Set up your development environment

Database

Working with the database schema

Authentication

How auth is structured

Testing

Writing and running tests

Getting Started

Database

Authentication

Testing

Deployment

​Overview

​App Directory (/app)

​Route Groups

​(dashboard)/ - Main App

​client-portal/ - Client Portal

​(auth)/ - Authentication Pages

​api/ - API Routes

​Special Files

​Components Directory (/components)

​Feature-Based Organization

​Component Naming

​UI Components (/components/ui)

​Lib Directory (/lib)

​Services (/lib/services)

​Database (/lib/db)

​Utils (/lib/utils)

​Constants (/lib/constants)

​Schemas (/lib/schemas)

​AI (/lib/ai)

​Hooks Directory (/hooks)

​Tests

​Unit Tests (/__tests__)

​E2E Tests (/e2e)

​Other Directories

​Drizzle (/drizzle)

​Trigger (/trigger)

​Emails (/emails)

​Scripts (/scripts)

​File Naming Conventions

​Code Organization Principles

​1. Colocation

​2. Feature-Based Structure

​3. Shared vs Feature Code

​4. Thin Routes, Fat Services

​Adding New Features

​Import Paths

​Related Documentation

Local Setup

Database

Authentication

Testing

Overview

App Directory (`/app`)

Route Groups

`(dashboard)/` - Main App

`client-portal/` - Client Portal

`(auth)/` - Authentication Pages

`api/` - API Routes

Special Files

Components Directory (`/components`)

Feature-Based Organization

Component Naming

UI Components (`/components/ui`)

Lib Directory (`/lib`)

Services (`/lib/services`)

Database (`/lib/db`)

Utils (`/lib/utils`)

Constants (`/lib/constants`)

Schemas (`/lib/schemas`)

AI (`/lib/ai`)

Hooks Directory (`/hooks`)

Tests

Unit Tests (`/tests`)

E2E Tests (`/e2e`)

Other Directories

Drizzle (`/drizzle`)

Trigger (`/trigger`)

Emails (`/emails`)

Scripts (`/scripts`)

File Naming Conventions

Code Organization Principles

1. Colocation

2. Feature-Based Structure

3. Shared vs Feature Code

4. Thin Routes, Fat Services

Adding New Features

Import Paths

Related Documentation