@keel_flow/pack-backend-design

Backend design principles for Keel projects: the API reuse ladder (reuse, then extend, then new), contract-first routes, migration safety, timeouts, authorization and configuration — checked against Python and SQL by keel verify.

Part of the Keel framework.

What was built

Nineteen principles, composed in src/index.ts as backendDesignPack (also the default export). Python is read through @keel_flow/py-ast; SQL migrations are read as regex over text whose comments, strings and dollar-quoted bodies have been blanked length-preservingly, so a reported line number still names the line you open.

The ladder and the contract

| id | severity | | --- | --- | | api-reuse-before-new | critical | | contract-before-handler | critical | | no-breaking-contract-change | critical |

API shape

| id | severity | | --- | --- | | api-models-not-orm | critical | | input-models-forbid-extra | critical | | collections-paginated | critical | | problem-details-errors | warning |

Failure behaviour

| id | severity | | --- | --- | | no-blind-except | critical | | outbound-calls-have-timeouts | critical | | bounded-retries-at-one-layer | warning | | no-blocking-in-async | warning | | long-work-async | critical | | mutations-idempotent | warning |

Data

| id | severity | | --- | --- | | migrations-expand-contract | critical | | migrations-lock-safe | critical | | no-query-in-loop | warning |

Security and configuration

| id | severity | | --- | --- | | routes-auth-by-default | critical | | authz-per-object | critical | | config-typed-fail-fast | warning |

Paths under a __fixtures__ or fixtures directory are out of scope for every check: deliberately wrong sample code is a test's input, not a defect to block on.

Every check reads the optional .keel/backend.json through loadBackendConfig, and a check whose configuration is absent returns no violations — an unconfigured project, or one with no Python at all, is never blocked by this pack. Checks honour # keel-ignore-file: <id> and # keel-ignore-next-line: <id>, skip removed files, and return no violations rather than throwing on a missing file, unparsable Python or malformed JSON.

The package also exports the api-stub reader (parseApiStubs, stubMatchesRoute) and the config loader that keel api inventory and keel api match are built on, so the block a design document carries and the block the gate reads are parsed by one implementation.

The design record is docs/design/backend-design-pack.md, which lists the checks' known limits.

License

MIT

.keel/backend.json may also carry "root" — a path, or a list of candidate paths, to a project checked out somewhere other than the directory holding the config. keel api reads the OpenAPI document and the front-end clients from there (resolveSourceRoot), which is how a coordination repository inventories a product it may not write into. The checks above ignore it: they judge the diff of the repository keel verify runs in.