System Features - API Reference

Audience: Admin panel engineers, mobile/portal engineers, QA, and any API consumer that needs to shape navigation around installation-level switches. Scope: One route — GET /api/system/features — that tells any signed-in caller which installation-level features are switched on for this school, and reveals accounting-integration setup detail only to the roles allowed to see it.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

This is the only route the module declares. SystemFeaturesModule is a leaf (its own entry in ADMIN_MODULES), not composed under any aggregate.

5. Auth, Identity, and Permissions

RoleGuard returns true for this handler before it reads request.user, because SystemFeaturesController.get is a key in NO_PERMISSION_ADMIN_HANDLERS (role.guard.ts:745). Every audience's navigation depends on this route, and the answer is booleans only — no row data, no ids — which is why it is deliberately left unpermissioned rather than gated behind any one module's read code.

The controller uses @CurrentUser, not @CurrentAdmin, specifically so a caller with no active role yet (mid-onboarding, or a multi-role account that has not selected one) still gets an answer instead of a hard failure; they just get no accounting setup detail, because accountingAccess() returns { setup: false, writeBackHint: false } when actor?.activeRole is absent.

6. DTO and Model Reference

6.1 SystemFeaturesDto (response)

6.2 AccountingIntegrationFeatureDto (nested)

paymentWriteBack answers one question: do payments recorded in the accounting application reach this school's fee records? It reads the payments:write scope itself, not merely the existence of a client, because an active client can hold read-only scopes. The office staff who record payments (FeePayments_CREATE) receive { enabled, paymentWriteBack } and none of the setup fields.

configured, clientConnected and hasClients are omitted from the response body, not sent as null or false — the service only assigns them onto accountingIntegration inside the accountingAccess().setup branch of SystemFeaturesService.get, and ResponseDto serializes whatever object it is given.

Response envelope: ResponseDto<SystemFeaturesDto> — message, data, with count/currentPage/totalPage/nextCursor/errorCode all present in the Swagger schema but unused by this route (common/dto/response-dto.ts).

7. Enum Reference

None. This module declares no enums; every field is a plain boolean.

8. Endpoint Reference

8.1 GET /api/system/features

Purpose

Call this once per session (or whenever navigation is rebuilt) to learn which installation-level features this school has switched on, so the panel can show or hide the accounting-integration screens and, for the roles allowed to configure it, its setup state. Safe to call before an active role is chosen — it degrades gracefully to enabled only.

Source Evidence

Auth and Permissions

• Auth: JWT required (global JwtAuthGuard).
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: none — allowlisted in NO_PERMISSION_ADMIN_HANDLERS.
• Guest support: none; an unauthenticated request is refused before the handler runs.
• Rate limit: none declared on this controller.
• Idempotency: N/A — pure read, Cache-Control: no-store on every response.

Request

GET /api/system/features HTTP/1.1
Authorization: Bearer TOKEN

Response

200 OK, always Cache-Control: no-store (@Header("Cache-Control", "no-store") on the handler — the answer must never be served stale from an intermediary, since it gates navigation and setup screens).

Caller without an accounting permission (or with no active role yet):

{
  "message": "Features fetched.",
  "data": {
    "accountingIntegration": {
      "enabled": true
    }
  }
}

Caller whose active role holds one of the five accounting permissions:

{
  "message": "Features fetched.",
  "data": {
    "accountingIntegration": {
      "enabled": true,
      "configured": true,
      "clientConnected": false,
      "hasClients": true
    }
  }
}

Installation with the integration switched off entirely, for a caller who holds an accounting permission:

{
  "message": "Features fetched.",
  "data": {
    "accountingIntegration": {
      "enabled": false,
      "configured": false,
      "clientConnected": false,
      "hasClients": true
    }
  }
}

clientConnected is forced to false whenever enabled is false (SystemFeaturesService.get) — it is never computed against the database in that state. hasClients is still computed, because a client from before the switch was turned off must stay visible for revocation.

Side Effects

None. This route performs no writes, no cache writes, no queue enqueues, no realtime events, and no audit log entry — it is a plain GET with a read-only service, and it is not a mutating request, so ActivityAuditInterceptor does not record it.

Error Cases

No route-specific error code exists for this endpoint. ACCOUNTING_INTEGRATION_DISABLED is registered in error-codes.ts and thrown elsewhere in the codebase when a caller tries to use the accounting integration while it is switched off — this route never throws it, because reporting enabled: false is itself the successful response, not a refusal.

Edge Cases

• No active role selected yet: actor?.activeRole is undefined, accountingAccess() short-circuits to { setup: false, writeBackHint: false }, response carries enabled only.
• Superadmin caller: accountingAccess() returns { setup: true, writeBackHint: true } immediately for role.isSuperadmin, without a permission lookup.
• Non-superadmin caller holding none of the five accounting permissions: response carries enabled only, same shape as "no active role".
• Integration switched off (enabled: false): clientConnected is hard-coded false without a database read; hasClients still queries the database.
• No integration client rows exist at all: both clientConnected and hasClients resolve to false (empty result from each query).
• An integration client exists but every key on it is expired or inactive: clientConnected is false (the join requires status: "active" on the key and expiresAt > now()); hasClients can still be true if the client itself is not revoked.
• Concurrent requests: no shared mutable state; every call independently re-reads config and the database, so there is no staleness beyond normal read-committed behavior.

Example Requests

GET /api/system/features HTTP/1.1
Authorization: Bearer TOKEN

curl -X GET "$API_URL/api/system/features" \
  -H "Authorization: Bearer TOKEN"

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence

9.3 Error Branch

10. Pagination, Sorting, Filtering, and Search

Not applicable. This is a single-object read with no list, no pagination, no sort or filter parameters.

11. Caching, Jobs, and External Integrations

12. Consumer Integration Notes

13. API Tradeoffs and Rationale

14. API Change Impact

15. Zero-Omission API Checklist

• The one controller route is documented.
• The route prefix and runtime URL are documented.
• Every DTO field, nested field, default, and visibility rule is documented.
• Every response field and its omission behavior is documented.
• Auth, guard chain, and the no-permission allowlist entry are documented.
• Success and auth-failure branches are documented; no route-specific error code exists.
• The module performs no DB writes, no cache, no queue, no realtime, no audit — stated explicitly.
• The route has minimal and full-detail response examples for both visibility states.
• Route, sequence, and error diagrams are included.
• Tradeoffs are documented.
• Links to backend and features/flows docs are included.

16. Integration Checklist

• The route from the controller is documented.
• Every DTO field is documented.
• No enums exist in this module.
• The response envelope is documented.
• No module-specific error code exists; this is stated rather than invented.
• Auth guard and the no-permission allowlist are documented.
• No cache key, queue job, realtime event, or external call exists; this is stated rather than invented.
• Diagrams match the current code.
• Links to backend and features/flows docs are included.

See Also

• Backend doc: /docs/developer/system-features/backend
• Features and flows doc: /docs/developer/system-features/feature