ngx-admin

Architecture Overview

April 2026

3. Document Roadmap

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

4. Executive Summary

ngx-admin is a feature-rich Angular-based administrative dashboard application built on the Nebular UI component library. The application serves as both a production-ready admin panel template and a comprehensive component showcase, providing end users with dashboards for IoT/smart-home monitoring, e-commerce analytics, data visualization, form management, map exploration, and rich-text editing. Its primary users are developers who adopt it as a starting point for building Angular admin interfaces, as well as end users of applications built on top of it.

The application is structured as a single-page application (SPA) using Angular 15 with a module-based architecture. Navigation is managed entirely by the Angular Router, with feature sections organized into route groups (/dashboard, /e-commerce, /forms, /tables, /charts, /maps, /extra-components, /modal-overlays, /ui-features, /editors, /miscellaneous). The Nebular UI framework (@nebular/theme) provides the design system, theming engine, layout components, and overlay services. Data visualization is handled by a combination of Apache ECharts (via ngx-echarts), Chart.js, D3.js, and @swimlane/ngx-charts. Interactive maps are powered by Leaflet (via @asymmetrik/ngx-leaflet) and the Angular Google Maps integration.

The most significant architectural characteristic of ngx-admin is its abstract service layer: all data-fetching contracts are defined as Angular abstract classes, with concrete implementations injected via the Angular dependency injection system. This pattern cleanly separates the UI from the data source, allowing the demo application to use in-memory mock services while enabling production adopters to substitute real HTTP-backed implementations. A second defining characteristic is the Nebular theming system, which drives not only UI component appearance but also chart colors, map styles, and responsive breakpoint behavior — all components subscribe to NbThemeService to remain synchronized with the active theme.

This Architecture Overview covers 100 screens of the ngx-admin application. The screens assessed and their routes are:

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

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

Generated by DocAgent — 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. Maintainability — The abstract service pattern and Nebular theming system are applied uniformly, enabling developers to swap data sources and themes without modifying UI components.
2. Extensibility — The router-shell pattern and Angular DI system allow new feature sections and data providers to be added without modifying existing components.
3. Visual Consistency — All components subscribe to NbThemeService, ensuring that theme changes propagate uniformly across charts, maps, UI components, and layout elements.
4. Responsiveness — Breakpoint-aware layout decisions are made consistently using NbMediaBreakpointsService, ensuring the UI adapts to different viewport sizes.
5. Correctness of Subscription Lifecycle — Preventing memory leaks from RxJS subscriptions is a recurring concern addressed (with varying consistency) across all data-fetching components.

6. System Context

6.1 System Boundary Description

The ngx-admin application is a client-side Angular SPA. Everything inside the system boundary is JavaScript/TypeScript code running in the user's browser. The system boundary encompasses the Angular application bundle, the Nebular UI framework, all charting libraries, and the Angular Router. Outside the boundary are: the backend API services that concrete *Data service implementations would call (not included in the assessed code), external CDNs for editor libraries, external tile servers for maps, and the Google Maps Platform.

[Diagram: System Context — show the ngx-admin Angular SPA as a central box; connect it to: Backend API (outbound, HTTPS/REST, data for dashboards), OpenStreetMap Tile Server (outbound, HTTPS, map tiles), Google Maps Platform (outbound, HTTPS/JS SDK, geocoding and map rendering), Spotify CDN (outbound, HTTPS, audio preview files), CKEditor CDN (outbound, HTTPS, editor script), TinyMCE Assets (local static, HTTP, editor skin/plugins), External Media CDNs (outbound, HTTPS, chat demo images and GIFs)]

6.2 External Interfaces

7. Solution Strategy

7.1 Technology Stack

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

7.2 Top-Level Decomposition

The application is organized as an Angular module-based SPA with a hierarchical route structure. The top-level PagesComponent acts as the authenticated shell, rendering the sidebar navigation (nb-menu) and a <router-outlet> for feature modules. Feature sections are organized as route groups, each with a shell component that contains only a <router-outlet>:

