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 11 + 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).

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