sebas5384/convex-ddd-architecture

Convex DDD Architecture

Reference skill for organizing Convex projects with DDD and Hexagonal architecture. It keeps domain logic isolated from database and external API concerns so changes remain local and safer to evolve.

When to Use

Use this skill when work includes one or more of these signals:

• New Convex sub-domain design (schema, queries, mutations, domain, adapters)
• Legacy Convex code migration toward DDD/Hexagonal boundaries
• Business rules drifting into handlers instead of aggregates
• Direct ctx.db access spreading outside repositories
• External API calls requiring retries, orchestration, or translation layers
• Team-level need for consistent file layout and naming in Convex projects
• Choosing or refactoring identifiers (variables, functions): domain nouns on exports/models; shorter names inside modules/functions where scope already disambiguates (naming.md)

Do not use this as a strict template for tiny prototypes where speed matters more than architectural boundaries.

Project Shape

./convex/
  _generated/                       # Auto-generated by Convex (do not edit)
  _shared/                          # Cross-domain utilities
    _libs/
      aggregate.ts                  # Base aggregate interface
      repository.ts                 # Base repository interface
  _triggers.ts                      # Central trigger registry
  customFunctions.ts                # Wrapped mutation/query exports
  schema.ts                         # Composed schema from all sub-domains
  [subDomainName]/                  # Each sub-domain folder (camelCase)
    _libs/
      stripeClient.ts               # Libs or helpers
    _tables.ts                      # Database schema tables
    _triggers.ts                    # Sub-domain trigger handlers
    _seeds.ts                       # Seeds for models
    _workflows.ts                   # Convex workflows
    queries/
      [queryName].ts                # One query per file, export default
    mutations/
      [mutationName].ts             # One mutation per file, export default
    domain/
      [modelName].model.ts          # Model schema, types, Aggregate
      [modelName].repository.ts     # Repository interface
    adapters/
      [actionName].action.ts        # External API actions
      [modelName].repository.ts     # Repository implementation

Naming Rules

• Files: Use camelCase (contactRepository.ts, sendInvoice.action.ts)
• Underscore prefix: For non-domain files (_tables.ts, _triggers.ts)
• Directory vs file: Start with a file (for example _workflows.ts), split into a directory after growth
• Identifiers: Domain vocabulary on exports, models, and APIs; inside functions prefer short nouns when the parent name/type already supplies context—do not repeat file or parent names on every local. Details: naming.md.

Quick Reference

| Concern | Rule | |---|---| | Convex imports | Import mutation, query, internalMutation from customFunctions.ts | | Function exports | One function per file with export default | | Domain model shape | Include _id, _creationTime, plus New<Model> without system fields via withoutSystemFields | | Persistence boundary | Access DB through repositories in adapters/ | | External integrations | Keep translation in actions; business decisions stay in mutations/aggregates | | _tables.ts | Only defineTable(NewXModel.fields) + indexes — field definitions live in domain model files, never inline | | Schema | Compose root schema from each sub-domain _tables export |

Core Patterns

1) Custom Functions Boundary

Always import mutation, query, internalMutation from customFunctions.ts, not from _generated/server. See custom-functions.md.

// ✅ Correct
import { mutation } from "../../customFunctions";

// ❌ Wrong - bypasses trigger integration
import { mutation } from "../../_generated/server";

2) API Path Convention

One function per file with named definition and default export:

// convex/combat/mutations/createBattle.ts
import { mutation } from "../../customFunctions";
import { v } from "convex/values";

const createBattle = mutation({
  args: { heroId: v.id("heroProfiles") },
  handler: async (ctx, args) => {
    // ...
  },
});

export default createBattle;

Frontend usage with .default suffix:

import { api } from "@/convex/_generated/api";
useMutation(api.combat.mutations.createBattle.default);
useQuery(api.economy.queries.getHeroProfile.default);

Avoid named exports like export const createBattle - this creates redundant paths like api.combat.mutations.createBattle.createBattle.

3) Schema Composition

Compose schema from sub-domain tables:

// convex/schema.ts
import { defineSchema } from "convex/server";
import { combatTables } from "./combat/_tables";
import { economyTables } from "./economy/_tables";

export default defineSchema({
  ...combatTables,
  ...economyTables,
});

4) Domain + Repository + Adapter Roles

• Domain models and aggregates define invariants (domain-models.md)
• Repositories isolate persistence logic (repositories.md)
• Actions adapt external DTOs and call mutations for business transitions (adapters.md)
• Triggers and workflows orchestrate reliable side effects (triggers.md)

5) Workflow and Trigger Safety

• Prefer one-way flow: UI mutation -> scheduled action/workflow -> mutation -> reactive query
• Keep trigger handlers lightweight; schedule async work when possible
• Treat trigger code as transaction-sensitive

Common Mistakes

• Overly verbose locals that restate file or function context instead of narrowing scope or extracting a smaller unit (naming.md)
• Importing handlers directly from _generated/server and bypassing shared wrappers
• Writing business rules in actions or handlers instead of aggregates
• Updating records with ad-hoc field mutations rather than aggregate transitions
• Returning raw records where aggregate behavior is expected
• Introducing required schema fields without staged migration strategy (migrations.md)
• Defining fields inline in _tables.ts instead of defineTable(NewXModel.fields) — this duplicates the schema and breaks the model-as-source-of-truth invariant
• Using an existing (possibly non-DDD) module as a reference when starting a new subdomain — always derive patterns from examples.md, not from adjacent code that may predate these guidelines

Supporting References

Supporting documents live in the references/ directory.

Read before writing any new subdomain code:

• examples.md — Complete worked examples (invoice domain, RPG game) showing the full stack: model → _tables.ts → repository interface → adapter → mutation. Start here.
• learnings.md — Hard-won rules from migrations; covers _tables.ts pitfalls, DTO placement, and incremental refactor strategy.

Read when the task touches that specific concern:

• domain-models.md — *Model validator shape, withoutSystemFields, Aggregate class structure and state transitions
• repositories.md — createRepository factory, interface conventions, method naming (by, list, with)
• adapters.md — External API adapter structure, DTO translation boundary
• triggers.md — Trigger registration, safety rules, scheduling side effects
• migrations.md — Schema change strategy, widen-migrate-narrow
• custom-functions.md — Function wrapper details and auth variants
• naming.md — Identifier conventions, ubiquitous language
• value-objects.md — Immutable value object pattern (no _id, static catalogs)
• eslint-rules.md — Enforced linting rules for import boundaries