ngx-admin

Architecture Overview

Application: ngx-admin Document Title: Architecture Overview Date: May 2026

3. Document Roadmap

This document is organized to serve multiple audiences. Use the guide below to navigate to the sections most relevant to your role.

4. Executive Summary

ngx-admin is an Angular-based administrative dashboard application that serves as both a functional dashboard and a comprehensive UI component showcase. The application provides two primary value propositions: a set of operational dashboard screens (IoT device monitoring, e-commerce analytics, energy consumption tracking, and media playback) and an extensive library of interactive demonstrations covering forms, charts, maps, modal overlays, tables, and UI component variants. The application is built on the open-source Nebular design system by Akveo and is publicly available as a reference implementation and starter template for Angular-based enterprise dashboards.

The primary users of this application are developers and technical teams who use it as a starting point for building Angular dashboards, as well as end users of any application derived from this template. The application targets a broad range of screen sizes and supports four distinct visual themes (Default, Dark, Cosmic, and Corporate), with all UI components adapting dynamically to the active theme at runtime.

The technical approach is a single-page application (SPA) built with Angular 15, using the Nebular component library for UI primitives, Apache ECharts and Chart.js for data visualization, and Leaflet and Google Maps for geographic features. The application is organized into feature modules grouped by domain (dashboard, e-commerce, forms, charts, maps, tables, modal overlays, extra components, editors, and UI features), each accessible via Angular's lazy-loaded routing. Data is provided through an abstract service layer that decouples the UI from its data sources, enabling the application to run with mock data while remaining structurally ready for real backend integration.

The most significant architectural characteristics are: (1) a pervasive reactive theming system where every chart, map, and UI component subscribes to NbThemeService and re-renders when the theme changes; (2) an abstract data service pattern where all data-fetching contracts are defined as abstract Angular classes, with concrete implementations injected at the module level; (3) a consistent use of shell components with <router-outlet> for feature grouping, enabling clean lazy loading boundaries; and (4) a heavy reliance on static and mock data throughout the demonstration screens, with no live backend integration visible in the assessed code.

This Architecture Overview covers 100 screens of the ngx-admin application. The screens and routes assessed are: Earning Card (/e-commerce/earning-card), D3 (/charts/d3), Chartjs (/charts/chartjs), Tiny Mce (/@theme/components/tiny-mce), Dashboard (/dashboard), Charts (/charts), Footer (/@theme/components/footer), Search Input (/@theme/components/search-input), Header (/@theme/components/header), Echarts (/charts/echarts), Temperature Dragger (/dashboard/temperature/temperature-dragger), Solar (/dashboard/solar), E Commerce (/e-commerce), Status Card (/dashboard/status-card), Chart Panel Summary (/e-commerce/charts-panel/chart-panel-summary), Country Orders (/e-commerce/country-orders), Room Selector (/dashboard/rooms/room-selector), Traffic (/dashboard/traffic), Weather (/dashboard/weather), Chart Panel Header (/e-commerce/charts-panel/chart-panel-header), Contacts (/dashboard/contacts), Rooms (/dashboard/rooms), Player (/dashboard/rooms/player), Chart (/e-commerce/country-orders/chart), Electricity Chart (/dashboard/electricity/electricity-chart), Kitten (/dashboard/kitten), Temperature (/dashboard/temperature), Ckeditor (/editors/ckeditor), User Activity (/e-commerce/user-activity), Front Side (/e-commerce/profit-card/front-side), Visitors Analytics (/e-commerce/visitors-analytics), Slide Out (/e-commerce/slide-out), Traffic Cards Header (/e-commerce/traffic-reveal-card/traffic-cards-header), Traffic Bar (/e-commerce/traffic-reveal-card/front-side/traffic-bar), Back Side (/e-commerce/traffic-reveal-card/back-side), Front Side (/e-commerce/traffic-reveal-card/front-side), Progress Section (/e-commerce/progress-section), Back Side (/e-commerce/profit-card/back-side), Form Layouts (/forms/form-layouts), Spinner Sizes (/extra-components/spinner/spinner-sizes), Progress Bar (/extra-components/progress-bar), Spinner (/extra-components/spinner), Interactive Progress Bar (/extra-components/progress-bar/interactive-progress-bar), Buttons (/forms/buttons), Spinner Color (/extra-components/spinner/spinner-color), Spinner In Buttons (/extra-components/spinner/spinner-in-buttons), Forms (/forms), Spinner In Tabs (/extra-components/spinner/spinner-in-tabs), Datepicker (/forms/datepicker), Maps (/maps), Bubble (/maps/bubble), Form Inputs (/forms/form-inputs), Dialog Name Prompt (/modal-overlays/dialog/dialog-name-prompt), Window (/modal-overlays/window), Window Form (/modal-overlays/window/window-form), Smart Table (/tables/smart-table), Toastr (/modal-overlays/toastr), Tooltip (/modal-overlays/tooltip), Grid (/ui-features/grid), Ui Features (/ui-features), Tables (/tables), Showcase Dialog (/modal-overlays/dialog/showcase-dialog), Search Map (/maps/search-map), Icons (/ui-features/icons), Pages (/pages), Tree Grid (/tables/tree-grid), Popovers (/modal-overlays/popovers), Typography (/ui-features/typography), Charts Panel (/e-commerce/charts-panel), Extra Components (/extra-components), Visitors Analytics Chart (/e-commerce/visitors-analytics/visitors-analytics-chart), Electricity (/dashboard/electricity), Map (/e-commerce/country-orders/map), Security Cameras (/dashboard/security-cameras), Nebular Select (/extra-components/form-inputs/nebular-select), Charts (/e-commerce/charts-panel/charts), Modal Overlays (/modal-overlays), Back Side (/e-commerce/earning-card/back-side), Legend Chart (/e-commerce/legend-chart), Alert (/extra-components/alert), Traffic Reveal Card (/e-commerce/traffic-reveal-card), Map (/maps/search-map/map), Front Side (/e-commerce/earning-card/front-side), Calendar (/extra-components/calendar), Calendar Kit (/extra-components/calendar-kit), Visitors Statistics (/e-commerce/visitors-analytics/visitors-statistics), Miscellaneous (/miscellaneous), Profit Card (/e-commerce/profit-card), Search (/maps/search-map/search), Editors (/editors), Chat (/extra-components/chat), Search Fields (/ui-features/search-fields), Tiny Mce (/editors/tiny-mce), Day Cell (/extra-components/calendar/day-cell), Leaflet (/maps/leaflet), Month Cell (/extra-components/calendar-kit/month-cell), Not Found (/miscellaneous/not-found), Form Inputs (/extra-components/form-inputs), Dialog (/modal-overlays/dialog), and Gmaps (/maps/gmaps).

