# Solution architecture

Authoritative implementation summary: 26 September 2026. The original target design is retained in `design-baseline/02-architecture-original.md`; chapter 30 gives the detailed current checkpoint and chapter 33 defines Android/Linux integration.

## Service boundary

```text
Operators -- HTTPS --> Portal + remote relay
                         |
                         | authenticated loopback gRPC
                         v
                    DataService --> SQL Server
                         ^
                         | authenticated loopback gRPC
Android/Linux -- MQTTS --> MQTT gateway
Android/Linux -- HTTPS --> enrollment, IoT, package and parameter endpoints
```

Portal (5102), MQTT (5883) and DataService are three independently hosted Windows services in the single-server package. DataService owns business authorization and SQL persistence. Portal owns operator HTTP/session behavior and the in-memory Android remote relay. MQTT owns mutual-TLS device admission, presence, telemetry ingest, command dispatch and result delivery. Internal gRPC (15101) is loopback-only.

Application bytes and parameters use authenticated HTTPS. MQTT carries durable bounded JSON envelopes. Android remote screen/input uses WSS and is separate from commands and package transfer. SQL and private artifact storage must be backed up together.

## Trust boundaries

| Boundary | Identity and enforcement |
| --- | --- |
| Operator to Portal | BCrypt password, optional TOTP MFA, cookie + server session, antiforgery |
| Portal/MQTT to DataService | Configured service key plus operator/device context; customer authorization repeated in DataService |
| Device to HTTPS | Bootstrap proof before enrollment or provisioned device identity for protected downloads |
| Device to MQTT | Device UUID/Secret, assignment epoch, per-device certificate fingerprint and exact topic scope |
| Browser to remote relay | Authenticated operator, scoped device ticket, origin/WSS checks and bounded session |

A terminal cannot create its portal inventory record. SuperAdmin first onboards the manufacturer serial, customer and portal model. Android test/debug provisioning imports its unique enrollment into app-private storage. Linux xTMSAgent claims the existing serial from a protected customer bootstrap. The first authenticated MQTT session closes the enrollment window.

## Data and durable work

SQL stores customers, users/roles, audit, device/model/assignment, latest telemetry, application inventory, presence, commands/deployments, application catalog, parameters, IoT certificate lifecycle and location history. Device commands are at-least-once and tied to the assignment epoch. Agents journal command IDs before effects and retain results until an application-level storage receipt arrives.

One logical application/version can have distinct NEWPOS, NEXGO and A10 artifacts. The portal resolves compatible artifacts per target. Android verifies APK metadata, signer, hash and installed state. A10 uses the native signed tarball; the portal verifies structure/hash and the device vendor API verifies its signature/install.

## Device platforms

Android UIC Home is a managed launcher and agent with a foreground MQTT service, hardware-flavor SDK adapters, application/parameter operations and consent-based remote assistance. Screen-off reliability depends on Android/vendor power policy. Preserve package identity, signer and app data during updates.

Linux xTMSAgent starts communications before TMS enrollment, provides F2 network configuration, supervises the payment application, reports complete model/resources/network/inventory and uses a file bridge for parameters/payment state. It installs/removes the A10 payment application and reboots after verified change. Remote desktop and official field-install instructions remain pending.

## Cross-cutting portal behavior

Customer scope and feature Read/Write roles are enforced in the service, including audit and location. The device view separates portal model from reported model, shows free/total storage and available/total memory, preserves location history after meaningful 100-metre movement and permits manual positioning only while reported coordinates are unavailable.

The bilingual manuals are linked from the public sign-in page and authenticated header. See [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).

## Current constraints

The single-server runtime is not a multi-node architecture. Automatic IoT certificate renewal/CA rollover, production Android bootstrap distribution, official A10 installation, malware scanning, Linux remote desktop, scheduled parameter push and fleet-scale/load/restore qualification remain outstanding.