Repositories

Purpose: the repos that make up the solution, their roles, stacks, and key commands. Status: as of 2026-07-30.

All repos are owned by inspiraCode and default to the main branch. Roles come from terminales-solution.code-workspace.

Branching: the three code repos go through PRs. terminales-solution commits straight to main — no PRs for board, manifests, or docs.

The four repos

Repo	Role	Purpose
terminales-api	api	NestJS backend: complex/durable business logic, token validation, DBOS workflows, PSP + VAS orchestration.
terminales-web	web	Next.js admin + browser terminal.
terminales	mobile	Android/Kotlin in-store terminal (offline-first reads; operational writes are online-only).
terminales-solution	multi / infra	Planner board, manifests, conventions, this knowledge base, and the two published sites.

Stacks & commands

terminales-api (NestJS)

• Stack: NestJS + Appwrite server SDK (node-appwrite) + DBOS. TypeORM and BetterAuth are decommissioned; typeorm remains only to run migrations against the legacy Postgres remainder.
• Package manager: pnpm. Tests: Jest.
• Commands: pnpm install · pnpm lint · pnpm test · pnpm test:e2e · pnpm start:dev
• Schema & data: pnpm appwrite:validate (offline schema check) · pnpm appwrite:types · pnpm appwrite:backup / appwrite:restore · pnpm seed:e2e + pnpm verify:e2e-schema (the E2E tenancy-graph seed) · pnpm migration:{generate,create,run,revert,show}.
• Key paths: src/auth/appwrite-auth.guard.ts (+ roles/, pin-login/, teams/, user-management/, platform-admin/), src/pos/** (customers, held-orders, inventory, notifications, foundations, audit), src/vas/** (aggregator port + DBOS fulfillment), src/wallet/**, src/reports/**, src/dbos/**, src/database/migrations/** (+ MIGRATIONS.md, the DDL policy).
• Domain docs: docs/pos/4.APPWRITE_REUSE_ANALYSIS.md; runbooks in docs/runbooks/ (backup-restore, mantarys-connectivity).

terminales-web (Next.js)

• Stack: Next.js 16, React 19, MUI v9 (+ x-charts, x-date-pickers), TanStack React Query, Appwrite Web SDK, Axios, Sentry, Playwright.
• Package manager: pnpm. Tests: Jest + Playwright.
• Commands: pnpm install · pnpm lint · pnpm typecheck · pnpm test · pnpm test:e2e · pnpm dev
• Design parity: pnpm screenshots (Playwright captures on its own :4000 prod server, mocks ON + all flags ON) · pnpm docs:parity (rebuild the gallery README, preserving hand-written notes) · pnpm docs:parity:snapshot (freeze a dated copy).
• Types: pnpm api-types / verify:api-types (openapi-typescript) and pnpm appwrite-types / verify:appwrite-types — both coexist by design. pnpm tokens:build / verify:tokens for design tokens.
• Structure: atomic design system under src/ui/{atoms,molecules,organisms,templates,theme} alongside the older named folders (AppBar/, Buttons/, Generics/, …) that it is progressively replacing — see docs/design/legacy-deprecation-map.md. Entity folders were relocated out of the route tree (2026-07-28); routes live in src/app, components in src/components. USE_MOCKS from src/env.ts. See web-data-layer.

terminales (Android / Kotlin)

• Stack: Android, Kotlin, Jetpack Compose, Hilt, Room, io.appwrite:sdk-for-android. Package com.axios.terminales.
• Build: Gradle. Tests: JUnit; Maestro for the screenshot/parity harness.
• Commands: ./gradlew dependencies · ./gradlew lintDebug · ./gradlew testDebugUnitTest · ./gradlew installDebug
• Structure: feature packages under app/src/main/java/com/axios/terminales/ (auth, shifts, payment, vas, wallet, customers, reporting, notifications, terminal, account) with the design system in ui/components/terminales/{atoms,molecules,organisms}; harness/ backs the Playground captures.
• Parity: flows in tools/*.yaml (Maestro) + tools/capture-screenshot.sh; gallery built by tools/build-gallery.mjs into docs/design-parity/.

terminales-solution (planner / infra / sites)

• Holds: board/ (status mirror), manifests/, backlog/{ideation,drafts}, conventions/, review/ (the reviewer rubric), runbooks/, solution.yml (Project 11 metadata, sprints, agent roster), and docs/ (this knowledge base).
• Also ships three sites: docs-site/ (Astro Starlight → docs.io.inspiracode.com; publishes only the allowlist in publish.config.mjs) and presentacion/ (password-gated Spanish owner-facing progress site, SSR, at presentacion.io.inspiracode.com) and manuales-site/ (password-gated manuals, at manuales.io.inspiracode.com) — all three served from ionos, see ci/docs-sites/README.md.
• Auto-commit: the agentic CLI auto-commits only board/, manifests/, backlog/. docs/ is not auto-committed — commit it deliberately.

Repo selection for tickets

Each ticket targets exactly one repo (agent_meta.repos = single element) — except E2E tickets (agent_meta.e2e: true), which may list several because a flow is verified across the live stack. The title’s first token (API / Web / Mobile / Infra / Multi) and repos disambiguate which repo dev-start uses. See ticket-conventions.