Components, patterns, and features not included in the assessed documentation are outside the scope of this document.

Generated by Inkwell Forge — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

5. Stakeholders & Concerns

5.1 Stakeholder Table

5.2 Top Architectural Quality Goals

The following quality goals are derived from patterns consistently observed across the 100 assessed screens:

1. Theme Consistency — Every visual component must adapt to the active Nebular theme at runtime. This is the most pervasively enforced quality goal in the codebase, evidenced by NbThemeService subscriptions in virtually every chart, map, and widget component.

2. Component Reusability — The application is structured as a showcase and starter template; components must be self-contained, accept @Input() data, and emit @Output() events rather than coupling to global state.

3. Separation of Data and Presentation — The abstract service pattern (e.g., SolarData, UserData, ElectricityData) enforces that UI components are decoupled from their data sources, enabling mock-to-real backend substitution without component changes.

4. Maintainability — Consistent use of shell components, feature module grouping, and the Nebular component library reduces the surface area for custom code and makes the codebase navigable.

5. Responsiveness — Multiple screens subscribe to NbMediaBreakpointsService and NbThemeService.onMediaQueryChange() to adapt layouts and component sizes to the active viewport breakpoint.

6. System Context

6.1 System Boundary

The ngx-admin application is a client-side single-page application that runs entirely in the browser. The system boundary encompasses the Angular application bundle, the Nebular component library, and all feature modules. Outside the boundary are: the browser's native APIs (Geolocation, HTMLAudioElement), third-party CDN-hosted libraries (CKEditor, TinyMCE), external map tile providers (OpenStreetMap, Google Maps), external media CDNs (Spotify preview URLs), and any backend data services that would be connected via the abstract service layer in a production deployment.

