sea.dev monorepo

This is a pnpm monorepo, with a few bits of Python on the side.

Getting started

Docker needs to be running

You will need Node installed. Then you can install pnpm

npm install -g pnpm

Here are some of the main commands you will need:

# after adding dependencies
pnpm install

# run format on _all_ packages
pnpm run -r fmt

# lint only the main app
pnpm run --filter @sea/main lint

# fmt, lint, check, test all packages
pnpm run -r all

# build all dependencies of the apps
pnpm run --filter "{apps/**}^..." build

# run the main app
pnpm run --filter @sea/main dev

# or cd apps/main and then
pnpm run dev

Monorepo Structure

This is a pnpm workspace monorepo organized into applications and shared libraries.

Applications (apps/)

• main - Main React web application (TanStack Start)
• api - REST API service (Fastify)
• workers - Hatchet async workers for background jobs
• conversion-worker - Document conversion worker
• posthog-proxy - PostHog analytics proxy

Shared Libraries (libs/)

Core Packages:

• db - Database schema & migrations (Drizzle ORM)
• schemas - Zod schemas & TypeScript types for API and database
• dal - Data Access Layer (database queries and CRUD operations)
• core - Core business logic (data extraction, chat, workflows)
• ai - AI/LLM integration (agents, tools, prompts)

Infrastructure & Utilities:

• clients - External service clients (Azure, GCP, Hatchet)
• cache - Caching utilities (Upstash Redis)
• config - Shared configuration
• util - Utility functions
• validators - Validation logic

UI & Presentation:

• ui - React UI components (shadcn/ui)
• widget - Embeddable widget (React)
• widget-ng - Angular widget (separate codebase)

Development:

• lint - Shared ESLint/Prettier configuration

Package Dependency Flow

┌─────────────┐
│    apps/    │  Applications consume all libraries
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  @sea/core, @sea/ai (Business Logic)    │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  @sea/dal (Data Access Layer)           │
└──────┬──────────────────────────────────┘
       │
       ▼
┌──────┬──────────────────────────────────┐
│  @sea/db (Database Schema)              │
│  @sea/schemas (Types & Validation)      │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  @sea/util, @sea/config (Foundation)    │
└─────────────────────────────────────────┘

Key Principles:

• Schemas and types live in @sea/schemas
• Database definitions live in @sea/db
• Database queries live in @sea/dal
• Business logic lives in @sea/core or @sea/ai
• UI components are in @sea/ui (reusable) or app-specific folders

For AI Assistants: See CLAUDE.md for detailed development guidelines including package responsibilities, type placement, and coding standards.

See /apps/main/README.md for detailed setup and development instructions for the React app.

Environment Variables

The project requires several environment variables to be set in a .env file at the root of the project. Key variables include:

Required for Core Functionality

• DATABASE_URL - PostgreSQL connection string
• BETTER_AUTH_SECRET - Secret for authentication
• OPENAI_API_KEY - OpenAI API key for LLM features

Analytics (PostHog)

• POSTHOG_URL - PostHog API host (e.g., https://app.posthog.com or https://eu.posthog.com)
• POSTHOG_KEY - PostHog project API key

See the main .env file for a full list of required variables. The .env file is gitignored for security.