# Product scope and operating model

## Purpose

UIC Connect TMS enables a bank to administer the POS terminals it owns and places with merchants. The customer is the bank or other institution operating a terminal fleet. A merchant is an operating location or business relationship inside that customer's estate; it is not the tenant boundary.

The existing merchant-oriented UIC Connect business model remains separate. Payment routing and acquiring continue on their existing transaction path. A TMS outage must not itself interrupt payment authorization; a deliberate device block is a separate, capability-dependent administrative action.

## Required capabilities

| ID | Requirement | Design coverage |
| --- | --- | --- |
| R01 | Separate Kestrel ASP.NET Core MVC .NET 8 portal, Claims + Session | Architecture, security |
| R02 | TMS.DataService using gRPC over HTTP/2 and Dapper | Architecture, data contracts |
| R03 | Multiple customers; one or more administrators per customer | Tenancy, customer lifecycle |
| R04 | Only super administrators create customers and assign devices to them | Authorization matrix, assignment workflow |
| R05 | MQTT service or AWS IoT Core connectivity | Connectivity decision and adapter |
| R06 | Telemetry, properties, location, software and installed applications | Device detail and ingest |
| R07 | Reboot, message, block/unblock, remote control, app push, parameter push | Operation lifecycle |
| R08 | Visual schema designer and schema-driven device parameter editing | Schema specification |
| R09 | Device groups, nested subgroups and tags | Tenant model, portal navigation |
| R10 | Application upload: Android APK and legacy Linux ZIP | Application lifecycle |
| R11 | Reuse existing MQTT and remote-control proxy where appropriate | Reuse assessment |
| R12 | Independent solution with UIC Connect visual continuity | Project boundaries, portal design |

## Vocabulary and ownership

| Concept | Meaning |
| --- | --- |
| Platform | UIC-operated TMS installation and global device inventory |
| Customer | Bank/institution; primary isolation and authorization boundary |
| Customer administrator | User managing one customer's fleet and delegated access |
| Device | Physical terminal with immutable internal identity and enrollment credentials |
| Merchant / site | Optional customer-owned placement records; not mandatory for enrollment |
| Placement | Dated association of a device to a merchant/site; distinct from customer assignment |
| Group / subgroup | Customer-owned organizational hierarchy used to browse and target devices |
| Tag | Customer-owned, many-to-many classification without ownership or permission semantics |
| Application | Logical software product, with immutable APK/ZIP versions |
| Schema version | Immutable published definition of parameter structure and form layout |
| Configuration revision | Immutable resolved parameter document for one device and application |

## Customer and device lifecycle

1. Super administrator creates a customer in Pending state and invites its first administrator.
2. Customer becomes Active after at least one administrator accepts. An active customer cannot lose its last active administrator; recovery requires a super administrator and an audit reason.
3. Super administrator registers/imports devices into global Unassigned inventory. Serial numbers are identifying attributes, not credentials.
4. Super administrator assigns devices to the customer. This action is distinct from a customer administrator organizing those devices into groups or assigning merchant placement.
5. Customer administrator configures groups, tags, applications, schemas, device parameters and operational users.
6. Devices enroll, report state, receive approved operations and return application-level results.
7. Retirement revokes credentials and disables new work while preserving historical records. A cross-customer transfer follows the quarantine procedure in the tenancy chapter.

Proposed states: customer Pending → Active → Suspended → Closed; device Unassigned → Assigned → Enrolled → Retired. Connection status and operational block status are separate dimensions, not lifecycle states.

## Scope boundaries

Included: fleet administration, application distribution, configuration, remote support, operational audit, customer administration and optional merchant/site placement. Bank ownership and rental placement are recorded; rental billing, subscriptions, settlement, transaction processing, acquirer certification and full inventory procurement are outside this initial module.

The portal must distinguish Unsupported, Unknown, Stale, Pending and Failed. A Linux terminal may support parameters and ZIP installation without screen control. Support is negotiated from device capabilities; it is never inferred solely from a model name.

## Initial assumptions for review

- A device has exactly one current customer, or is globally unassigned.
- A user may have memberships in multiple customers, but each request acts within one explicit customer context.
- Groups form a tree, with one primary group per device. Tags provide overlapping selections. Neither grants permissions in release one.
- Parameters are independently versioned per device and application. Groups and templates help bulk authoring; group movement does not silently change parameters.
- SQL Server is the proposed database, based on inspected UIC architecture documentation and existing reusable service dependencies. Dapper compatibility alone does not establish database or contract compatibility.
- English and Latin American Spanish are proposed launch languages; Traditional Chinese can preserve broader UIC regional continuity if required.