Module Architecture

Design Principles

Every feature in Codapult is packaged as a self-contained module with its own directories, routes, components, and database tables. Modules follow three rules:

1. Independent — each module lives in its own directories and can be deleted without breaking other modules.
2. Core-dependent only — modules depend on the Core layer (Auth, Database, Rate Limiting, Validation), not on each other, unless explicitly noted.
3. CLI-removable — the interactive setup wizard can strip modules automatically.

Module Map

Removal vs. Disabling: Two Different Operations

Codapult has two separate ways to exclude a module from your product. Understanding the difference before setup matters.

Removing a module (CLI or manual, permanent): The module's code is deleted from your repository — files, routes, components, database tables, and imports. The build gets smaller and the codebase stays clean. Removing a module via the CLI wizard cannot be undone through the CLI. If you need the module back later, you add it manually from the Codapult source repository.

Disabling a module (env var, reversible): If a module is present in the codebase but you are not ready to use it, you can hide it via an environment variable. The code stays in the repo; the feature is invisible to users. Flip the variable to re-enable it at any time, with no code changes.

Practical rule: Remove modules you are confident are outside your product's scope. Keep modules you are unsure about — disable them via env var until you need them. The cost of keeping code you do not use yet is low. The cost of manually re-adding removed code is not.

How to Remove a Module

CLI Wizard (Recommended)

Run the interactive setup wizard and deselect the modules you don't need:

npx @codapult/cli setup

The wizard automatically deletes files, removes imports, cleans up navigation, and updates the schema.

This is permanent. The wizard deletes files, imports, and schema tables — it doesn't just hide them. If you're not sure whether you'll need a module later, don't remove it here. Leave it in and turn it off with the matching ENABLE_* environment variable instead (see the Module Map below or Environment Variables) — that's reversible, the CLI removal isn't.

Manual Removal

For finer control, remove a module by hand:

1. Delete the module's directories (see the table above).
2. Remove all imports referencing the deleted module.
3. Remove database tables from src/lib/db/schema.ts and regenerate migrations.
4. Remove navigation links from src/config/navigation.ts, Sidebar.tsx, admin layout, and marketing navbar.
5. Uninstall npm dependencies unique to the module.
6. Remove environment variables from .env.example.

Example: Removing AI Chat

# Delete files
rm -rf src/app/\\[locale\\]/\(dashboard\)/dashboard/ai-chat
rm -rf src/app/api/chat
rm -rf src/components/ai

# Remove the AI Chat nav item from Sidebar.tsx
# Edit src/components/dashboard/Sidebar.tsx

# Uninstall dependencies (if not used elsewhere)
pnpm remove @ai-sdk/openai @ai-sdk/anthropic ai @ai-sdk/react

# Remove env vars from .env.example:
# OPENAI_API_KEY, ANTHROPIC_API_KEY, EMBEDDING_PROVIDER,
# VECTOR_STORE_PROVIDER, OLLAMA_BASE_URL, OLLAMA_EMBEDDING_MODEL

Example: Removing Teams

# Delete files
rm -rf src/app/\\[locale\\]/\(dashboard\)/dashboard/teams
rm -rf src/app/\\[locale\\]/invite
rm src/components/dashboard/TeamSwitcher.tsx
rm src/components/dashboard/TeamSettings.tsx
rm src/components/dashboard/AcceptInvitationButton.tsx
rm src/lib/db/organizations.ts
rm src/lib/actions/organizations.ts

# Remove organization tables from src/lib/db/schema.ts:
# organization, organization_member, organization_invitation

# Remove TeamSwitcher from Sidebar.tsx

# Regenerate migrations
pnpm run db:generate

Dependency Boundaries

Modules form a layered dependency graph. The Core layer is required; everything above it is optional and independently removable.

┌───────────────────────────────────────────────┐
│                 Core Layer                    │
│  (Auth, Database, Rate Limiting, Validation)  │
└─────────────────────┬─────────────────────────┘
                      │
         ┌────────────┼────────────┐
         │            │            │
    ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
    │ Billing │  │  Teams  │  │  Admin  │
    └─────────┘  └─────────┘  └─────────┘
         │            │            │
    ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
    │ Usage   │  │  RBAC   │  │ Feature │
    │ Credits │  │         │  │  Flags  │
    └─────────┘  └─────────┘  └─────────┘

Modules only depend on the Core layer. They do not depend on each other unless explicitly noted in the Dependencies column (for example, SCIM Provisioning depends on Teams, and Chat Memory depends on AI Chat).