Convex Data Patterns

Convex est le backend applicatif d'Audit Pro 2IF. Les lectures et écritures de données passent par les queries, mutations et actions Convex afin que l'authentification, les accès par organisation et les mises à jour temps réel restent centralisés.

Model Data In Convex

Define tables and indexes in convex/schema.ts:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  projects: defineTable({
    organizationId: v.string(),
    name: v.string(),
    status: v.union(v.literal("draft"), v.literal("active")),
  }).index("by_organization", ["organizationId"]),
});

Query With Indexes

Use indexes for reads that target a subset of data:

const projects = await ctx.db
  .query("projects")
  .withIndex("by_organization", (q) =>
    q.eq("organizationId", args.organizationId),
  )
  .collect();

Keep Writes In Mutations

Mutations should own app data changes:

await ctx.db.insert("projects", {
  organizationId: args.organizationId,
  name: args.name,
  status: "draft",
});

Use Actions For External Services

Use actions when the function needs to call external services such as Stripe, Resend, or Cloudflare R2. Keep the database update in a mutation when possible, and call that mutation from the action after the external request succeeds.

Practical Tips

• Put organization-scoped functions behind the shared org builders.
• Keep public API routes thin and call Convex for app data.
• Store backend secrets in Convex env.
• Add indexes before introducing new query access patterns.
• Return DTOs from shared mappers when the same shape is used in multiple places.