# Current implementation architecture

Authoritative implementation checkpoint: 26 September 2026. This chapter supersedes conflicting target-state descriptions in earlier chapters. User documentation: [English portal manual](manuals/user-manual-en.html), [Español](manuals/user-manual-es.html), [Android integration](manuals/android-integration-en.html) and [Linux integration](manuals/linux-integration-en.html).

## Runtime topology

```text
Browser -- HTTPS/WSS 5102 --> TMS.Portal / Kestrel MVC + remote relay
                                  | operator cookie/session + antiforgery
                                  | authenticated gRPC / HTTP/2 loopback 15101
                                  v
                              TMS.DataService -- Dapper --> SQL Server 2022 or PostgreSQL 17
                                  ^
                                  | authenticated gRPC
Android/Linux -- MQTTS 5883 --> TMS.Connectivity.Mqtt
Android/Linux -- HTTPS 5102 --> enrollment, IoT, package and parameter endpoints
```

Local development uses HTTP 15100, HTTPS 15102 and MQTTS 18883. Windows deployments use three LocalService services and SQL Server. Linux deployments use three hardened systemd services and PostgreSQL. The provider is selected by `DatabaseProvider`; the same DataService binary supports both. Internal gRPC is cleartext HTTP/2 restricted to loopback and must never be exposed publicly. AWS IoT, Redis, separate dispatcher processes and multiple portal nodes are not deployed.

## Project responsibilities

| Component | Responsibility |
| --- | --- |
| TMS.Portal | MVC/Razor, bilingual UI/manuals, account recovery/MFA, HTTPS device endpoints and Android remote viewer/relay |
| TMS.Contracts | Protobuf RPC contracts and generated types |
| TMS.DataService | Authorization, customer/device use cases, audit, application/parameter/location and IoT lifecycle |
| TMS.DBAccess | Parameterized Dapper persistence, SQL Server/PostgreSQL provider adaptation and transactional policy |
| TMS.Connectivity.Mqtt | Mutual-TLS broker, per-device topic authorization, telemetry, presence, command dispatch/results |
| TMS.Hosting | Service hosting, logging and protected configuration |
| TMS.ServerSetup / TMS.Setup | Windows installer, DPAPI secrets, service configuration and migrations |
| Android UIC Home | Launcher, MQTT agent, telemetry, operations, applications, parameters and remote assistance |
| Linux xTMSAgent | A10 communications/bootstrap, MQTT agent, payment-app supervisor/bridge and native package operations |

## Operator identity and customer boundary

The SQL-backed identity store uses BCrypt passwords, server sessions and optional TOTP MFA with single-use recovery codes. Password recovery supports SMTP or AWS SES; reset links are hashed, single-use and expire after 30 minutes. Security changes are audited without secret material.

SuperAdmins can manage all customers, SuperAdmins, model catalog and onboarding. Customer administrators/users are restricted to memberships and feature-level Read/Write roles for their own customer. Portal controllers and DataService both enforce customer/device scope; hiding navigation is not authorization.

## Device trust and enrollment

HTTPS and MQTT validate the server certificate. A separate IoT CA issues per-device client certificates. MQTT requires the current Device Secret, assignment epoch, exact non-revoked certificate fingerprint and own-topic policy.

A terminal cannot register itself in the fleet. SuperAdmin first onboards its exact manufacturer serial and portal model. Android currently uses an authorized private enrollment import for test/debug. Linux xTMSAgent uses a protected customer bootstrap to claim the existing serial, stores the unique returned secret with mode `0600`, deletes the bootstrap and provisions its IoT key/certificate. The first successful MQTT admission marks the certificate Provisioned and closes further downloads. See chapters 29 and 33.

## Persistence, commands and applications

SQL is authoritative for customers, users/roles, audit, devices, presence, commands, deployments, application metadata, parameters, IoT history and location history. SQL Server and PostgreSQL expose the same application behavior; a deployment chooses one provider and cannot point one database at both engines. Application binaries remain in private filesystem storage and must be backed up with the selected database.

Commands are durable, scoped to customer/device/assignment and delivered at least once. Agents persist command IDs and outgoing results; SQL commit receipts complete the device outbox. Queued/Dispatched is not execution success.

One logical application version can contain multiple immutable model-specific artifacts. The deployment resolves the correct artifact per target. Android APKs are parsed and signature-verified in process. Native A10 `prodapp.tarball.tar.gz` packages are structure/hash checked by the portal and vendor-signature checked by the terminal. Android and A10 install/uninstall are implemented; successful A10 changes reboot and report refreshed inventory. Malware scanning remains outstanding.

## Parameters

The current saved schema, catalogs, templates and device JSON are compiled on request. Group metadata controls portal layout. Templates/copies use saved values. Android exposes parameters through a read-only provider; A10 uses a local file bridge. Scheduled parameter push, secret-value storage and a separate payment-app applied receipt are not implemented.

## Telemetry and location

Current telemetry includes portal and reported model, OS/version, agent version, uptime, capabilities, free/total storage, available/total memory, network interfaces, observed public IP and user application inventory. Android additionally reports battery/SIM information when firmware permits. A10 inventory reads `userappl/cfg/appname.txt` and `version.txt`.

Valid reported location is stored as current state and history. A new history point is created after at least 100 metres. Operators with Device Write can set address/map/coordinate location only when no valid reported coordinate exists; telemetry always takes precedence. Address search is server-proxied, cached and rate-limited. See chapter 34.

## Android and Linux runtime

UIC Home 3.9.14-dev uses a sticky foreground service, reconnect logic and bounded wake locks. Battery exemption/vendor power qualification remains necessary. Messages can wake an unlocked display; remote capture requires local approval and accessibility input. Sessions are bounded, memory-only and not recorded.

xTMSAgent starts CommServer before enrollment, allowing F2 network configuration on a new A10-T. It reports generic portal model and complete device model separately, supervises the payment app, uses durable MQTT spools and coordinates unsafe operations through payment-app status. Remote desktop is not implemented for Linux. Official A10-T field-install instructions remain pending.

## Portal operations and records

The portal includes customer/SuperAdmin administration, customer users/roles, profile/password/MFA, audit log, MQTT diagnostics, device search/groups/tags, app library with per-version/application deletion rules, scalable deployment targeting, task grids/details, parameter schema/catalog/template/device workspaces, session-expiry dialogs and bilingual help.

Device details show telemetry, applications, operations, diagnostics, parameters, map/current/history location and manual positioning when eligible. Audit visibility is global for SuperAdmins and customer-scoped for customer administrators.

## Remaining work and evidence limits

Outstanding: production Android enrollment distribution, official A10-T installation procedure, automatic IoT renewal/CA rollover, malware scanning, multi-node relay/session routing, fleet-scale/load/restore qualification, scheduled parameter push, app-applied parameter receipts and Linux remote desktop.

The SQL Server suite has passed 239 clean integration checks plus IoT/package/Android-specific checks. PostgreSQL installation, migration, super-admin login, customer creation, customer-admin login, scoped page access and MQTT status persistence have also been exercised on Ubuntu. NEWPOS NEW9810, NEXGO N82 and UIC A10-T have been exercised with the portal. This evidence does not certify every firmware, carrier network or unattended production fleet.