/pages
  /dashboard        → DashboardComponent (shell) → child widgets
  /e-commerce       → ECommerceComponent (shell) → child widgets
  /forms            → FormsComponent (shell) → child screens
  /tables           → TablesComponent (shell) → child screens
  /charts           → ChartsComponent (shell) → child screens
  /maps             → MapsComponent (shell) → child screens
  /extra-components → ExtraComponentsComponent (shell) → child screens
  /modal-overlays   → ModalOverlaysComponent (shell) → child screens
  /ui-features      → UiFeaturesComponent (shell) → child screens
  /editors          → EditorsComponent (shell) → child screens
  /miscellaneous    → MiscellaneousComponent (shell) → child screens

The @theme directory contains globally shared layout components (Header, Footer, Search Input, TinyMCE wrapper) that are part of the application shell rather than any specific feature route.

7.3 Key Architectural Patterns

1. Abstract Service / Dependency Injection for Data — All data-fetching contracts are defined as Angular abstract classes (e.g., UserData, ElectricityData, CountryOrderData). Components depend on the abstract class; concrete implementations are registered in Angular modules. This is the primary data access pattern across all 100 assessed screens.

2. Router Shell Components — Feature sections use empty shell components (containing only <router-outlet>) to define route namespaces without adding any UI or logic overhead. Observed in: EditorsComponent, ExtraComponentsComponent, MapsComponent, TablesComponent, ChartsComponent, FormsComponent, ModalOverlaysComponent, UiFeaturesComponent, MiscellaneousComponent.

3. Theme-Reactive Components — Components subscribe to NbThemeService.getJsTheme() or NbThemeService.onThemeChange() to receive theme variables and update their visual state reactively. This pattern is applied to all chart components, the Dashboard, the Header, the Room Selector, and many widget components.

4. Presentational / Container Component Split — Data-fetching logic is concentrated in container components (e.g., CountryOrdersComponent, VisitorsAnalyticsComponent), while child components (e.g., CountryOrdersChartComponent, VisitorsStatisticsComponent) receive data via @Input() and emit events via @Output().

5. ECharts Partial Update Pattern — Chart components initialize the full ECharts options object on first load, then use echartsInstance.setOption() with only changed properties on subsequent data updates, avoiding full chart re-initialization.

6. forkJoin for Parallel Data Fetching — Multiple data sources required simultaneously are fetched in parallel using RxJS forkJoin, preventing partial renders. Observed in: ContactsComponent, ElectricityComponent, VisitorsAnalyticsComponent, TemperatureComponent, ChartsPanelComponent.

7.4 Approach to Quality Goals

8. Building Block View

[Diagram: Building Block View — show the following containers: Angular SPA (browser), with internal components: Pages Shell, Feature Modules (Dashboard, E-Commerce, Forms, Tables, Charts, Maps, Extra Components, Modal Overlays, UI Features, Editors, Miscellaneous), @theme Shell Components (Header, Footer, Search Input, TinyMCE), Core Data Services (abstract classes), Nebular UI Framework, ECharts/ngx-echarts, Leaflet/ngx-leaflet, Google Maps. Show dependency arrows from Feature Modules to Core Data Services, from all components to Nebular UI Framework, from chart components to ECharts, from map components to Leaflet and Google Maps.]

8.1 Level 1 — High-Level Containers

8.2 Level 2 — Component Breakdown

Dashboard Feature Module (/dashboard)

E-Commerce Feature Module (/e-commerce)

Maps Feature Module (/maps)

Modal Overlays Feature Module (/modal-overlays)

@theme Shell Components

8.3 Shared Building Blocks

9. Runtime View

9.1 Page Load and Data Hydration

Participants: Angular Router, Feature Shell Component, Container Component, Abstract Data Service, Concrete Data Service, NbThemeService, Template

Sequence:

