# C4 — System Context (Level 1) — TinyPOS (`tnx-pos`)

> Produced by the Reversa **Architect** (phase: interpretation) · doc_level: `complete`
> Generated on 2026-09-18

**Confidence scale:** 🟢 CONFIRMED · 🟡 INFERRED · 🔴 GAP

The context view shows TinyPOS as a single box, the people who use it, the in-store peripherals it touches, and the operational systems that drive it. **There are no external software integrations** — no payment gateway, third-party API, or messaging provider was found in configuration or dependencies. 🟢

---

## Actors and external elements

| Element | Kind | Relationship to TinyPOS | Confidence |
|---------|------|-------------------------|------------|
| **Store Administrator** (cashier / owner) | Person | The **only** system user. Operates the POS terminal and the entire back-office. Single Encore\Admin `Administrator` role — authorization is authenticate-only. | 🟢 |
| **Shopper / Customer** | Person (indirect) | Physically shops; is served at the terminal by the Administrator. Has **no login** — represented only as a CRM record (`customers`) for pricing tier, points and debt. | 🟢 |
| **Barcode scanner** | Peripheral / device | Feeds product & customer codes into the `scan` endpoints (exact-code lookup). | 🟡 (hardware inferred; endpoints confirmed) |
| **Receipt printer** | Peripheral / device | Renders the print view from `GET /orders/{order}/print`. | 🟢 |
| **System cron** | Operational system | Fires `php artisan schedule:run` every minute; drives the daily statistics rollup. | 🟢 |
| **GitLab CI** | Operational system | `pos-dev` deploy job redeploys the app and reinstalls the cron file. | 🟢 |

---

## Diagram

```mermaid
flowchart TB
    admin["👤 Store Administrator<br/>(cashier / owner)<br/><i>the only system user</i>"]
    shopper["👤 Shopper / Customer<br/><i>served in-store; CRM record only,<br/>no login</i>"]

    subgraph tinypos_boundary [" "]
        tinypos["🟦 <b>TinyPOS</b><br/>Point-of-Sale & back-office<br/>Laravel 5.6 monolith (PHP 7.4, MariaDB)<br/><i>sales, catalogue, customers,<br/>loyalty, debt, statistics</i>"]
    end

    scanner["🔌 Barcode scanner<br/><i>in-store peripheral</i>"]
    printer["🖨️ Receipt printer<br/><i>in-store peripheral</i>"]
    cron["⏱️ System cron<br/><i>artisan schedule:run</i>"]
    ci["🚀 GitLab CI<br/><i>pos-dev deploy job</i>"]

    admin -->|"operates terminal & back-office<br/>(HTTPS, session auth)"| tinypos
    admin -->|"serves"| shopper
    scanner -->|"scans product / customer codes<br/>→ /pos/scan, /customers/scan, /orders/scan"| tinypos
    tinypos -->|"renders receipt<br/>GET /orders/{id}/print"| printer
    cron -->|"triggers nightly rollup<br/>Order::summaryLogging()"| tinypos
    ci -->|"deploys & installs cron"| tinypos
    shopper -.->|"data captured as CRM record<br/>(pricing tier, points, debt)"| tinypos

    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef ext fill:#999,stroke:#6b6b6b,color:#fff
    class tinypos system
    class admin,shopper person
    class scanner,printer,cron,ci ext
```

---

## Notes

- **No external system integrations** is itself an architectural fact worth recording: payments, tax, e-invoicing and loyalty are all handled **inside** TinyPOS against its own MariaDB. Any future integration (e.g. e-invoice, card terminal) would be greenfield. 🟢
- The **Shopper** is drawn as a person but is a *passive* actor — they never authenticate. Their only footprint is the `customers` CRM record the Administrator creates/selects. This is the single most important access-control fact (see `permissions.md`). 🟢
- The barcode scanner is the one 🟡 element: the `scan` endpoints and the exact-code-vs-`LIKE` branch are confirmed in code, but that a physical scanner drives them is inferred from the workflow (`inventory.md` §11).

Container-level decomposition of the TinyPOS box is in `c4-containers.md`.
</content>