Skip to content
Terminales Docs

System overview

Purpose: explain what terminales is, who it serves, and where it’s headed. Status: as of 2026-07-30.

What it is

Section titled “What it is”

terminales is a multi-tenant Point-of-Sale (POS) platform. Multiple merchants operate independently on shared infrastructure; each merchant runs one or more stores, each store has one or more terminals (Android devices), staffed by employees who open/close shifts and process sales.

It is delivered as:

  • a web admin + web terminal (Next.js) for back-office and browser-based selling,
  • an Android terminal app (Kotlin) for in-store selling — offline-capable for reads, but never for taking a sale,
  • an API (NestJS) for complex/durable business logic,
  • a backend platform (Appwrite) providing data, auth, storage, and functions.

Goals

Section titled “Goals”
  1. Sell reliably — and never sell what cannot be settled. (Revised 2026-07-06.) The Android terminal keeps reading from its local cache without connectivity (catalog, cached reports, notifications, theming), but every money-path write requires the network: the UI blocks with a clear “sin conexión” state and nothing is queued. Reliability is provided server-side by DBOS durable workflows plus clientId idempotency for online retries — not by device-side replay.
  2. Isolate merchants safely. One merchant must never see another’s data; isolation is enforced at the data layer, not just the UI.
  3. Reduce backend maintenance surface. Move CRUD/data/auth/storage onto Appwrite (managed primitives) and reserve hand-written server code for logic that genuinely needs it (durability, PSP orchestration, fiscal rules).
  4. Keep clients fast on low-resource devices. Clients talk to Appwrite directly for simple reads/writes; only complex commands round-trip through the API.
  5. Reproducible environments. Schema, buckets, and functions are code (infra/appwrite/appwrite.config.json), applied per environment via CLI/CI. Since the M6 gate this is the only DDL path for Appwrite — no console edits — with reviewed TypeORM migrations the only one for the legacy Postgres remainder.

Current phase: verifying a feature-complete MVP on stage

Section titled “Current phase: verifying a feature-complete MVP on stage”

The system was first built on NestJS + TypeORM + BetterAuth. That backend has been fully migrated to Appwrite and the legacy stack removed:

  • Data → Appwrite TablesDB (the POS domain).
  • Auth → Appwrite Account + Teams (BetterAuth removed entirely, 2026-07-04).
  • Storage → Appwrite Storage buckets with scoped file-tokens.
  • Functions → Appwrite Functions, deployed by CI.
  • NestJS/DBOS stays for complex/durable logic — settlement, VAS fulfillment, wallet integrity, PSP orchestration.

Three gates have been passed since: the migration (Epics A–G, complete 2026-07-03), the stage environment (api-stage.io.inspiracode.com on the ionos server, 2026-07-08), and the M6 production-cutover gate (2026-07-11..24) — which ended the pre-production regimes. Feature flags now exist and, per the PO’s 2026-07-14 directive, are all ON; database migrations are back as the only DDL path; CI is re-enabled and runs on self-hosted hardware.

What is left is verification, not construction. Every MVP user story has an implementation; each is being driven to green on three independent axes — Built, Mock E2E, Live E2E — in ../product/user-stories.md (web) and ../product/mobile-user-stories.md (mobile), alongside Figma ↔ app parity galleries for both clients. The one structural gap remaining is the VAS aggregator transport (Mantarys).

There are still no live users and no production release.

How work is organized

Section titled “How work is organized”
  • Backlog & board: GitHub Project 11 (inspiraCode). The solution root (terminales-solution) holds the planner mirror (board/, manifests/, backlog/) and conventions.
  • Tickets are authored as drafts in backlog/drafts/ following the spec-writer flow, then uploaded via agentic plan draft. See ticket-conventions.
  • Implementation is agent-driven. Per-user autonomous loops run tickets end-to-end (implement → commit → self-review → PR) on the ionos server via the agentic CLI; loops are --assigned-only, so unassigned work sits idle. See agentic-workflow.
  • Knowledge (this directory) is the durable big-picture layer; granular tasks stay on Project 11.
  • Stakeholders read two published sites: the knowledge-base site (docs-site/ → docs.io.inspiracode.com, allowlisted subset only) and a password-gated Spanish progress site (presentacion/).
Section titled “Related reading”