Skip to content
AntFabric Corev1.0.0local

Conventions

A short list, because each item is enforced somewhere or costs real time when skipped.

  • TypeScript, strict. noUncheckedIndexedAccess and exactOptionalPropertyTypes are on: check index access, and leave optional keys out rather than setting them to undefined.
  • Formatting is Prettier, run by the pre-commit hook on staged files. Do not hand-format.
  • Imports follow the dependency rule. A plugin imports @antfabric/* libraries and other plugins’ contracts packages, nothing else.
  • Controller → service → repository. Controllers map HTTP; services hold the rules; repositories are the only code that runs queries.
  • Check access in the service, on every call. Screens hide what you may not do; the server is what refuses it. Someone who may not see a record gets “not found”, not “forbidden”.
  • SQL first. Write the migration, apply it, then update the Drizzle schema. Never generate migrations from the schema.
  • Migrations are append-only. Never edit one that has been applied; write the next one. The runner refuses an edited migration.
  • A plugin’s tables live in its own schema, reached as its own database role. No foreign keys into core or other plugins; people are referenced by user id.
  • Plugin routes live under /api/v1/plugins/<plugin id>; every route has @Permissions(...) or a deliberate @Public().
  • DTOs use class-validator; unknown properties are rejected.
  • After changing a controller or DTO run pnpm api:spec and commit openapi.json and the generated client. CI fails when they are stale.
  • Responses are wrapped by core: { statusCode, status, message, data }.

type: subject, with type one of feat, fix, chore, docs, refactor, test, style (commitlint). The subject says what changed for someone reading the log in a year.

Docs change in the same merge request as the code. A plugin’s README says what it does, which core services it uses and how to try it; architecture changes update this handbook.

Write for someone new: short sentences, plain words, the decision before the reasoning. Name things the way the screens do (“App Admin”, “follow-up”), not the way the code happens to.