System Features Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• One read endpoint reporting installation-level feature switches to any signed-in caller.
• The visibility rule that hides accounting-integration setup detail from callers who do not hold an accounting permission.

Does Not Own

• The accounting integration's actual behavior (client management, keyring rotation, sync jobs) — that lives in apps/api/src/modules/integration/. This module only reports on it.
• The ACCOUNTING_INTEGRATION_ENABLED switch's enforcement on other routes — common/feature-flags/accounting-integration.ts also exports RequiresAccountingIntegration(), a decorator used elsewhere to 404 accounting routes while disabled. system-features only reads the flag; it never enforces it.
• Permission resolution itself — delegated to RoleService (modules/role/).

Source of Truth

3. Module Composition

SystemFeaturesModule declares its own controller, so it is itself the entry registered in ADMIN_MODULES (config/swagger/swagger-documents.ts:1344) — there is no separate aggregate module to list instead.

4. File and Directory Map

apps/api/src/modules/system-features/
  system-features.module.ts
  system-features.controller.ts
  system-features.service.ts
  dto/
    system-features.dto.ts

5. Data Model

This module owns no schema of its own. It reads two tables owned by the integration module.

5.1 Schema Source

packages/db/src/schema/  (owned by the integration module, read here)
  integrationClients
  integrationClientKeys

5.2 Tables Read

integration_clients (read-only from this module)

integration_client_keys (read-only from this module)

This module never writes to either table. Full column definitions, constraints, and lifecycle belong to the integration module's own documentation.

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 SystemFeaturesService

Explain:

• Input normalization: none — the route takes no request body, query, or params.
• Validation order: not applicable; the only branching is the permission check.
• Transaction boundaries: none — every query is a standalone SELECT, and none depends on another within the same request beyond ordering (configured/clientConnected/hasClients are only computed after the permission check passes).
• Idempotency: trivially idempotent — pure reads, no state changes.
• Retry behavior: none implemented or needed; a failed DB read propagates as a normal 500 through the global exception filter.
• Response mapping: the service returns SystemFeaturesDto directly; the controller does not remap it, only wraps it in ResponseDto.
• Fail-open or fail-closed: fail-closed on the setup fields — accountingAccess() defaults to { setup: false, writeBackHint: false } for any caller without an active role or a matching permission, so the safe default is "do not reveal setup detail."
• Logger usage: none in this service.

7. Runtime Flows

7.1 GET /api/system/features

Include:

• Success path: as above, in both branches (with and without accounting-permission detail).
• Validation failures: none possible — no input to validate.
• Permission failures: none surfaced as an error; the "failure" to see setup detail is silent field omission, not a 403.
• Missing entity: not applicable — there is no path-addressed entity.
• Duplicate request: not applicable — pure read, safe to call repeatedly.
• Cache miss/hit: not applicable — the route is explicitly no-store.
• Async enqueue: none — no queue involvement.
• Race/concurrency: none — each request is independent; no shared mutable state.
• Guest vs logged-in branch: an unauthenticated caller never reaches the handler (JwtAuthGuard refuses first).

8. Caching

None. The handler sets Cache-Control: no-store explicitly, and the service performs no Redis reads or writes. Every call re-evaluates the feature flag and, when applicable, re-queries the database.

9. BullMQ, Schedulers, and Async Work

None. This module owns no queue, no processor, and no scheduled job.

10. Realtime and Events

None. This module emits no realtime events and is not a consumer of any.

11. Security, Auth, and Abuse Controls

• Guards: JwtAuthGuard (global) requires a valid session; RoleGuard runs but short-circuits to true for this handler via the NO_PERMISSION_ADMIN_HANDLERS allowlist (role.guard.ts:745-754), before it would otherwise read request.user or refuse a missing active role.
• Permissions: none required to call the route at all. A separate, service-level check (accountingAccess, returning { setup, writeBackHint }) gates only the four optional response fields (configured, clientConnected, hasClients on setup; paymentWriteBack on setup or writeBackHint), never the route itself.
• Guest identity: not applicable — no guest path exists; the global guard refuses unauthenticated callers.
• Admin identity: @CurrentUser, deliberately not @CurrentAdmin — the handler tolerates a session with no chosen active role.
• Rate limits: none declared on this controller.
• Anti-abuse rules: none specific to this route.
• Input normalization: not applicable — no input.
• Sensitive data redaction: the response never includes ids, client identifiers, or key material — only booleans.
• Audit logs: none written. This is a non-mutating GET, so ActivityAuditInterceptor (which records every mutating request) does not fire for it.
• Fail-closed behavior: the setup-detail gate defaults to withholding the fields whenever the permission check cannot prove the caller is entitled to see them.

12. Error Handling

This module defines and throws no error code of its own. ACCOUNTING_INTEGRATION_DISABLED (common/types/error-codes.ts:1966) exists in the shared registry and is thrown by other modules that enforce the switch (via RequiresAccountingIntegration()), but never by this one — reporting enabled: false here is a normal 200, not a refusal.

13. Observability

14. Testing and Validation

Validation commands:

pnpm --filter @skoolsewa/api test:structure

See Also

• API doc: /docs/developer/system-features/api
• Features and flows doc: /docs/developer/system-features/feature