Zippi is a full-stack delivery and business operations platform built to serve every actor in the food and local commerce delivery chain — from the customer placing an order on their phone to the super administrator overseeing the entire platform. A single Flask API powers sixteen distinct roles, each of which enters its own dedicated portal surface with a tailored interface, a scoped dataset, and a permission set tuned to that role’s job. No role sees what belongs to another tenant or role group.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/CRISTIANCAMACH34/Zippi/llms.txt
Use this file to discover all available pages before exploring further.
What Zippi Is
At its core, Zippi orchestrates the complete lifecycle of a delivery order: creation on the client app, acceptance and preparation by the business, assignment and pickup by the courier, and final delivery with evidence and payment reconciliation. Layered on top of that operational core are tools for multi-brand business management, geographic city operations, financial settlement, customer support, and platform administration. Zippi is organized as a monorepo with two top-level directories:/api/v1 and handles authentication, RBAC, multi-tenant scoping, order state management, payments, and all business logic. The frontend is a single Vite application that renders the correct portal surface based on the authenticated user’s role.
The 16 Roles
Zippi defines exactly 16 roles spanning from global platform administration down to the individual customer or courier. Each role has a fixed surface, a default scope type, a home route, and a permission set derived frombackend/app/modules/auth/domain/rbac.py. No role can be invented at runtime — the catalog is the single source of truth.
| Role | Label | Surface |
|---|---|---|
super_admin | Super administrador | superadmin_panel |
platform_admin | Administrador plataforma | superadmin_panel |
country_admin | Administrador país | admin_panel |
city_admin | Administrador ciudad | admin_panel |
zippi_branch_admin | Administrador sucursal Zippi | admin_panel |
operations_admin | Administrador operaciones | admin_panel |
finance_admin | Administrador financiero | admin_panel |
support_agent | Agente soporte | admin_panel |
business_owner | Dueño de negocio | business_portal |
business_admin | Administrador negocio | business_portal |
business_branch_admin | Administrador sucursal negocio | business_branch_portal |
kitchen_staff | Cocina | kitchen_app |
cashier | Cajero | cashier_app |
waiter | Mesero | waiter_app |
delivery_driver | Domiciliario | courier_app |
customer | Cliente | client_app |
Portal Surfaces
Each role is mapped to one of nine portal surfaces defined inROLE_DEFINITIONS. The surface controls which part of the frontend application is rendered, which modules appear in the sidebar, and which API endpoints are accessible.
Superadmin Panel
Global platform control for
super_admin and platform_admin. Covers countries, cities, Zippi branches, platform configuration, audit, security, and full operational visibility across every tenant.Admin Panel
Operational and financial management for
country_admin, city_admin, zippi_branch_admin, operations_admin, finance_admin, and support_agent. Each admin role is scoped to its geography (country → city → Zippi branch).Business Portal
Brand and multi-location management for
business_owner and business_admin. Covers the full catalog, orders, settlements, analytics, and notifications scoped to a business group or individual brand.Business Branch Portal
Local operations for
business_branch_admin — manages a single business location, its catalog, orders, kitchen coordination, and daily cash reconciliation.Kitchen App
Command-ticket screen for
kitchen_staff. Shows the live preparation queue with priority and timer; limited to kitchen.read and kitchen.manage permissions.Cashier App
Till management for
cashier. Covers order payment collection, till opening/closing, and shift reconciliation (arqueo).Waiter App
Table-service screen for
waiter. Handles dine-in orders, table management, and routing requests to the kitchen or cashier.Courier App
Mobile delivery experience for
delivery_driver. Shows assigned deliveries, allows evidence uploads, tracks the courier’s personal cash balance, and handles incident reporting.Client App
Consumer marketplace for
customer. Browse businesses, place orders via the app or WhatsApp bot, track delivery in real time, and open support tickets.Tech Stack
| Layer | Technology |
|---|---|
| Backend API | Python 3.10+, Flask, SQLAlchemy |
| Database | MySQL 8 |
| Async workers | Redis + Celery |
| Payments | Wompi (sandbox & production) |
| Messaging | WhatsApp Cloud API (Meta Graph v22.0) |
| File storage | Local filesystem or AWS S3 |
| Frontend | TypeScript, React/Vue, Vite |
| CI | GitHub Actions (ruff, bandit, pytest, tsc) |
Next Steps
Quickstart
Run Zippi locally in under 10 minutes — backend on :5000, frontend on :5174.
Architecture
Explore the monorepo layout, DDD layering, module registry, and external integrations.
Roles & Portals
Full reference for all 16 roles, their surfaces, scopes, and module sets.
Order State Machine
The happy-path order states, exception states, and the complete transition table.