Glossary
Purpose: shared vocabulary for the POS domain and the Appwrite platform, so agents and humans use terms consistently. Status: as of 2026-07-30.
POS domain
Section titled “POS domain”| Term | Meaning |
|---|---|
| Merchant | The organization that owns stores. An org record in the merchants collection (not a team). Stores reference it via merchantId. |
| Store | An operational location belonging to a merchant. Each store is an Appwrite Team (the tenant boundary) and also a stores collection doc carrying storeTeamId. |
| Terminal | A physical POS device (Android), paired to a store. Collection terminals (storeId, kind, pairingCode, lastSeenAt, currentShiftId). |
| Employee | A staff member. Identity is an Appwrite Auth user; employees is a POS profile (pinHash, storeTeamId) linked 1:1 by userId. |
| POS role | Per-store operational role: cashier / supervisor / manager. = the store-team membership role. Role→permission mapping is a code matrix (no pos_roles/pos_permissions collections). |
| Shift | A cashier work session (open → close) tied to a terminal. Collection shifts. |
| Cash movement | Cash in/out during a shift (drops, payouts, float). Collection cash_movements. |
| Product | A POS sellable item (SKU). New Appwrite collection products (distinct from the legacy loan Product). |
| Variant | A single-axis variation of a product (size/color). Collection variants. |
| Barcode | A scannable code mapped to a variant. Collection barcodes. |
| Tax rate | A configurable tax applied to line items. Collection tax_rates. |
| Stock level | On-hand quantity for a (variant, store) pair. Collection stock_levels. |
| Stock movement | Append-only inventory ledger entry. Collection stock_movements. |
| Cart | An in-progress sale. Collection carts with line_items, discounts. |
| Sales order | A finalized sale. Collection sales_orders with order_payments. |
| Tender | A method of payment (cash, card, …) applied to an order. |
| Transaction | POS financial ledger entry (SALE/VOID). New collection transactions (distinct from legacy financial Transaction). |
| Payment intent | A PSP-agnostic intent to capture payment. Collection payment_intents; PSP adapter stays in NestJS. |
| Receipt | A thin artifact representing a printed/issued receipt. Collection receipts. |
| Audit log | Record of sensitive operations (action/entity/before/after). Collection audit_log. |
| clientId | A client-generated UUID stamped on money-path writes so a retry or replay is idempotent (server dedups). Note: this is for online retries — writes are never queued offline (PO, 2026-07-06). |
| Z-report | End-of-day summary report per terminal/store. |
Appwrite platform
Section titled “Appwrite platform”| Term | Meaning |
|---|---|
| Project | The Appwrite project (per environment). |
| TablesDB / Table / Row / Column | Appwrite’s data primitives, renamed from Database/Collection/Document/Attribute. Use the new names in new writing; older docs and some code identifiers still say “collection” — read it as “table”. We use a single shared database with one table per POS domain. |
| Column / Index / Relationship | Table schema elements, declared in appwrite.config.json. Row-size limits are real: a single string column is capped at 16 381 chars and a whole row at roughly 65 KB, so a big JSON blob cannot be one column — model the overflow as child rows (the carts pattern). |
| Query | Appwrite’s query API (Query.equal, pagination, ordering) — our primary read path. |
| Account | Per-user auth: sessions, JWT, MFA, recovery, custom tokens. |
| Session | A logged-in user session (cookie on Web, token on Android). |
| JWT | Short-lived token a client mints from its session; the API validates it. |
| Custom token | Server-minted token used for PIN login (NestJS validates PIN → mints token). |
| MFA / 2FA | Multi-factor auth via email/SMS factors (no TOTP): verify email/phone → enable → email/SMS challenge. |
| Team | A group of users = one per store; membership roles are the POS roles. The tenant boundary for permissions. |
| Label | Server-set user category; reserved for cross-merchant platform admins (Role.label(...)), not POS roles. |
| Presence | Appwrite Presences API (GA 2026-05-25): per-user online/status records broadcast on Channel.presences(), auto-expiring. |
| Membership | A user’s join to a team, with role(s) (owner/admin/member). |
| Permissions | Per-document read/write rules (by team, role, user) enforcing tenant + store scoping. |
| Storage / Bucket / File token | File storage; buckets declared as code; file tokens grant scoped access. |
| Function | Server-side function deployed to Appwrite; we deploy via CI/CD. |
| Realtime | Subscription channel pushing document changes to clients (cache refresh). |
appwrite.config.json |
Schema-as-code: tables, columns, indexes, relationships, buckets, functions. Lives at terminales-api/infra/appwrite/. Since M6 it is the only DDL path for Appwrite — no console edits. |
appwrite push |
Applies appwrite.config.json to an environment. Gated through appwrite-deploy.yml and preceded by pnpm appwrite:validate. |
appwrite types |
Generates typed models from the schema (feeds API + Web). |
Project / tooling
Section titled “Project / tooling”| Term | Meaning |
|---|---|
| Project 11 | The GitHub Project board for this solution. |
| Epic A–G | The Appwrite migration work, grouped (Foundation → Data → Auth → Storage → Functions → Client integration → Cutover/Decommission). Complete — see ../progress/roadmap.md. |
| Wave 1 / 2 / 3 | The successive planning-and-execution passes after the migration. Wave 3 (from 2026-07-11) = verification & completion of the MVP. |
| M0–M11 | The milestone ladder in ../progress/milestones.md. M6 is the production-cutover gate (crossed 2026-07-24); M11 is go-live. |
| DBOS | Durable-execution framework used in NestJS for must-succeed workflows (finalize/settlement, VAS fulfillment, wallet serialization). |
| Spec-writer | The convention/flow for authoring draft tickets. See ticket-conventions. |
agentic |
The CLI that drives the whole pipeline — plan (draft/promote/sprint/assign) and dev (start/auto/review/pr/finish). Runs 24/7 in per-user loops on the ionos server. |
| ionos | The remote development + hosting server (formerly “terminales-solution”). Runs the agent loops, the stage stack, and the observability stack. |
| Mock E2E / Live E2E | The two Playwright suites. Mock = hermetic, NEXT_PUBLIC_USE_MOCKS=true. Live = --project=live, mocks OFF, against a real API + cloud Appwrite with the e2e_store seed. Tracked per story in ../product/user-stories.md. |
| Design parity | The Figma ↔ app comparison discipline: regenerate screenshots, diff against the frame, fix by layer. Galleries live in terminales-web/docs/design-parity/ and terminales/docs/design-parity/. |
| W-xx / M-xx | Canonical screen ids — web / mobile — from flows-screens-master-map. Every parity and story doc cites them. |
| Mantarys | The VAS aggregator (the “VB webservice”): TAE, gift-card PINs, service/bill payment. See mantarys. |
| AngelPay | The card PSP; card-present tenders route to a paired handheld terminal. |