Conventions
A short list, because each item is enforced somewhere or costs real time when skipped.
- TypeScript, strict.
noUncheckedIndexedAccessandexactOptionalPropertyTypesare on: check index access, and leave optional keys out rather than setting them toundefined. - 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:specand commitopenapi.jsonand the generated client. CI fails when they are stale. - Responses are wrapped by core:
{ statusCode, status, message, data }.
Commits
Section titled “Commits”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.