1. User navigates to a feature route (e.g., /dashboard/electricity).
2. Angular Router matches the route and activates ElectricityComponent.
3. Angular's DI system injects ElectricityData (concrete implementation) and NbThemeService into the component constructor.
4. The constructor immediately calls forkJoin([electricityService.getListData(), electricityService.getChartData()]).
5. Both observables are subscribed to with takeWhile(() => this.alive).
6. Concurrently, NbThemeService.getJsTheme() is subscribed to; the current theme name is assigned to currentTheme.
7. The concrete service implementations execute their data retrieval (mock data or HTTP call).
8. When both forkJoin source observables complete, the subscriber fires: listData and chartData are assigned to component properties.
9. Angular's change detection detects the property assignments and re-renders the template with the populated data.
10. Child components (e.g., ElectricityChartComponent) receive data via @Input() bindings and render their visualizations.

Error path: If either observable in the forkJoin errors, the entire forkJoin terminates without emitting. No error callback is registered in the component; listData and chartData remain undefined. The template renders with empty/undefined bindings, likely showing a blank or broken UI with no user-facing error message.

[Diagram: Sequence — Page Load and Data Hydration: User → Router → ElectricityComponent constructor → forkJoin(getListData, getChartData) → Concrete Service → (data returned) → component properties assigned → change detection → template re-renders → ElectricityChartComponent receives @Input]

9.2 User Selects a Country on the Map

Participants: CountryOrdersMapComponent, CountryOrdersComponent, CountryOrderData (abstract service), CountryOrdersChartComponent

Sequence:

1. User clicks a country polygon on the Leaflet map rendered by CountryOrdersMapComponent.
2. The Leaflet click event handler fires; selectFeature(featureLayer) is called.
3. The previously selected country's style is reset; the clicked country's style is updated to the selection highlight.
4. selectEvent.emit(featureLayer.feature.properties.name) emits the country name string to the parent.
5. CountryOrdersComponent.selectCountryById(countryName) is called.
6. this.countryName = countryName is set.
7. countryOrderService.getCountriesCategoriesData(countryName) is called; the returned observable is subscribed to with takeWhile(() => this.alive).
8. The concrete service returns order data for the selected country.
9. this.countryData = data is assigned.
10. Angular's change detection propagates countryName and countryData to CountryOrdersChartComponent via @Input() bindings.
11. CountryOrdersChartComponent.ngOnChanges() fires; echartsInstance.setOption() is called with the new series data (partial update).
12. The chart re-renders with the selected country's data.

Error path: If getCountriesCategoriesData() errors, no error handler is present; countryData remains at its previous value. The chart continues to display the previously selected country's data without any user notification.

[Diagram: Sequence — User Selects a Country on the Map]

9.3 User Changes the Application Theme

Participants: HeaderComponent, NbThemeService, All subscribed components (chart components, DashboardComponent, RoomsComponent, RoomSelectorComponent, TypographyComponent, etc.)

Sequence:

1. User selects a new theme from the theme dropdown in HeaderComponent.
2. HeaderComponent.changeTheme(themeName) calls NbThemeService.changeTheme(themeName).
3. NbThemeService updates its internal theme state and emits on onThemeChange() and getJsTheme() observables.
4. All components subscribed to NbThemeService.getJsTheme() receive the new theme configuration object.
5. Chart components (e.g., ElectricityChartComponent, ProfitChartComponent) call their setOptions(eTheme) method, rebuilding the full ECharts options object with new theme colors.
6. The ECharts directive detects the options binding change and re-renders the chart with the new color scheme.
7. DashboardComponent updates statusCards by looking up the new theme name in statusCardsByThemes.
8. RoomSelectorComponent updates hideGrid based on whether the new theme is 'corporate'.
9. HeaderComponent updates currentTheme via the onThemeChange() subscription.
10. All Nebular UI components automatically re-render with the new theme's CSS custom properties.

Error path: If a component's theme subscription errors, that component's visual state may become inconsistent with the active theme. No error handling is present in any observed theme subscription.

[Diagram: Sequence — User Changes the Application Theme]

9.4 User Submits a Period Change on a Dashboard Widget

Participants: TrafficCardsHeaderComponent, TrafficRevealCardComponent, TrafficListData (abstract), TrafficBarData (abstract), TrafficFrontCardComponent, TrafficBarChartComponent

