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)
      (marketing)/    — Public pages: landing, pricing, blog, docs, plugins, legal
      (auth)/         — Sign in, sign up
      (dashboard)/    — Protected dashboard (settings, billing, teams, AI chat)
      admin/          — Admin panel (users, subscriptions, feature flags)
      invite/[token]/ — Team invitation acceptance
      layout.tsx      — Root layout with locale provider
    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
    config.ts         — Typed env var access (`env.*`), Zod startup validation
    env-utils.ts      — Env parsing helpers
  config/
    app.ts            — Brand identity, static AI settings, and company links
    navigation.ts     — Dashboard & admin sidebar items
    marketing.ts      — Client-safe landing content (stats, modules, testimonials)
    marketing-pricing.ts — Server-side pricing, checkout links, plugin cards
    competitor-comparison.ts — Compare and vs page data
  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 (i18n: slug.mdx, slug.ru.mdx, slug.de.mdx, …)
  docs/               — MDX documentation articles
messages/             — i18n translation files (en, ru, de, fr, ja)
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]/(marketing)/ — public pages: landing, pricing, blog, changelog, legal pages, help center, feature requests, plugin pages, and comparison pages. No auth required.
• [locale]/(auth)/ — sign in and sign up pages.
• [locale]/(dashboard)/ — all protected routes behind authentication. Includes settings, billing, team management, AI chat, onboarding, and plugin pages.
• [locale]/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]/(marketing)/ — Public Marketing Surface

The marketing route group is intentionally public and SEO-indexable. It includes the default Codapult sales site so you can see a complete working product page, but that copy is not generic placeholder text. Before shipping your SaaS, replace the Codapult-specific pages and content with your own product's positioning.

Use this map when customizing:

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 support i18n via filename convention (post.mdx for default locale, post.de.mdx for German, etc.). 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/lib/config.ts:

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

env.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, ai settings:

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: {
    ragEnabled: false,
  },
};

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

3. Supporting Config Files

Database Schema

The database schema lives in a single file: src/lib/db/schema.ts. This is the source of truth for all tables. 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