1.5 KiB
1.5 KiB
Foundation Boundary Playbook
Use this when moving feature logic into HiveGrid's shared foundation or when touching audit, idempotency, flags, permissions, billing usage, or notifications.
Ownership Rules
- Runtime apps may orchestrate requests, headers, sessions, and responses.
- Shared business rules belong in
packages/*, preferably@hivegrid/foundationfor pure policy and@hivegrid/dbfor schema-backed server boundaries. - UI and route modules must not reach around package boundaries for tenant-scoped persistence.
- Foundation exports must stay generic. Do not add product-specific roles, flags, templates, adapters, or catalog entries.
Required Checks
- Audit writes use
@hivegrid/db/audit-events.server. - Idempotency keys use
@hivegrid/db/idempotency-keys.serveror the API idempotency store bridge. - API usage limits use
@hivegrid/db/usage.server; API routes should not recompute subscription feature math locally. - Notification deliveries use
sourceKeywhenever a producer can derive a stable event key, so DB upsert prevents duplicate delivery records. - Feature flags resolve in this order: explicit override, user scope, tenant scope, global scope, default.
Done Criteria
- Add or update focused tests in the owning package.
- Update the owning ticket doc and architecture decision when ownership, billing, provider, worker, or admin-managed behavior changes.
- Run
pnpm run test:foundation, the affected package tests, and the app-level route tests for changed runtimes.