# Delivery plan and architecture decisions

> Historical design requirements: consult [chapter 30](30-current-architecture.md) for the current implementation and outstanding work.

## Phased implementation

| Phase | Deliverables | Exit criteria |
| --- | --- | --- |
| 0 — Validate | Runtime/database/hosting decisions; agent capability inventory; broker and relay spikes | Representative Android and Linux device handshake; agreed ownership model; approved stack baseline |
| 1 — Foundation | Separate solution, MVC shell, identity, distributed session, gRPC, Dapper migrations, CI | Two customers isolated end to end; no portal SQL access; HTTP/2 through real proxy; revoked access denied |
| 2 — Fleet | Customer onboarding, global inventory, assignment, groups/tags, telemetry, app inventory, location | Only super admin assigns; last-admin protection; correct freshness; replay-after-transfer rejected |
| 3 — Operations | Outbox/inbox, dispatcher, reboot/message/block, durable jobs, audit | Duplicate/reordered messages safe; offline expiry works; failures do not report success |
| 4 — Applications | Quarantine/validation, APK/ZIP catalogue, canary deployments, downloads | Invalid/hostile packages rejected; compatible device install verified; partial failure visible |
| 5 — Parameters | Schema WYSIWYG editor, catalogs, templates, versioning, device forms and push | Nested schema authored visually; server validation; migration preview; revision/hash acknowledgement |
| 6 — Remote support | Adapted relay, scoped tickets, WSS, view/control admission, revocation | Cross-customer sessions denied; payment-screen controls validated; reconnect and relay routing tested |
| 7 — Production readiness | Load/soak tests, backup restore, observability, security review, operator runbooks | Agreed capacity/SLOs achieved; restore drill; supported runtime; pilot-bank acceptance |

These are dependency stages rather than calendar estimates. Start one complete vertical slice early: authenticated customer administrator lists one assigned device through MVC → gRPC → Dapper, queues one safe command, and observes an audited result. MQTT/AWS feasibility and relay compatibility can be investigated before their feature phases.

## Decision register

| ADR | Decision | Status / consequence |
| --- | --- | --- |
| 001 | Independent TMS solution with UIC Connect identity and visual conventions | Required; no dependency on separate reference solution |
| 002 | Kestrel MVC, Claims + Session, .NET 8 | Required baseline; runtime upgrade gate before production |
| 003 | TMS.DataService gRPC HTTP/2; Dapper persistence | Required; portal and adapters cannot bypass service policies |
| 004 | Customer is bank/institution tenant; only SuperAdmin creates/assigns | Required; enforced at service boundary |
| 005 | SQL Server in separate TMS database | Proposed; verify UIC operational conventions and hosting |
| 006 | Existing MQTT adapter for first compatibility pilot | Proposed; production broker decided after reliability/cost review |
| 007 | Durable commands, outbox/inbox, application acknowledgements | Proposed baseline; avoids broker-delivery-as-success |
| 008 | One primary group, nested subgroups; many tags | Proposed; groups/tags do not grant permissions |
| 009 | Per-device/app materialized parameters; no implicit group inheritance | Proposed; predictable behavior during group moves |
| 010 | Immutable schemas/releases; explicit migration and deployment | Proposed; rollback preserves evidence |
| 011 | Reuse relay transport, replace shared viewer authentication | Proposed; short-lived scoped access |
| 012 | Object storage for packages and configuration artifacts | Proposed; private access and quarantined upload |

## Decisions needed before implementation

1. Runtime: approve a supported production version and upgrade timing while preserving the requested MVC/gRPC design.
2. Hosting: bank-hosted, UIC-managed cloud, or both; database availability, region/residency and environment ownership.
3. Device transport: supported OS/firmware/agent versions, certificate capability, current protocol guarantees and legacy constraints.
4. Identity: the current local store includes optional TOTP MFA, recovery codes and SMTP password recovery. Decide whether a shared UIC or bank identity provider will replace or federate with it, and define customer invitation and emergency last-administrator recovery policy.
5. Fleet semantics: one primary group versus multiple memberships, optional merchant placement fields, parameter templates versus future inheritance.
6. Operational policy: fleet size, heartbeat interval, retention, remote consent/masking, block meaning and approval thresholds.
7. UI toolkit: existing licensed controls and UIC design assets available for MVC; validate before choosing a new component vendor.

## Verification strategy

Use unit tests for invariants and schema validation, SQL integration tests for tenant filtering/concurrency/transactions, and contract tests for protobuf evolution and agent messages. End-to-end tests cover identity → MVC → gRPC → SQL → dispatch → acknowledgement. Verify real Android and Linux terminals; a simulator alone cannot prove reboot, installation, screen capture or payment-screen masking.

Critical scenarios: foreign customer IDs; stale membership; forged service metadata; group cycles; duplicate commands; worker crash after publish; broker reconnect storm; device offline beyond expiry; partial app installation; schema migration incompatibility; expired download grants; transfer during deployment; late results from the old assignment; remote session revocation; session-cache failure; database restore and outbox replay.

Do not promise exactly-once transport delivery. Demonstrate idempotent effects within defined protocol support, and explicitly expose uncertainty for legacy devices that cannot supply that guarantee.

## Observability and runbooks

Correlate portal request, RPC, operation, outbox message and device result using stable IDs. Metrics: ingest lag, last-seen freshness, queue age, dispatch latency, retries, duplicate suppression, failed deployments, SQL p95, gRPC errors and active remote sessions. Avoid serial/location/secrets in broad metric labels.

Runbooks must cover broker outage, certificate rotation/revocation, stuck operation reconciliation, quarantined transfer, artifact withdrawal, schema rollback, last-admin recovery and restore/replay. Audit exports are permission checked, scoped and access logged. Health endpoints expose readiness/liveness without revealing customer devices or sessions.

## Review checklist for this baseline

Confirm the customer operating model, runtime upgrade decision, database choice, broker pilot, group/template semantics and production policies. After that, implementation can start with the foundation vertical slice. This documentation does not claim security certification, validated bank compliance or production readiness.