Developer Documentation

This section contains technical documentation for the Upvendo platform, intended for developers working on the codebase and for AI agents assisting with bug fixing, feature development, and code understanding.

Who This Is For

• Backend developers working on the Laravel API (upvendo-backend)
• Frontend developers working on Backoffice, Kiosk, or Online Ordering apps
• DevOps engineers managing Cloudflare Workers, deployment, and infrastructure
• AI agents performing automated bug fixing, code review, and developer assistance

Subsections

Architecture

System-level documentation covering how the platform is built and how its components interact.

• Backend Overview -- Laravel 13 + MongoDB backend: service-orchestrator pattern, multi-tenant architecture, authentication, middleware, and job system.
• Proxy Overview -- Cloudflare Workers proxy: request routing, D1 stock management, KV caching, and item database API.
• Data Model -- MongoDB collection structure, core entity relationships, key model fields, multi-tenant data isolation, and factory defaults.
• Frontends Overview -- Vue 3 frontend applications: Backoffice (Vuetify), Kiosk (Tailwind + Capacitor), and Online Ordering (Tailwind + multi-merchant).
• Upvendo POS -- The first-party staff register (upvendo-pos): Vue 3 + Tailwind + Capacitor 7 iOS shell, the frozen /pos API contract, full-document order PUTs with 409 version conflicts, cash-only settlement, and no offline mode. ⚠️ Server is live — merchant selection is staged test_only: the /pos server API is on upvendo-backend origin/production; config/pos-providers.php now sets upvendo => 'active' => true, 'test_only' => true, so only test-flagged merchants can newly become first-party POS merchants, and there is still no POS billing SKU.
• Field Ops Overview -- The internal NFC "Upvendo Tap" review-stand program: the field-ops-authority authorization model, the two route surfaces (back-office admin + rep app), stand/rep/session data model, invite → PIN → rotating-refresh flow, and the batch → place → activate → CRM lifecycle. ⚠️ Internal sales tooling — NOT merchant-facing.

API (planned)

API reference documentation covering endpoint contracts, request/response formats, and authentication flows.

Patterns

Recurring code patterns, conventions, and best practices used across the codebase.

• Background Jobs -- Laravel queue system, key jobs, dispatch patterns, and job categories.
• Payment Flow -- End-to-end payment processing and state transitions.
• Service Orchestrator -- Service orchestrator pattern for multi-tenant business logic.
• Kiosk Tap Directive -- Why @click is forbidden in the kiosk app and how to use v-kiosk-tap correctly. Required reading for anyone writing interactive components in upvendo-kiosk.

Integrations

Per-POS engineering reference docs — API capabilities, entity models, iPad vs backoffice constraints, order lifecycles, and known limitations. Written for backend developers maintaining each integration.

• ShopCaisse -- ShopCaisse POS engineering reference: External Application API tier, entity hierarchy mapping, iPad-only structural creation rules, write-tier reality, order lifecycle (kitchen vs fiscal state machines), JWT structure, and webhook contract. Defers code-level detail (file/method/route maps) to the canonical upvendo-backend/docs/SHOPCAISSE_INTEGRATION.html.

Debugging (planned)

Common issues, debugging workflows, log analysis, and troubleshooting guides for each subsystem.

Quick Navigation

I need to...	Go to
Understand the backend architecture	Backend Overview
Understand the proxy layer	Proxy Overview
Look up a data model or collection	Data Model
Understand a frontend app	Frontends Overview
Add an interactive element to the kiosk	Kiosk Tap Directive
Work on the first-party POS register	Upvendo POS
Understand the NFC review-stand program	Field Ops Overview