[Diagram: System Context — show the ngx-admin Angular SPA as a central box; connect it to: Browser Native APIs (Geolocation, HTMLAudioElement), OpenStreetMap Tile CDN, Google Maps JavaScript API, CKEditor CDN (cdn.ckeditor.com), Spotify CDN (p.scdn.co), Backend Data Services (abstract — not implemented in assessed code), and the user's browser as the runtime host]

6.2 External Interfaces

7. Solution Strategy

7.1 Technology Stack

The following technology choices are directly evidenced in package.json and the screen documentation:

7.2 Top-Level Decomposition

The application is organized as an Angular NgModule-based SPA with a hierarchical routing structure. The top-level decomposition is:

• AppModule — Root module; bootstraps the application.
• PagesModule — The authenticated shell; hosts the ngx-one-column-layout with sidebar navigation and a <router-outlet> for all feature modules.
• Feature Modules — Lazily loaded modules grouped by domain: DashboardModule, ECommerceModule, ChartsModule, FormsModule, MapsModule, TablesModule, ModalOverlaysModule, ExtraComponentsModule, EditorsModule, UiFeaturesModule, MiscellaneousModule.
• @theme Module — Shared layout components: HeaderComponent, FooterComponent, SearchInputComponent, and layout wrappers.
• @core Module — Shared services: abstract data service classes, LayoutService, AnalyticsService, and utility services.

7.3 Key Architectural Patterns

1. Shell Component Pattern — Feature group routes (e.g., /charts, /forms, /maps, /tables) are handled by empty shell components containing only <router-outlet>. This creates clean lazy-loading boundaries and allows child routes to be independently navigable.

2. Abstract Service / Dependency Injection Pattern — All data-fetching contracts are defined as abstract Angular classes (e.g., SolarData, UserData, ElectricityData, CountryOrderData). Concrete implementations are registered in module providers. UI components depend only on the abstract class, enabling mock-to-real substitution without component changes.

3. Reactive Theming Pattern — Components subscribe to NbThemeService.getJsTheme() or NbThemeService.onThemeChange() to receive theme variable maps at runtime. Chart options, map styles, and component colors are constructed from these variables rather than hardcoded values.

4. Presentational / Container Component Split — Data-fetching and state management occur in container components (e.g., DashboardComponent, CountryOrdersComponent, ECommerceChartsPanelComponent). Leaf components (e.g., StatusCardComponent, ChartPanelSummaryComponent, TrafficBarComponent) are purely presentational, receiving all data via @Input().

5. takeWhile Subscription Lifecycle Pattern — The majority of components manage RxJS subscription cleanup using a boolean alive flag combined with takeWhile(() => this.alive), set to false in ngOnDestroy().

6. forkJoin for Parallel Data Loading — Multiple screens (ContactsComponent, TemperatureComponent, VisitorsAnalyticsComponent, ElectricityComponent) use forkJoin to fetch multiple data streams simultaneously, ensuring the UI renders only when all data is available.

7.4 Approach to Quality Goals

8. Building Block View

[Diagram: Building Block View — show the following containers: Browser (hosts the SPA), Angular SPA (contains PagesModule, feature modules, @theme module, @core module), External Services (OpenStreetMap, Google Maps, CKEditor CDN, Spotify CDN, Backend Data Services). Show dependency arrows from Angular SPA to External Services. Within Angular SPA, show PagesModule containing feature module boxes (Dashboard, E-Commerce, Charts, Forms, Maps, Tables, Modal Overlays, Extra Components, Editors, UI Features, Miscellaneous) and shared modules (@theme, @core).]

8.1 Level 1 — High-Level Containers

8.2 Level 2 — Component Breakdown

@theme Module (Shared Layout Shell)

@core Module (Shared Services)

Dashboard Module

E-Commerce Module

Charts Module

Maps Module

Tables Module

Modal Overlays Module

Extra Components Module

Editors Module

UI Features Module

Miscellaneous Module

Pages Module

8.3 Shared Building Blocks

9. Runtime View

9.1 Page Load and Theme Hydration

Participants: Browser, Angular Router, PagesComponent, HeaderComponent, NbThemeService, any chart component (e.g., EchartsComponent)

Sequence:

1. User navigates to a route (e.g., /charts/echarts).
2. Angular Router activates PagesComponent, which renders ngx-one-column-layout with nb-menu and <router-outlet>.
3. HeaderComponent initializes; reads themeService.currentTheme synchronously to set currentTheme; subscribes to themeService.onThemeChange() and themeService.onMediaQueryChange().
4. The router activates ChartsComponent (empty shell) and then EchartsComponent inside the nested outlet.
5. EchartsComponent.ngAfterViewInit() fires; subscribes to NbThemeService.getJsTheme().
6. NbThemeService emits the current theme's JS variable map.
7. EchartsComponent constructs the ECharts option object using theme color variables.
8. The echarts directive detects the option change and renders the chart canvas.

Error path: If NbThemeService.getJsTheme() fails to emit (e.g., theme configuration is malformed), the option object remains {} and the chart renders as an empty container with no user-facing error message.

[Diagram: Sequence — Page Load and Theme Hydration]

9.2 User Navigates Between Feature Sections

Participants: User, Angular Router, PagesComponent, Feature Module Shell Component, Child Route Component

Sequence:

1. User clicks a menu item in nb-menu (e.g., "Forms").
2. NbMenuService triggers navigation to /pages/forms.
3. Angular Router lazy-loads FormsModule if not already loaded.
4. FormsComponent (shell) is activated; renders <router-outlet>.
5. Router activates the default child route (e.g., FormLayoutsComponent).
6. FormLayoutsComponent renders its static template.
7. If the user then clicks "Form Inputs", the router replaces the outlet content with FormInputsComponent without re-loading FormsModule.

Error path: If the lazy-loaded module fails to load (e.g., network error), Angular's router error handling applies. No custom error UI is defined at the shell level.

[Diagram: Sequence — User Navigates Between Feature Sections]

9.3 Dashboard Data Loading via Abstract Service

Participants: DashboardComponent, SolarData (abstract), Concrete SolarService, NbThemeService

Sequence:

1. DashboardComponent is constructed.
2. Two RxJS subscriptions are established simultaneously:
   • SolarData.getSolarData() — emits numeric solar readings.
   • NbThemeService.getJsTheme() — emits the current theme object.
3. On SolarData emission, solarValue is updated; the template re-renders the solar widget.
4. On NbThemeService emission, theme.name is used as a key into statusCardsByThemes; the resolved CardSettings[] is assigned to statusCards.
5. Both subscriptions remain active for the component's lifetime, managed by takeWhile(() => this.alive).
6. On ngOnDestroy, alive is set to false; both subscriptions complete on their next emission.

Error path: No catchError or error callback is present on either subscription. If SolarData.getSolarData() errors, solarValue remains undefined and the solar widget renders in an empty/zero state.

[Diagram: Sequence — Dashboard Data Loading via Abstract Service]

9.4 High-Frequency Live Data Polling

Participants: EarningCardFrontComponent, EarningData (abstract), interval(200), switchMap

Sequence:

1. EarningCardFrontComponent.ngOnInit() calls getEarningCardData(selectedCurrency).
2. On initial data emission, earningLiveUpdateCardData and liveUpdateChartData are populated.
3. startReceivingLiveData(currency) is called; creates interval(200) observable.
4. Every 200ms, switchMap cancels any in-flight request and calls EarningData.getEarningLiveUpdateCardData(currency).
5. On each emission, liveUpdateChartData is replaced with a new array reference ([...data]), triggering Angular change detection and chart re-render.
6. When the user selects a different currency, changeCurrency() unsubscribes the existing intervalSubscription and restarts from step 1.
7. On ngOnDestroy, alive is set to false; all subscriptions complete.

Error path: If getEarningLiveUpdateCardData() errors, switchMap propagates the error and terminates the interval subscription. No error recovery or retry logic is implemented.

[Diagram: Sequence — High-Frequency Live Data Polling]

9.5 Dialog Interaction with Return Value

Participants: DialogComponent, NbDialogService, DialogNamePromptComponent, NbDialogRef

Sequence:

1. User clicks the "Name Prompt" button; DialogComponent.open3() is called.
2. NbDialogService.open(DialogNamePromptComponent) creates and renders the dialog overlay; returns a NbDialogRef.
3. DialogComponent subscribes to dialogRef.onClose.
4. DialogNamePromptComponent renders with a text input and Cancel/Submit buttons.
5. User types a name and clicks Submit; DialogNamePromptComponent.submit(name) calls this.ref.close(name).
6. NbDialogRef.close(name) emits name through the onClose observable and destroys the overlay.
7. DialogComponent's subscription callback receives name; if truthy, pushes it to this.names.
8. Angular change detection re-renders the names list in the template.

Error path: If the user clicks Cancel, ref.close() is called with no argument; the onClose observable emits undefined; the guard name => name && this.names.push(name) prevents undefined from being added to the list.

[Diagram: Sequence — Dialog Interaction with Return Value]

10. Data Flow & State Management

[Diagram: Data Flow — show data sources (Abstract Services, NbThemeService, Static/Hardcoded Data, Browser APIs) flowing through Container Components (which hold state) to Presentational Components (which receive @Input() and emit @Output()), with ECharts/Leaflet/Chart.js rendering engines at the leaf level]

10.1 Data Sources

The application draws data from four categories of sources:

1. Abstract Data Services — The primary data source for operational screens. Services such as SolarData, UserData, ElectricityData, CountryOrderData, and EarningData are abstract Angular classes. Concrete implementations (not included in the assessed code) are registered in module providers and may connect to REST APIs, WebSockets, or mock data generators.

2. Static / Hardcoded Data — The majority of chart demonstration screens use hardcoded data arrays defined directly in component classes (e.g., the D3 chart's Germany/USA/France values, the ECharts stacked area chart's marketing channel data, the Player's playlist). This is consistent with the application's role as a UI showcase.

3. Nebular Theme Service — NbThemeService.getJsTheme() is a data source for all chart and widget styling. It emits a JavaScript object containing color tokens, font settings, and component-specific variables that components use to construct their visual configurations.

4. Browser Native APIs — The Geolocation API provides coordinates for the Search Map screen. The HTMLAudioElement streams audio from Spotify CDN URLs for the Player widget.

10.2 State Management Approach

The application uses Angular class property state exclusively — there is no NgRx store, Akita, or other global state management library. State is managed at three levels:

• Component-local state — Boolean flags (flipped, revealed, isInputShown, loading), numeric values (value, solarValue), and data arrays (messages, cameras, contacts) are held as class properties on the component instance.
• Service-mediated shared state — NbThemeService acts as a shared reactive state bus for the active theme. LayoutService acts as a shared event bus for layout resize events. NbSidebarService manages sidebar visibility.
• URL state — Angular's router manages navigation state. No URL query parameters are used for data filtering in the assessed screens.

10.3 Data Transformation Pipeline

The typical data transformation pipeline for a data-driven screen is:

Abstract Service Observable
  → Container Component subscription (takeWhile / takeUntil)
    → Component state property assignment
      → @Input() binding to presentational child component
        → Child component constructs ECharts/Leaflet option object
          → Chart directive renders to canvas/SVG

For theme-driven styling, the pipeline is:

NbThemeService.getJsTheme() Observable (with delay(1))
  → Component subscription
    → Theme variable extraction (config.variables.*)
      → Chart option object construction (inline or via setOptions())
        → [options] binding triggers ECharts re-render

10.4 Caching and Persistence

No client-side caching layer is present. No TanStack Query, SWR, Apollo Client, or similar data-fetching library with cache management is used anywhere in the assessed screens. Each component instantiation triggers fresh service calls with no deduplication or stale-time management.

No client-side persistence is used. No localStorage, sessionStorage, cookies, or IndexedDB are read or written by any assessed component. All state is ephemeral and resets on navigation away or page refresh.

The browser's native HTTP cache will cache static assets (GeoJSON files, map tiles, audio files) according to the cache headers returned by their respective servers, but this is not controlled by the application.

10.5 Cross-Screen Data Sharing

Cross-screen data sharing occurs through three mechanisms:

1. Shared Services — NbThemeService, LayoutService, NbSidebarService, and NbMenuService are application-scoped singletons that broadcast state changes to all subscribers regardless of which screen is active.

2. Parent-Child @Input() Bindings — Within a feature module, container components fetch data and pass it to child presentational components via @Input(). For example, ECommerceChartsPanelComponent fetches chart data and passes it to OrdersChartComponent and ProfitChartComponent.

3. Router Navigation — The PagesComponent menu configuration (MENU_ITEMS) defines the navigation structure. NbMenuService.navigateHome() provides a cross-screen navigation mechanism.

No shared global state store (NgRx, Akita, etc.) is used. Data is not shared between sibling feature modules.

11. Cross-Cutting Concerns

11.1 Error Handling Strategy

Observed pattern: Error handling is largely absent across the assessed screens. The dominant pattern is to subscribe to observables without providing an error callback or catchError operator.

Specific observations:

• DashboardComponent, ContactsComponent, TemperatureComponent, ElectricityComponent, VisitorsAnalyticsComponent, CountryOrdersComponent, SecurityCamerasComponent, EarningCardFrontComponent, and ProgressSectionComponent all subscribe to data observables without error handling. If the underlying service fails, the component silently remains in its loading/empty state.
• BubbleMapComponent fetches world.json via HttpClient without catchError; a 404 would leave the map without country polygons.
• CountryOrdersMapComponent fetches countries.geo.json without error handling.
• The SmartTableComponent uses window.confirm() for delete confirmation, which is a synchronous blocking call.

Inconsistency: No consistent error state UI pattern (error banners, retry buttons, toast notifications) is applied to data-loading failures. This is architecturally significant for any production deployment.

11.2 Authentication & Authorization

Observed pattern: No authentication or authorization logic is implemented within any of the 100 assessed component files. Every component explicitly notes that security is "delegated to Angular route guards at the router level."

The @nebular/auth (11.0.1) and @nebular/security (11.0.1) packages are present in package.json, indicating the infrastructure for authentication exists in the project. However, no route guard implementations, JWT handling, or session management are visible in the assessed screens.

[Not documented — WHO: Backend/security engineer or the developer who configured the routing module; WHAT: Are Angular route guards (CanActivate, CanLoad) applied to the /pages route group or any feature module routes? What authentication strategy (JWT, session cookie, OAuth) is used with @nebular/auth?; WHERE: Insert answer in Section 11.2: Authentication & Authorization and Section 12: Architecture Decisions]

11.3 Loading & Empty States

Observed pattern: Loading and empty state handling is inconsistent across screens.

• No loading state: The majority of data-driven components (e.g., DashboardComponent, ContactsComponent, TemperatureComponent) have no explicit loading spinner, skeleton, or placeholder. The template renders with undefined data until the observable emits.
• Implicit empty state: Components using *ngFor on undefined arrays will render nothing, which may appear as a blank area to the user.
• Explicit loading state (spinner screens): The SpinnerComponent, SpinnerInButtonsComponent, and SpinnerInTabsComponent demonstrate loading state patterns using setTimeout simulations, but these are showcase components, not applied to real data-loading flows.
• No error state UI: No screen defines a user-facing error message or retry mechanism for failed data loads.

11.4 UI Component Patterns

Observed pattern: The Nebular component library (@nebular/theme) is the universal UI primitive layer. Across all 100 screens, the following Nebular components appear consistently:

• nb-card, nb-card-header, nb-card-body, nb-card-footer — Card layout containers
• nb-icon — Icon rendering (Eva Icons, Ionicons, Font Awesome)
• nb-menu — Sidebar navigation
• nb-tabset, nb-tab — Tab containers
• nb-dialog, nb-window, nb-toastr — Overlay services
• nb-spinner — Loading indicators
• nb-progress-bar — Progress visualization
• nb-calendar, nb-calendar-range — Date pickers
• nb-select, nb-option — Dropdown selects
• nb-chat, nb-chat-form — Chat UI

CSS naming convention: All custom components use the ngx- selector prefix, enforced by the ESLint rule @angular-eslint/component-selector with prefix: "ngx".

SCSS: Component-scoped SCSS files are used universally. No CSS-in-JS or utility-class framework (Tailwind, etc.) is used.

11.5 Validation Approach

Observed pattern: Form validation is not a prominent concern in the assessed screens. The FormLayoutsComponent, FormInputsComponent, and NebularFormInputsComponent are static showcases with no form submission logic. The WindowFormComponent contains uncontrolled inputs with no ngModel or ReactiveFormsModule bindings. The DialogNamePromptComponent captures input via a template reference variable without validation.

No Validators, FormGroup, FormControl, or ReactiveFormsModule patterns are observed in the assessed component classes.

[Not documented — WHO: Frontend developer responsible for the forms module; WHAT: Are reactive forms with validation used in any non-showcase form screens not included in this assessment?; WHERE: Insert answer in Section 11.5: Validation Approach]

11.6 Logging & Observability

Observed pattern: AnalyticsService is present in the @core/utils module and wraps a declare const ga: any global reference (Google Analytics Universal Analytics). However, AnalyticsService.enabled is hardcoded to false, meaning no analytics events are tracked in the assessed code. The service is referenced in TrafficChartComponent's service imports but is not injected into any assessed component.

No observability SDK identified in available project context beyond the disabled AnalyticsService. The package.json manifest contains no error tracking (Sentry, Bugsnag, Rollbar), APM (Datadog, New Relic), or structured logging packages.

[Not documented — WHO: DevOps or infrastructure engineer; WHAT: Is any error tracking, APM, or logging service configured at the deployment level (e.g., via environment variables or a separate configuration file not included in the assessed code)?; WHERE: Insert answer in Section 11.6: Logging & Observability]

11.7 Performance Patterns

Observed patterns applied consistently:

• LayoutService debounced resize bus — All ECharts-based chart components subscribe to LayoutService.onSafeChangeLayoutSize(), which applies debounceTime(350) before triggering echartsIntance.resize(). This prevents excessive canvas reflow during sidebar animations or window resizing. Observed in: TrafficChartComponent, ElectricityChartComponent, CountryOrdersChartComponent, OrdersChartComponent, ProfitChartComponent, VisitorsAnalyticsChartComponent, VisitorsStatisticsComponent, StatsAreaChartComponent.

• ECharts sampling: 'average' — Line series in TrafficChartComponent and StatsAreaChartComponent use sampling: 'average' to downsample data when there are more points than pixels.

• forkJoin for parallel data loading — ContactsComponent, TemperatureComponent, VisitorsAnalyticsComponent, and ElectricityComponent use forkJoin to minimize total load time.

• trackByDate in TrafficFrontCardComponent — A trackBy function is provided for the traffic list *ngFor, preventing unnecessary DOM re-creation on data updates.

• ChangeDetectionStrategy.OnPush in IconsComponent — The only screen in the assessment that explicitly applies OnPush change detection, appropriate given its static data.

Patterns notably absent: OnPush change detection is not applied to any other component in the assessment, including components with frequent updates (e.g., EarningCardFrontComponent polling at 200ms). No virtual scrolling is used for any list.

11.8 Missing or Not Observed

The following cross-cutting concerns are architecturally significant by their absence:

12. Architecture Decisions

AD-1: Nebular as the Primary UI Component Library

• Context: The application requires a comprehensive set of Angular UI components including layout primitives, form controls, overlays, navigation, and a theming system.
• Decision: Nebular (@nebular/theme 11.0.1) is used as the sole UI component library for all structural and interactive UI elements.
• Rationale: Nebular provides a complete design system with built-in multi-theme support, which directly enables the application's four-theme requirement. It also provides the NbThemeService reactive theming bus that all chart and widget components depend on. As the application is an Akveo product, Nebular is the natural choice.
• Consequences: All UI components are tightly coupled to Nebular's API and theming model. Migrating to a different component library would require rewriting the theming integration across all chart and widget components. Nebular's version must be kept in sync with Angular's version.

AD-2: Abstract Service Classes as Data Layer Contracts

• Context: The application needs to demonstrate UI components with realistic data while remaining structurally ready for real backend integration.
• Decision: All data-fetching contracts are defined as abstract Angular classes (e.g., SolarData, UserData, ElectricityData). Concrete implementations are registered in module providers and injected at runtime.
• Rationale: This pattern decouples UI components from their data sources entirely. A developer can swap mock implementations for real HTTP services by changing only the module provider registration, without modifying any component code.
• Consequences: The concrete service implementations are not included in the assessed code, making it impossible to document actual HTTP endpoints, status code handling, or database queries. Any production deployment requires implementing and registering concrete services for all abstract classes.

AD-3: Shell Components with Router Outlet for Feature Grouping

• Context: The application has 10+ feature sections, each containing multiple sub-screens. A clean URL hierarchy and lazy-loading boundaries are needed.
• Decision: Each feature group (Charts, Forms, Maps, Tables, Modal Overlays, Extra Components, Editors, UI Features, Miscellaneous) is represented by an empty shell component containing only <router-outlet>. The shell component has no logic, no state, and no data fetching.
• Rationale: This pattern creates clean lazy-loading module boundaries, allows child routes to be independently navigable, and keeps feature module code isolated. The shell component serves as a named route anchor without adding any rendering overhead.
• Consequences: Navigation to a feature group root URL (e.g., /charts) renders a blank page unless a default child route redirect is configured. The shell components add a layer of component instantiation with no functional benefit beyond routing.

AD-4: Apache ECharts as the Primary Charting Engine

• Context: The application requires diverse chart types: area charts, bar charts, pie charts, donut charts, stacked area charts, horizontal bar charts, and geographic bubble maps.
• Decision: Apache ECharts (via ngx-echarts 4.2.2) is the primary charting library, used for the majority of charts across the Dashboard, E-Commerce, and Charts modules.
• Rationale: ECharts supports all required chart types in a single library, provides a declarative option object API that integrates naturally with Angular's change detection, and supports the sampling: 'average' performance optimization for large datasets. Chart.js and ngx-charts are used for specific demonstration screens but are not the primary engine.
• Consequences: ECharts is accessed both via the ngx-echarts directive and directly as a global (echarts.graphic.LinearGradient), creating an implicit dependency on the global echarts object. The ngx-echarts version (4.2.2) is pinned to an older ECharts 4.x API, which may limit access to newer ECharts 5.x features.

AD-5: RxJS takeWhile Pattern for Subscription Lifecycle Management

• Context: Components subscribe to long-lived observables (theme changes, media query changes, data streams) and must unsubscribe on destruction to prevent memory leaks.
• Decision: The dominant pattern is a boolean alive flag initialized to true, used as the predicate for takeWhile(() => this.alive), set to false in ngOnDestroy().
• Rationale: This pattern is simple to implement and avoids storing Subscription references. It is consistently applied across the majority of components.
• Consequences: The takeWhile predicate is evaluated on every emission, which is slightly less efficient than takeUntil(destroy$). More critically, the subscription completes only on the next emission after alive is set to false, meaning a component that is destroyed between emissions may briefly process one more value. A Subject + takeUntil pattern would be more reliable. Additionally, ProgressSectionComponent has a bug where ngOnDestroy sets alive = true instead of false, permanently preventing cleanup.

AD-6: NbThemeService as the Runtime Theming Bus

• Context: The application supports four themes (Default, Dark, Cosmic, Corporate) and requires all visual components to adapt when the theme changes at runtime.
• Decision: All chart components, map components, and widgets subscribe to NbThemeService.getJsTheme() in ngAfterViewInit (with a delay(1)) to receive theme-specific color variables and construct their visual configurations.
• Rationale: Centralizing theme variables in NbThemeService ensures a single source of truth for all visual tokens. The delay(1) pattern ensures the DOM is fully rendered before ECharts attempts to mount, avoiding race conditions.
• Consequences: Every chart component has a mandatory async initialization path through NbThemeService. If the theme service is slow or unavailable, charts render as empty containers. Theme changes trigger full option object reconstruction and chart re-render across all active chart components simultaneously.

AD-7: Hardcoded Static Data for Chart Demonstrations

• Context: The Charts module and many E-Commerce sub-components need to display realistic-looking data without a live backend.
• Decision: Chart demonstration screens (D3, ECharts, Chart.js) use hardcoded static arrays defined directly in component classes. Some screens (Chart.js) use Math.random() to generate data on each instantiation.
• Rationale: Static data eliminates the need for mock service infrastructure for pure demonstration screens, keeping those components simple and self-contained.
• Consequences: The hardcoded data (Germany/USA/France values, marketing channel figures) has no semantic meaning and cannot be updated without modifying component source code. The Math.random() pattern in ChartjsBarHorizontalComponent means chart data changes on every theme switch, which is a confusing side effect.

AD-8: Direct DOM Manipulation for Third-Party Editor Integration

• Context: TinyMCE 4 and CKEditor 4 require direct DOM access to initialize their editor instances.
• Decision: TinyMceComponent uses ElementRef.nativeElement and ngAfterViewInit to pass the host DOM element to tinymce.init(). CKEditor is integrated via the ng2-ckeditor Angular wrapper.
• Rationale: Both TinyMCE and CKEditor 4 are DOM-centric libraries that predate Angular's component model. Direct DOM access is the only viable integration approach for these libraries.
• Consequences: TinyMCE is accessed as a global variable (window.tinymce), bypassing Angular's module system and making it impossible to verify library integrity via Subresource Integrity. The keyup-only content emission in TinyMceComponent means paste-only actions do not propagate to the parent. The emitted HTML is raw and must be sanitized before storage or rendering.

AD-9: LayoutService as a Debounced Resize Event Bus

• Context: ECharts instances must call .resize() when their container dimensions change (e.g., sidebar toggle, window resize). Multiple chart components on the same page need to respond to the same resize event.
• Decision: A shared LayoutService with a Subject-based layoutSizeChange$ observable, wrapped with shareReplay({ refCount: true }) and debounceTime(350), is used as a centralized resize event bus.
• Rationale: Centralizing resize events prevents each chart component from independently listening to window resize events. The debounceTime(350) prevents excessive .resize() calls during animated layout transitions. shareReplay ensures all subscribers receive the same debounced event without redundant upstream subscriptions.
• Consequences: All chart components are coupled to LayoutService. The shareReplay({ refCount: true }) configuration without an explicit bufferSize defaults to replaying 1 value to new subscribers, which may cause a chart to resize immediately on subscription even if no layout change has occurred recently. (inferred from RxJS shareReplay behavior — verify against the LayoutService source and confirm whether the replay behavior is intentional)

AD-10: SVG-Based Custom Widgets with LocationStrategy URL Fragment Fix

• Context: The TemperatureDraggerComponent and RoomSelectorComponent use SVG <clipPath> and <pattern> elements that reference fragment IDs via CSS url(#id). Angular's router changes the browser URL, breaking bare fragment references.
• Decision: Both components inject Angular's Location and LocationStrategy services to construct url(baseHref + path + id) strings that remain valid regardless of the current route.
• Rationale: SVG fragment references are relative to the document URL. When Angular's router navigates, the URL changes and bare url(#id) references break. Prepending the full path is the standard workaround.
• Consequences: The getUrlPath(id) method is called from the template on every change detection cycle without memoization, calling location.path() repeatedly. This is a minor performance concern. The fix is also required for hash-based routing strategies.

13. Quality Attributes

14. Risks & Technical Debt

15. Glossary

15.1 Domain Terms

15.2 Architecture Terms