Architecture

This document describes the runtime and logical architecture of the Provision Portal UI, its main building blocks, and how it interacts with the Provision Portal backend.

C4 Context

c4-context

The container diagram shows how the browser, the single Nginx container, and the backend cooperate at runtime.

c4-container

Note the difference from a browser-calls-backend-directly model: the browser always calls the same-origin relative path /prov-api/, and Nginx reverse-proxies it to FT_PROV_API_URL. This keeps the deployed artifact origin-agnostic and avoids browser CORS.

Workspace structure

The repository is a single-application Angular CLI 21 workspace. The src/app tree is organised by role:

Area Role

components/pages/*

Route-level pages (single-device, multiple-device, replace-device, deactivate-service, get-status, view-log, user-management, login).

components/base/*

Reusable, standalone form controls (ft-common-input, select, checkbox, radio-group, button, loader, confirmation) implementing ControlValueAccessor.

layouts/*

AuthLayoutComponent (login) and MainLayoutComponent (authenticated shell).

services/*

HTTP and state services (ApiService, AuthService, ProvisionService, DeviceService, ServerService, UserService, ConfigService, MenuStateService).

guards/*

authGuard, PermissionGuard, ConfigGuard.

interceptors/*

AuthInterceptor (Bearer token) and ErrorHandlerInterceptor (toastr on HTTP error).

models/*

Interfaces, enums, and the @ngrx/signals UserStore.

Client-side architecture

The Provision Portal UI is a standard Angular 21 application built from standalone components. Common building blocks:

  • HTTP layer. All services call a single ApiService, which prefixes the runtime apiUrl (/prov-api/) and JSON-serialises bodies. Two DI interceptors wrap every request. See API Integration.

  • State management. @ngrx/signals Signal Store (UserStore) manages collection state; plain signal services (ServerService, MenuStateService) hold simple shared state. See State & Data Flow.

  • Routing & layouts. Angular Router drives two layout shells (auth / main) with route guards. See Routing & Layouts.

  • i18n. @ngx-translate/core with the HTTP loader provides runtime translations from assets/i18n/.

  • UI toolkit. Angular Material / CDK, ng-bootstrap + Bootstrap 5, ngx-toastr for notifications, angular-svg-icon for inline SVGs.

Runtime configuration and API access

The application loads assets/config/app.config.json through an APP_INITIALIZER (ConfigService.loadConfig()) before it boots, so apiUrl is available to the first HTTP call. The container entrypoint patches that value to /prov-api/, and Nginx proxies /prov-api/ to the backend — so the same image works across environments without a rebuild. See Configuration and API Integration.

Architectural changes that affect authentication, routing, or runtime configuration should be reflected both in this document and in the C4 diagrams to keep them aligned.