Sequence:

1. User clicks a period button (e.g., 'month') in TrafficCardsHeaderComponent.
2. changePeriod('month') is called; type is updated locally.
3. periodChange.emit('month') fires, propagating the new period to TrafficRevealCardComponent.
4. TrafficRevealCardComponent.setPeriodAngGetData('month') is called.
5. period is updated to 'month'.
6. getTrafficFrontCardData('month') calls trafficListService.getTrafficListData('month'); result is subscribed to with takeWhile(() => this.alive).
7. getTrafficBackCardData('month') calls trafficBarService.getTrafficBarData('month'); result is subscribed to with takeWhile(() => this.alive).
8. Both services return data for the 'month' period.
9. trafficListData and trafficBarData are assigned.
10. Angular's change detection propagates the new data to TrafficFrontCardComponent and TrafficBarChartComponent via @Input() bindings.
11. Both child components re-render with the new period's data.

Error path: No error handling is present on either subscription. If either service call fails, the corresponding child component retains its previous data without any user notification.

[Diagram: Sequence — User Submits a Period Change on a Dashboard Widget]

9.5 Modal Dialog Opens and Returns a Value

Participants: DialogComponent, NbDialogService, DialogNamePromptComponent, NbDialogRef

Sequence:

1. User clicks the "Name Prompt" trigger button in DialogComponent.
2. open3() is called; NbDialogService.open(DialogNamePromptComponent) is invoked.
3. Nebular creates a dialog overlay, instantiates DialogNamePromptComponent, and injects a NbDialogRef instance into it.
4. The onClose observable is subscribed to: name => name && this.names.push(name).
5. The dialog renders with a text input and Cancel/Submit buttons.
6. User types a name and clicks Submit.
7. DialogNamePromptComponent.submit(name) calls this.ref.close(name).
8. Nebular destroys the dialog overlay and emits name on the onClose observable.
9. The subscription callback fires; if name is truthy, it is pushed to this.names.
10. Angular's change detection updates the names list in the DialogComponent template.

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

[Diagram: Sequence — Modal Dialog Opens and Returns a Value]

10. Data Flow & State Management

[Diagram: Data Flow — show abstract service classes receiving data from concrete implementations (mock or HTTP), flowing into container components, which pass data via @Input() to presentational components; show NbThemeService as a cross-cutting observable feeding into all chart and layout components; show user interactions flowing back up via @Output() events and method calls]

10.1 Data Sources

The application uses the following data sources, as evidenced across the 100 assessed screens:

10.2 State Management Approach

ngx-admin uses component-local state as its primary state management approach. There is no global state store (no NgRx, Akita, or similar). State is managed as class-level properties on Angular component instances. The following patterns are observed:

