Overview - CharleOS

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:

Prerequisites

Ensure you have Node.js 18+, npm, and Git installed

Clone & Install

git clone https://github.com/charle-agency/charle-os.git
cd charle-os
npm install

Environment Setup

The .env.local file is already in the repository - no need to pull from Vercel

Run Development Server

npm run dev

Open http://localhost:3000

See 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:

Next.js 16

Framework

App Router architecture
React 19
TypeScript throughout
Server components by default

Better Auth

Authentication

Google OAuth integration
Session management
Role-based permissions
Client portal access

PostgreSQL + Drizzle

Database

Type-safe ORM with Drizzle
Hosted on Neon (serverless)
Schema-first migrations
Drizzle Studio for browsing

Tailwind + shadcn/ui

Styling

Utility-first CSS
Pre-built components
Dark mode support
Responsive by default

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:

Local Development
Database Changes
Testing

Day-to-day development

Pull latest changes from main
Create a feature branch
Make changes and test locally
Run linters and tests
Push branch and create PR
Deploy preview automatically on Vercel

Schema modifications

Update schema in lib/db/schema.ts
Push changes locally: npm run db:push
Test changes with Drizzle Studio
Generate migration for production: npm run db:generate
Commit schema + migration files
Migrations run automatically on deploy

Quality assuranceUnit Tests (Vitest):

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

E2E Tests (Playwright):

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

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 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:

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
`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 - Detailed setup instructions
Project Structure - Codebase organization
Environment Variables - Configuration reference
Database - Working with Drizzle and PostgreSQL
Authentication - 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:

CORS Error on Sign In

Symptom: Error mentioning https://charle.agency when signing in locallyCause: Auth URLs in .env.local are pointing to productionFix: Update .env.local:

BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000"

Database Connection Error

Symptom: Can’t connect to databasePossible 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

Pending Role After Sign In

Module Not Found

Symptom: Import errors or missing modulesFix:

# Clear cache and reinstall
rm -rf node_modules .next
npm install

Next Steps

Local Setup

Follow the step-by-step guide to set up your local environment

Project Structure

Understand how the codebase is organized

Environment Variables

Learn about all configuration options

Database

Working with Drizzle ORM and PostgreSQL

Getting Started

Database

Authentication

Testing

Deployment

​Quick Start

​Tech Stack

Next.js 16

Better Auth

PostgreSQL + Drizzle

Tailwind + shadcn/ui

​Full Stack

​Development Workflow

​Project Structure

​Key Concepts

​App Router Architecture

​Server vs Client Components

​Data Fetching with SWR

​Type Safety

​Available Scripts

​Getting Help

​Documentation

​Internal Resources

​Troubleshooting

​Next Steps

Local Setup

Project Structure

Environment Variables

Database

Quick Start

Tech Stack

Full Stack

Development Workflow

Project Structure

Key Concepts

App Router Architecture

Server vs Client Components

Data Fetching with SWR

Type Safety

Available Scripts

Getting Help

Documentation

Internal Resources

Troubleshooting

Next Steps