System Features Features and Flows
Developer Resources System Features System Features Features and Flows Complete feature list, actor journeys, business rules, and edge cases for system-features.
Source Type Files or Docs What Was Extracted API system-features.controller.ts, API doc Route, actors, auth, response-visible behavior. Backend system-features.service.ts, Backend doc Permission gate, query behavior, side effects (none).
Field Value Module system-featuresSubmodule N/A Primary user value Lets the panel discover, in one call, which installation-level features this school has switched on, so it can show or hide navigation and setup screens without hardcoding assumptions per deployment. Actors Any authenticated user (guardian, student, teacher, staff, admin, superadmin); unauthenticated callers are refused before reaching this feature. Main entry points GET /api/system/featuresMain outputs A response body of booleans — no persisted records, no events, no notifications. Related docs API , Backend
Actor Can Do Cannot Do Auth Requirement Notes Guest (unauthenticated) Nothing Call the endpoint at all None available Refused by the global JwtAuthGuard with 401 before the handler runs. Signed-in user, no active role chosen Read enabled See accounting setup detail JWT Applies to any audience mid-onboarding or before a role is selected. Signed-in user, active role without an accounting permission Read enabled See accounting setup detail JWT Includes most guardian, student, and teacher sessions, and staff without a fee/salary/asset sync read code. Signed-in user, active role holding FeePayments_CREATE but none of the accounting permissions Read enabled and paymentWriteBack (whether payments recorded in the accounting application are written back to this school) See any other setup field JWT Office staff who record payments. Signed-in user, active role holding FeeSync_READ, FeeMappings_READ, FeeIntegrations_READ, SalarySync_READ, or AssetSync_READ Read enabled, configured, clientConnected, hasClients, paymentWriteBack Change any of these values through this route — it is read-only JWT Typically finance/admin staff and superadmin. Superadmin Same as the permission-holding row, granted unconditionally — JWT role.isSuperadmin short-circuits the permission lookup.
Capability Surface Actor Route/Trigger State Read State Written Linked API Section Learn whether accounting integration is switched on Admin (audience-agnostic) Any signed-in user GET /api/system/featuresACCOUNTING_INTEGRATION_ENABLED env varNone API §8.1 Learn whether the integration is configured and connected Admin (audience-agnostic) Role holding an accounting permission, or superadmin Same route Keyring state, integration_clients, integration_client_keys None API §8.1
On login, or whenever the panel rebuilds its navigation (role switch, page refresh), it calls this endpoint to decide whether to render the accounting-integration section at all, and — for roles allowed to configure it — whether to prompt for setup or show a connected/disconnected state.
The caller has a valid session (any authenticated user).
No catalog, pricing, or session state is required — this is a pure configuration read.
No feature flag gates the route itself; ACCOUNTING_INTEGRATION_ENABLED is one of the values it reports , not a precondition for calling it.
Step Actor/System Action Result Source 1 Panel Calls GET /api/system/features with the session's bearer token. Request accepted by JwtAuthGuard. Controller. 2 Backend RoleGuard allows the handler through unconditionally (allowlisted).No permission check at the route level. role.guard.ts:745.3 Backend Reads ACCOUNTING_INTEGRATION_ENABLED; checks whether the caller's active role qualifies for setup detail. enabled always set; configured/clientConnected/hasClients set only if qualified.Service. 4 Panel Renders navigation based on the returned booleans. Accounting section shown/hidden; setup screen shown only where the caller could plausibly act on it. Backend doc.
Branch Condition Behavior Error/Result No active role yet actor.activeRole is undefinedOnly enabled returned 200, minimal bodyRole without accounting permission Permission lookup misses all five codes Only enabled returned 200, minimal bodyRole with accounting permission, integration disabled enabled: falseconfigured/hasClients still computed from real state; clientConnected forced false200, full body with clientConnected: falseUnauthenticated No valid JWT Refused before the feature runs 401
This module exposes no mutating admin action — it is a read-only disclosure endpoint. There is no create, update, delete, or restore flow to document here; configuring the integration itself (rotating keys, connecting a client) is owned by the integration module and out of scope for this page.
Include route, permission, mutation side effects, cache invalidation, audit/logging, and failure branches: this flow has no mutation , no cache invalidation , and no audit entry — every step is the same single read described in §5.1, re-interpreted by the panel.
This module has no entity lifecycle of its own — it reports on the lifecycle of the accounting integration, which is owned elsewhere. There is no state machine to document for system-features itself.
Flow DB Writes Cache Effects Jobs Realtime Analytics Notifications GET /api/system/featuresNone None (no-store) None None None None
Scenario Trigger User/System Experience Recovery Source Session expired Missing/invalid JWT 401 responseRe-authenticate JwtAuthGuard (global).Database temporarily unavailable Query failure in clientConnected()/hasClients() 500 via the global exception filterRetry the request Global AllExceptionsFilter.
Covered above: the sequence diagram in §5.1, the flowchart in §6.1. No state machine exists (§7), so no state diagram is produced — this module has no lifecycle. No dedicated error-branch diagram beyond the table in §10, since the only failure paths are the global auth guard and an unhandled DB error, both already fully described.
Feature Minor Behavior Actor Trigger User/System Result Backend Side Effect Source Report enabled Always present, regardless of role Any signed-in user GET /api/system/featuresPanel knows if accounting exists at all Read ACCOUNTING_INTEGRATION_ENABLED SystemFeaturesService.getReport setup detail Omitted (not null/false) for unqualified callers Role without an accounting permission Same route Panel sees no configured/clientConnected/hasClients keys No extra DB read performed SystemFeaturesService.getForce clientConnected: false while disabled Skips the DB join entirely Any qualified caller, with the switch off Same route Panel never shows "connected" while the feature is off No query issued SystemFeaturesService.getCompute hasClients regardless of enabled Runs even while the switch is off Any qualified caller Same route Panel can still show "you have a client to revoke" after disabling One SELECT query SystemFeaturesService.get, hasClientsSuperadmin bypass Skips the permission-code lookup entirely Superadmin Same route Same setup detail as any qualified role One fewer DB call SystemFeaturesService.accountingAccessno-store response headerEvery response, unconditionally Any caller Same route Client/proxy never caches a stale feature state None system-features.controller.ts:30
Rule Business Reason Actor Impact Enforced In API Impact Backend Impact Tests Every signed-in caller may read enabled Every audience's navigation needs to know whether the feature exists No caller is blocked from the route NO_PERMISSION_ADMIN_HANDLERS allowlistRoute carries no @Permissions() RoleGuard short-circuits to allowroute-permissions.spec.ts:127-131Setup detail requires an accounting permission or superadmin Setup state is operationally sensitive even though it is not secret Non-finance roles see a minimal body SystemFeaturesService.accountingAccessOptional fields present/absent Conditional query execution None (no unit test exists) clientConnected is false whenever enabled is falseA client cannot be meaningfully "connected" to a switched-off integration Consistent UI even during a disabled window SystemFeaturesService.getField always coherent with enabled Skips a query when disabled None Response is never cached Feature state can change between deploys/config edits and must reflect immediately Panel always sees current state @Header("Cache-Control", "no-store")HTTP header on every response None None
Product Decision User Benefit Engineering Benefit Alternative Tradeoff Risk Unpermissioned route, service-level field gating Every audience gets a working navigation call without needing a bespoke permission grant One route serves every audience instead of duplicating per-audience endpoints A dedicated SystemFeatures_READ permission Slightly less explicit in the permission catalog Low — the gate is centralized in one function @CurrentUser instead of @CurrentAdminA caller mid-onboarding, with no active role, still gets a usable answer No special-casing needed elsewhere for "no active role yet" callers Require an active role Would 401/403 sessions that legitimately have none yet None material — the degraded response (enabled only) is deliberately safe
Flow Edge Case Trigger Expected Behavior User/System Feedback Source Feature read No active role Session mid-onboarding Minimal body enabled onlySystemFeaturesService.accountingAccessFeature read Integration disabled, caller qualified ACCOUNTING_INTEGRATION_ENABLED=falseFull body, clientConnected forced false Panel shows disabled + still-revokable clients if any SystemFeaturesService.getFeature read Unauthenticated No/invalid JWT Request refused before reaching the feature 401Global JwtAuthGuard Feature read Concurrent calls Two simultaneous requests Both resolve independently; no shared state Two consistent, possibly differing (if config changed) responses Stateless service
Flow Reads Writes Cache Jobs/Events Response Fields GET /api/system/featuresConfig, keyring state, integration_clients, integration_client_keys None None None enabled, configured, clientConnected, hasClients, paymentWriteBack
Complete API contracts for backup, including routes, auth, DTOs, responses, errors, examples, and integration notes.
System Features Backend Documentation
Backend architecture, data model, services, and runtime rules for system-features.