upp-base -- Overview

upp-base is the platform services layer for all Angular applications in the UnPisPas monorepo. It sits between the raw framework primitives (Angular, Ionic, Cordova) and the application code, providing a unified set of services for HTTP communication, persistent storage, localisation, geolocation, device management, WebSocket connectivity, and UI feedback. Every Angular app in the workspace -- unpispas-pos (production POS) and upp-test (demos and testing) -- imports upp-base as its foundation.

Why upp-base exists

Without upp-base, every application and feature library would need to solve the same set of cross-cutting concerns independently: how to make HTTP requests that work both in a browser and on a Cordova device, how to detect online/offline state, how to store data persistently across platforms, how to manage the user session, and how to present consistent UI feedback. upp-base centralises these solutions into a single, well-tested library so that:

Feature libraries (under libs/feature/) can focus on domain logic instead of platform plumbing.
Applications remain thin shells that compose features and services.
Cross-platform behaviour (browser vs. Cordova/Capacitor) is abstracted behind service APIs, so consuming code never needs to branch on the runtime environment.

Architecture and service dependency graph

All services in upp-base are providedIn: 'root' singletons. They are tree-shakeable -- if an application does not inject a service, it will not be bundled. The services form a layered dependency graph:

Layer 0 (no upp-base deps)       platformService, clockService, eventbusService, kioskService, configService, storeService
                                       |
Layer 1 (depend on Layer 0)       httpService (uses platformService)
                                  toastService (uses languageService)
                                  languageService (uses httpService, storeService)
                                       |
Layer 2 (depend on Layer 1)       stateService (standalone, but consumed by many)
                                  adhocService (uses httpService, stateService, languageService, toastService, downloadService)
                                  viewService (uses platformService, httpService, stateService, languageService, configService)
                                       |
Layer 3 (depend on Layer 2)       identificationService (uses adhocService, storeService)
                                  geocodeService (uses httpService, platformService, alertService, toastService, languageService)
                                  deviceService (uses httpService, adhocService)
                                  uploadService / downloadService (uses httpService, languageService)
                                  logsService (uses clockService, adhocService, viewService)
                                  preloadService (uses stateService, viewService)

Understanding this graph helps you know which services are available at which point in the application lifecycle and which direction dependencies flow.

Module registration

The UppBaseModule must be imported in the root AppModule of every application. It bootstraps Ionic, Ionic Storage, and the Cordova plugin providers that the services depend on.

import { UppBaseModule } from '@unpispas/upp-base';

@NgModule({
  imports: [
    UppBaseModule,
    // ...
  ]
})
export class AppModule {}

What the module provides

Category	Items
Declarations	`modalInputComponent`, `modalAlertComponent`, `UiKioskBoardComponent`, `UiKioskInputDirective`, `modalAwayComponent`, `UiAwayComponent`
Exports	`UiKioskInputDirective`, `UiKioskBoardComponent`
Ionic modules	`IonicModule.forRoot()`, `IonicStorageModule.forRoot()`
Providers	`HTTP` (Cordova), `Network` (Cordova), `AndroidPermissions`, `Geolocation`, `provideHttpClient()`

Dependencies

Dependency	Role
`@unpispas/upp-defs`	Constants (`AppConstants`) and utilities (`GenericUtils`). Zero-dependency foundation layer.
`@ionic/angular`	UI primitives -- modals, toasts, loading indicators, platform detection.
`@ionic/storage-angular`	Key-value persistent storage (IndexedDB / SQLite).
`@awesome-cordova-plugins/*`	Cordova plugins: HTTP, Network, Geolocation, Android Permissions.
`@angular/common/http`	Angular `HttpClient` for browser-based HTTP requests.
`ngx-device-detector`	Device-type detection (mobile / tablet / desktop).
`@fingerprintjs/fingerprintjs`	Browser fingerprinting for device identification.

Injection tokens

Token	Type	Description
`langsPath`	`InjectionToken<string>`	Base path where language JSON files are stored. Must be provided by the consuming application so `languageService` knows where to load translation files from.
`Storage`	via `IonicStorageModule`	The Ionic Storage driver. Automatically configured by `IonicStorageModule.forRoot()`. Used internally by `storeService`.

Services at a glance

All services are providedIn: 'root' (singleton, tree-shakeable).

Service	Key role	When you will use it
`httpService`	Dual-mode HTTP transport (browser / Cordova), online/offline detection.	Rarely directly -- prefer `adhocService`.
`adhocService`	High-level request wrapper with automatic session, device, language, and place parameters.	Every time you call the backend.
`stateService`	Application state: access mode, session, device, place, expiry, readiness.	Login/logout flows, session management.
`viewService`	View orchestration: current screen, edit mode, panels, theme, kiosk, SW updates.	UI navigation, theme toggling, panel management.
`languageService`	i18n -- loads JSON translation modules, translates strings with placeholders.	All user-facing text.
`alertService`	Modal alert dialogs with text, checkbox, and radio inputs.	Confirmations, data entry prompts.
`toastService`	Toast notifications and loading indicators.	User feedback for success, errors, long operations.
`storeService`	Key-value persistent storage with per-key mutex (IndexedDB).	Persisting session data, caches.
`configService`	Per-element configuration backed by `localStorage`.	Small UI preferences (kiosk mode, theme).
`platformService`	Platform detection (iOS, Android, desktop, Cordova), theme, zoom, kiosk.	Adapting UI to the device.
`identificationService`	FingerprintJS-based device identification.	Device registration during login.
`kioskService`	Virtual keyboard management.	Touch-screen kiosk environments.
`geocodeService`	Geolocation, Google Geocoding, timezone, NearBy proximity.	Place setup, address resolution, proximity restriction.
`deviceService`	Local and remote WebSocket connections, printer/scale control.	Peripheral device integration.
`uploadService`	File upload via multipart `FormData`.	Attachment uploads.
`downloadService`	File download (server-proxied, base64-decoded).	Report and document downloads.
`clockService`	Periodic ticks (refresh, 1s, 10s, 1min).	Polling, scheduled UI updates.
`eventbusService`	Global event bus (emit / subscribe pattern).	Cross-component communication without direct dependencies.
`preloadService`	Background image preloading with Cache API.	Product images, media assets.
`logsService`	Client-side log collection and server flushing.	Debugging, support campaigns.

Importing

import { httpService, stateService, viewService, languageService } from '@unpispas/upp-base';

All public types, services, components, and directives are re-exported through libs/upp-base/src/index.ts. Import only what you need -- tree-shaking will remove the rest.

Typical application bootstrap flow

Understanding the order in which services initialise helps when debugging startup issues:

platformService waits for the Ionic platform to be ready, then detects the runtime environment (mobile/desktop/cordova) and initialises theme and kiosk mode from configService.
httpService starts onlineService, which immediately checks internet connectivity using either Cordova Network plugin events or browser online/offline events.
viewService subscribes to session expiry events and loads the initial language modules via languageService.
clockService starts its 250 ms base interval immediately on construction.
logsService overrides window.console on construction. If a logging campaign was previously active (stored in localStorage), it resumes automatically.
Application code sets stateService.device (via identificationService.DeviceId()), then performs login. On success, it sets stateService.session, stateService.Access, and viewService.View to transition the UI.
stateService.IsReady is set to true once all initialisation is complete, which triggers preloadService to begin background image loading.

Why upp-base exists​

Architecture and service dependency graph​

Module registration​

What the module provides​

Dependencies​

Injection tokens​

Services at a glance​

Importing​

Typical application bootstrap flow​