• Container components hold fetched data as class properties (e.g., listData, chartData, cameras).
• Presentational components receive data exclusively via @Input() bindings and emit events via @Output().
• UI toggle state (e.g., flipped, revealed, isSingleView, loading) is held as simple boolean class properties.
• Period/filter selection (e.g., type, period) is held as string class properties, often with a corresponding types array for the available options.
• Theme state is held in NbThemeService (Nebular's internal state) and accessed reactively via observables.
• URL state is not used for any observed screen state; navigating away and back resets all component state to defaults.

10.3 Data Transformation Pipeline

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

Abstract Service Observable
    → (forkJoin or direct subscribe)
    → Component class property assignment
    → Angular change detection
    → @Input() binding to child component
    → Child component ngOnChanges / ngAfterViewInit
    → ECharts setOption() / Leaflet layer update / template render

For theme-driven chart styling:

NbThemeService.getJsTheme()
    → config.variables.[namespace]
    → setOptions(eTheme) method
    → ECharts options object construction (with LinearGradient, color tokens)
    → [options] binding on echarts directive
    → Chart render

No data transformation libraries (e.g., lodash, date-fns) are directly imported in the assessed component files. Transformations are performed inline using native JavaScript array methods (map, filter, find, Math.round, parseInt).

10.4 Caching and Persistence

• No client-side caching layer is present. No TanStack Query, SWR, Apollo, or Angular HttpClient interceptor-based caching is observed across any of the 100 assessed screens.
• No client-side persistence is used. No localStorage, sessionStorage, cookies, or IndexedDB access is present in any assessed component.
• Browser HTTP cache applies to static asset fetches (GeoJSON files, map tiles) based on server-set cache-control headers.
• Each component instantiation triggers a fresh data fetch from the abstract service. Navigating away and back to a screen re-fetches all data.
• Theme state is held in NbThemeService's in-memory state and persists for the lifetime of the browser session (until page refresh).

10.5 Cross-Screen Data Sharing

Data is not shared between screens via a global store. The following mechanisms are used for cross-component data sharing within a screen:

• @Input() / @Output() bindings — Primary mechanism for parent-to-child data flow and child-to-parent event propagation within a screen.
• Shared abstract services — Multiple components on the same screen may inject the same abstract service (e.g., NbThemeService is injected by both container and child chart components).
• NbDialogRef / NbWindowRef — Used to pass data into and receive return values from overlay components.
• Angular Router — Navigation between screens; no URL parameters are used for state transfer in the assessed screens.

11. Cross-Cutting Concerns

11.1 Error Handling Strategy

Observed pattern: Across all 100 assessed screens, there is no consistent error handling strategy for observable subscriptions. The dominant pattern is the absence of error handling:

• forkJoin subscriptions in ContactsComponent, ElectricityComponent, VisitorsAnalyticsComponent, TemperatureComponent, and ChartsPanelComponent have no catchError operator and no error callback in .subscribe().
• Individual service subscriptions in TrafficComponent, ProgressSectionComponent, UserActivityComponent, StatsCardBackComponent, and StatsCardFrontComponent similarly have no error handling.
• The CountryOrdersMapService uses HttpClient.get() with no catchError; a 404 or network failure leaves the map blank with no user feedback.

Consequence: When a data service observable errors, the component silently retains its initial undefined state. No error message, toast notification, or fallback UI is shown to the user.

Exception: DialogComponent.open3() uses the onClose observable's truthy guard (name && this.names.push(name)) to handle the case where the dialog is cancelled (returns undefined), but this is a UI flow guard, not an error handler.

11.2 Authentication & Authorization

Observed pattern: No authentication or authorization logic is implemented within any of the 100 assessed component files. All components explicitly note that security is "delegated to Angular route guards at the routing module level."

The package.json includes @nebular/auth (11.0.1) and @nebular/security (11.0.1), indicating that authentication and role-based access control infrastructure is present in the application. However, the specific guard configurations, protected routes, and role definitions are not visible in the assessed screen documentation.

[Not documented — WHO: Backend/security lead; WHAT: Which routes have CanActivate guards applied, which roles are defined in @nebular/security, and how the auth token is stored and refreshed; WHERE: Section 11.2 Authentication & Authorization, after the paragraph above]

11.3 Loading & Empty States

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

• Most container components initialize data properties as undefined and rely on *ngIf or Angular's safe navigation operator (?.) in the template to prevent rendering before data arrives. The template files were not provided for most screens, so the exact implementation cannot be confirmed.
• No screen uses a dedicated loading spinner component at the container level (though SpinnerComponent and its variants are demonstrated as UI showcase screens).
• No screen implements a skeleton loader pattern.
• Error states are universally absent (see Section 11.1).

Inconsistency: ChatComponent initializes messages synchronously from a static array, so it has no loading state. SpinnerInButtonsComponent and SpinnerComponent use setTimeout to simulate loading states for demonstration purposes only.

11.4 UI Component Patterns

Observed pattern: The Nebular UI framework (@nebular/theme) is the exclusive UI component library used across all assessed screens. The following Nebular components appear consistently:

• Layout: nb-card, nb-card-header, nb-card-body, ngx-one-column-layout
• Navigation: nb-menu, nb-tabset, nb-tab
• Forms: nb-select, nb-option, nb-input (via nbInput directive), nb-datepicker
• Overlays: NbDialogService, NbWindowService, NbToastrService, NbPopover directive
• Data Display: nb-tree-grid, ng2-smart-table (third-party, Nebular-compatible)
• Icons: nb-icon (Eva icons), Ionicons font classes, Font Awesome font classes
• Calendar: NbCalendarComponent, NbCalendarDayPickerComponent, NbCalendarRangeComponent

The ngx- component selector prefix is enforced by ESLint (@angular-eslint/component-selector rule with prefix: "ngx"), ensuring all application-defined components are distinguishable from Nebular components.

11.5 Validation Approach

Observed pattern: Form validation is not implemented in any of the 100 assessed screens. The form showcase screens (FormLayoutsComponent, FormInputsComponent, NebularFormInputsComponent, ButtonsComponent, DatepickerComponent) are static demonstrations with no bound form controls or validation logic. WindowFormComponent renders uncontrolled inputs with no validation. DialogNamePromptComponent collects a name string with no length or format validation.

[Not documented — WHO: Frontend lead; WHAT: Whether Angular Reactive Forms or Template-Driven Forms with validation are used in any non-assessed screens; WHERE: Section 11.5 Validation Approach]

11.6 Logging & Observability

No observability SDK is identified in the available project context. The package.json manifest does not include any error tracking (e.g., Sentry), APM (e.g., Datadog, New Relic), or analytics (e.g., Google Analytics, Mixpanel) packages as dependencies. The AnalyticsService referenced in LayoutService wraps a ga global variable (Google Analytics Universal Analytics), but this service is not injected into any of the 100 assessed component files and its configuration is not visible in the assessed documentation.

11.7 Performance Patterns

The following performance patterns are consistently applied across the assessed screens:

• Debounced layout resize: LayoutService.onSafeChangeLayoutSize() applies debounceTime(350) before emitting layout change events. All ECharts chart components subscribe to this observable to trigger resizeChart(), preventing excessive resize calls during window drag operations. Applied in: OrdersChartComponent, ProfitChartComponent, ElectricityChartComponent, VisitorsAnalyticsChartComponent, EarningCardFrontComponent, VisitorsStatisticsComponent, CountryOrdersChartComponent, TrafficBarChartComponent.
• ECharts partial update: Chart components use echartsInstance.setOption() with only changed properties on data updates, rather than rebuilding the full options object. Applied in: CountryOrdersChartComponent, ProfitChartComponent, OrdersChartComponent, EarningCardFrontComponent, TrafficBarChartComponent.
• shareReplay in LayoutService: The layoutSizeChange$ Subject uses shareReplay({ refCount: true }), multicasting layout events to all chart subscribers without re-executing the source.
• ChangeDetectionStrategy.OnPush in IconsComponent: The only component in the assessed set that explicitly applies OnPush change detection, appropriate given its static data initialized at construction time.
• forkJoin for parallel fetching: Prevents sequential waterfall data loading on screens requiring multiple data sources.

Inconsistency: The vast majority of components use Angular's default CheckAlways change detection strategy. ChangeDetectionStrategy.OnPush is applied only to IconsComponent across the 100 assessed screens.

11.8 Missing or Not Observed

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

• No centralized error handling: No global Angular ErrorHandler override, no catchError in HTTP interceptors, and no error callback in any observable subscription is observed. This is a significant gap for production use.
• No client-side caching: No HTTP interceptor caching, no service worker, and no data-fetching library cache is present. Every navigation to a screen re-fetches all data.
• No internationalization (i18n): No Angular i18n, ngx-translate, or similar library is present in package.json or referenced in any assessed component.
• No form validation framework: No Angular Reactive Forms validation, no Zod, no Yup, and no custom validators are observed in any assessed screen.
• No consistent loading state UI: No skeleton loaders, no global loading indicator (beyond pace-js in package.json), and no standardized empty-state component are observed.
• No rate limiting or debouncing on user-triggered data fetches: Period selector changes in TrafficRevealCardComponent, UserActivityComponent, and ChartsPanelComponent trigger immediate service calls with no debounce, allowing rapid successive calls.

12. Architecture Decisions

AD-1: Nebular as the Primary UI Component Library

• Context: The application requires a comprehensive Angular UI component library providing layout, theming, form controls, overlays, data display components, and an icon system.
• Decision: @nebular/theme (version 11.0.1) is used as the exclusive UI component library across all screens.
• Rationale: Nebular provides a cohesive design system (Eva Design System) with built-in multi-theme support, a reactive theming API (NbThemeService), and Angular-native components. The @nebular/auth and @nebular/security packages extend it with authentication and RBAC infrastructure.
• Consequences: All UI components are Nebular-styled, ensuring visual consistency. The application is tightly coupled to Nebular's API and release cycle. Migrating to a different UI library would require replacing all nb-* components across the entire codebase.

AD-2: Abstract Service Classes as Data Layer Contracts

• Context: The application serves as both a demo template (using mock data) and a starting point for production applications (requiring real HTTP backends).
• Decision: All data-fetching contracts are defined as Angular abstract classes (e.g., UserData, ElectricityData, CountryOrderData) in src/app/@core/data/. Components depend on the abstract class token; concrete implementations are registered in Angular modules.
• Rationale: This pattern cleanly separates the UI layer from the data source, enabling the demo to use in-memory mock services while allowing production adopters to substitute HTTP-backed implementations without modifying any component code.
• Consequences: The data layer is highly extensible and testable. However, the concrete implementations are not included in the assessed code, making it impossible to document actual API endpoints, HTTP status code handling, or database queries from the component documentation alone.

AD-3: Apache ECharts for Complex Data Visualizations

• Context: The application requires rich, interactive data visualizations including line charts, bar charts, pie charts, scatter maps, and geographic visualizations.
• Decision: Apache ECharts (via ngx-echarts) is the primary charting library for all complex visualizations. Chart.js (angular2-chartjs) and @swimlane/ngx-charts are also present but used for simpler or alternative chart types.
• Rationale: ECharts provides a comprehensive configuration-driven API that supports gradient fills, custom tooltips, animation, and geographic map rendering within a single library. The ngx-echarts Angular wrapper provides directive-based integration with [options] and [merge] bindings.
• Consequences: All ECharts chart components follow the same initialization pattern (ngAfterViewInit → theme subscription → setOptions() → echartsInstance.setOption() for updates). The global echarts object is accessed directly for echarts.graphic.LinearGradient, bypassing TypeScript type safety.

AD-4: RxJS forkJoin for Parallel Data Fetching

• Context: Several screens require multiple independent data sources to be available simultaneously before rendering (e.g., Contacts needs both contacts and recent users; Electricity needs both list data and chart data).
• Decision: forkJoin is used to combine multiple observables and wait for all to complete before updating component state.
• Rationale: forkJoin prevents partial renders where one data panel appears before another, ensuring a consistent initial state. It is semantically correct for one-shot HTTP-style observables.
• Consequences: If any single observable in the forkJoin errors or never completes, the entire combined observable fails silently (no error handler is present). This is a known risk documented in Section 14.

AD-5: takeWhile Pattern for Subscription Lifecycle Management

• Context: Angular components that subscribe to long-lived observables (theme changes, media query changes, data streams) must unsubscribe on component destruction to prevent memory leaks.
• Decision: The takeWhile(() => this.alive) pattern is used as the primary subscription cleanup mechanism across the majority of assessed screens. alive is a boolean class property initialized to true and set to false in ngOnDestroy().
• Rationale: This pattern avoids storing Subscription objects and calling .unsubscribe() explicitly, reducing boilerplate.
• Consequences: takeWhile evaluates the predicate on every emission, meaning the subscription is not immediately cancelled when ngOnDestroy fires — it completes on the next emission after alive becomes false. For high-frequency observables, this can result in one additional emission being processed after destruction. The takeUntil(destroy$) pattern (used in SecurityCamerasComponent and HeaderComponent) is more reliable and is the modern Angular recommendation. The inconsistency between the two patterns across the codebase is documented as technical debt in Section 14.

AD-6: Angular Router Shell Components for Feature Sections

• Context: The application has 11 top-level feature sections, each containing multiple child screens. A routing structure is needed that groups related screens without adding UI overhead at the section level.
• Decision: Each feature section has a dedicated shell component (e.g., EditorsComponent, MapsComponent, FormsComponent) whose template contains only <router-outlet></router-outlet> and whose class body is empty.
• Rationale: This pattern satisfies Angular's requirement that every route have an associated component while adding zero UI or logic overhead. It enables lazy loading of feature modules at the section level.
• Consequences: The codebase contains 11 near-identical shell components. Navigation structure is defined entirely in the routing module, not in the shell components themselves.

AD-7: Theme-Driven Chart Styling via NbThemeService

• Context: The application supports four Nebular themes (default, dark, cosmic, corporate). All chart visualizations must adapt their colors to the active theme.
• Decision: All ECharts chart components subscribe to NbThemeService.getJsTheme() and extract chart-specific color tokens from config.variables.[namespace] (e.g., config.variables.electricity, config.variables.profit, config.variables.countryOrders). No chart colors are hardcoded.
• Rationale: Centralizing color definitions in the Nebular theme configuration ensures that theme switches automatically propagate to all chart components without requiring individual component updates.
• Consequences: Chart components are dependent on specific theme variable namespaces being defined in the Nebular theme configuration. If a theme variable is missing or renamed, the chart will render with undefined colors. The delay(1) operator applied in several chart components' ngAfterViewInit is a workaround for Angular change detection timing issues.

AD-8: Leaflet for Interactive Geographic Maps

• Context: The application requires interactive world maps with country polygon rendering, selection, and hover states.
• Decision: Leaflet (via @asymmetrik/ngx-leaflet) is used for the Country Orders map and the basic Leaflet showcase. The CountryOrdersMapComponent fetches GeoJSON from a static asset and uses L.geoJSON() to render country polygons.
• Rationale: Leaflet is a mature, open-source mapping library with strong Angular integration via ngx-leaflet. It supports GeoJSON rendering, custom styling, and event handling natively.
• Consequences: The Leaflet map tile URL uses http:// (not https://), which will cause mixed-content blocking in production HTTPS environments. The attribution field is set to '...', violating OpenStreetMap's attribution requirements. Both are documented as risks in Section 14.

AD-9: NbDialogService and NbWindowService for Overlay Management

• Context: The application requires modal dialogs and floating window overlays with support for both component-based and template-based content, return values, and configurable backdrop/keyboard behavior.
• Decision: Nebular's NbDialogService and NbWindowService are used exclusively for all overlay management. Components and templates are passed as content; NbDialogRef and NbWindowRef are injected into overlay content components for lifecycle control.
• Rationale: These services provide a consistent, Angular-native overlay API that integrates with Nebular's theming and animation system. The onClose observable pattern enables clean return-value handling.
• Consequences: All overlay content components must be compatible with Nebular's DI-based instantiation. The NbDialogRef and NbWindowRef injection pattern requires overlay content components to be registered as Angular entry components (or use ivy component factories).

AD-10: Static In-Memory Data Services for Demo Content

• Context: The application is a demo template that must display realistic-looking data without requiring a backend server.
• Decision: Several services use static in-memory data: PlayerService (hardcoded playlist with Spotify CDN URLs), ChatService (hardcoded messages and bot reply rules), SmartTableData (hardcoded user records), and the BubbleMapComponent (hardcoded country population data).
• Rationale: Static data allows the demo to run without any backend infrastructure, making it immediately runnable after npm install.
• Consequences: The hardcoded Spotify CDN URLs in PlayerService are external dependencies that may break if Spotify removes the preview files. The ChatService.reply() method mutates the shared botReplies array directly, causing permanent session-level state corruption for bot reply URLs. Both are documented as risks in Section 14.

13. Quality Attributes

14. Risks & Technical Debt

15. Glossary

15.1 Domain Terms

15.2 Architecture Terms