Project Structure

Overview

Codapult follows a standard Next.js App Router layout with additional conventions for adapters, plugins, and infrastructure code.

codapult.plugins.ts           — Plugin registration config
Dockerfile                    — Production Docker image
docker-compose.yml            — Local Docker Compose setup
src/
  app/
    [locale]/                 — Locale segment (next-intl URL routing)
      (protected)/
        (dashboard)/          — Protected dashboard (settings, billing, teams, AI chat)
        (admin)/              — Admin panel (users, subscriptions, feature flags)
      (public)/
        (marketing)/          — Public pages: landing, pricing, blog, docs, plugins, legal
        (auth)/               — Sign in, sign up
        invite/[token]/       — Team invitation acceptance
      layout.tsx              — Root layout
    api/                      — API routes (auth, chat, upload, webhooks, trpc, graphql)
  components/
    ui/                       — shadcn/ui base components
    marketing/                — Landing page sections
    dashboard/                — Dashboard components (sidebar, team switcher)
    admin/                    — Admin components (tables, managers)
    auth/                     — Auth components (AuthForm)
  lib/
    db/                       — Drizzle client, schema, migrations, seed
    auth/                     — Auth adapter (Better-Auth / Kinde)
    payments/                 — Payment adapter (Stripe / LemonSqueezy / Polar)
    storage/                  — File storage adapter (local / S3 / R2)
    actions/                  — Server actions (mutations)
    trpc/                     — tRPC v11 routers
    graphql/                  — GraphQL schema + resolvers
    plugins/                  — Plugin system (types, registry, hooks)
    jobs/                     — Background job adapter (in-memory / BullMQ)
    ai/                       — AI chat, RAG pipeline, embeddings
    validation.ts             — Zod schemas (shared across all actions/routes)
    rate-limit.ts             — Sliding-window rate limiter
    guards.ts                 — Auth + permission guards
    env-utils.ts              — Env parsing helpers
  config/
    env.ts                    — Typed env var access (`env.*`)
    env-schema.ts             — Zod schema of env vars and startup validation
    app.ts                    — Brand identity and company links
    navigation.ts             — Dashboard & admin sidebar items
  i18n/
    routing.ts                — Locale list, prefix strategy (defineRouting)
    navigation.ts             — Locale-aware Link, useRouter, usePathname
    request.ts                — Server-side locale resolution
content/
  blog/                       — MDX blog posts (locale variants can use a slug.<locale>.mdx convention)
  docs/                       — MDX documentation articles
messages/                     — i18n translation files
plugins/                      — Community plugins directory
e2e/                          — Playwright E2E tests
scripts/                      — Utility scripts (seed, migrate)
infra/
  terraform/                  — AWS infrastructure (HCL)
  pulumi/                     — AWS infrastructure (TypeScript)
  helm/                       — Kubernetes Helm chart

Key Directories

src/app/ — Routes

Next.js App Router uses route groups (parenthesized folders) to organize routes without affecting URL paths:

• [locale]/ — dynamic segment that captures the active locale from the URL. Contains all user-facing routes. Managed by next-intl; the default locale (en) has no URL prefix.
• [locale]/(public)/(marketing)/ — public pages: landing, pricing, blog, changelog, legal pages, help center, feature requests, plugin pages, and comparison pages. No auth required.
• [locale]/(public)/(auth)/ — sign in and sign up pages.
• [locale]/(protected)/(dashboard)/ — all protected routes behind authentication. Includes settings, billing, team management, AI chat, onboarding, and plugin pages.
• [locale]/(protected)/(admin)/ — admin panel with its own layout. Requires role: "admin". Manages users, subscriptions, feature flags, webhooks, SSO, performance metrics, and A/B tests.
• api/ — REST and RPC endpoints (outside [locale]/). Every route follows the same pattern: auth check → rate limit → Zod validation → business logic → JSON response.

src/components/ — UI

Components are organized by domain. ui/ contains the shared shadcn/ui primitives (Button, Dialog, Table, etc.); other folders hold feature-specific components.

src/lib/ — Business Logic

Each adapter module (auth/, payments/, storage/, jobs/) contains a common interface and multiple implementations. The active implementation is selected at runtime by the corresponding env var — your application code only imports the interface.

Other modules:

• actions/ — server actions for form submissions and mutations. Each validates input with Zod and checks auth/permissions via guards.
• trpc/ — type-safe API procedures organized into routers (user, billing, notifications). Client and server setup included.
• graphql/ — optional GraphQL layer using graphql-yoga. SDL schema with resolvers.
• plugins/ — plugin registry, types, lifecycle hooks, and marketplace catalog.
• ai/ — AI chat with streaming, RAG pipeline, embedding generation, conversation history.
• jobs/ — background job system with built-in jobs (send-email, webhook-retry, credit-reset, rag-index) and cron scheduling.

src/app/[locale]/(public)/(marketing)/ — Public Marketing Surface

The marketing route group contains public, SEO-indexable pages. Customize or remove routes to match your product and the public surfaces you intend to support.

Use these surfaces when customizing. The repository includes the complete source, so the table intentionally points to stable customization boundaries rather than listing every implementation detail:

If a public surface is not part of your launch, disable it with the matching ENABLE_* env var where available, then remove its navigation links and sitemap entries.

content/ — MDX Content

Blog posts and documentation articles are MDX files with frontmatter metadata. Blog posts can support additional locales through filename conventions such as post.<locale>.mdx; the currently shipped default locale is English. The help center documentation uses category-based organization.

infra/ — Infrastructure as Code

Three deployment options are included out of the box:

• Terraform — AWS infrastructure defined in HCL
• Pulumi — AWS infrastructure defined in TypeScript
• Helm — Kubernetes chart with Deployment, Service, Ingress, HPA, worker, and Redis

Configuration Architecture

Codapult uses a three-layer config system:

1. Environment Variables (.env.local)

Secrets and per-environment settings. All variables are documented in .env.example with inline comments. Access them type-safely via src/config/env.ts:

import { env } from '@/config/env';

env.db.turso.url; // string — validated at startup
env.auth.provider; // "better-auth" | "kinde" | "none"

2. Application Config (src/config/app.ts)

Your main customization file. Controls brand identity and company metadata:

export const appConfig = {
  appName: 'my-saas',
  appUrl: 'https://my-saas.com',
  brand: {
    name: 'My SaaS',
    description: 'The best SaaS product',
    logo: '/logo.svg',
  },
  company: {
    contactEmail: 'support@my-saas.com',
  },
};

AI runtime settings and feature gates live in src/config/env.ts, not app.ts. Use ENABLE_AI_CORE for the shared AI runtime and ENABLE_AI_CHAT for the chat surface.

Feature toggles (which modules are enabled) are controlled via ENABLE_* environment variables — see env.features in src/config/env.ts.

3. Selected Supporting Config Areas

Database Schema

The database schema has provider-specific sources of truth: src/lib/db/schema.ts for SQLite/LibSQL and src/lib/db/schema-pg.ts for PostgreSQL. Keep table names and exported schema shapes aligned across both files. Conventions:

• Table names: singular snake_case (user, organization_member)
• Column names: snake_case (created_at, user_id)
• Primary keys: text('id').primaryKey() with UUID/nanoid (not auto-increment)
• Timestamps: integer('created_at', { mode: 'timestamp' }) with .$defaultFn(() => new Date())
• Foreign keys: always specify onDelete behavior

For development, run pnpm db:push to apply the schema directly. For production databases with existing data, use pnpm db:generate to create a migration, then pnpm db:migrate to apply it safely.

Next Steps

• Authentication — sign-in methods, 2FA, and SSO configuration
• Payments & Billing — configure subscription tiers
• Customization — theming, branding, and white-label