Skip to main content

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.

Zippi is a monorepo with a Flask API backend and a Vite/React+Vue frontend. The two services run on separate ports and communicate over HTTP — the frontend’s VITE_API_URL must always point to the backend, not to the Vite dev server. Follow the steps below to get both processes running locally from a fresh clone.
In production, SECRET_KEY and JWT_SECRET_KEY must each be at least 32 bytes of random data. The app raises a RuntimeError at startup if either key is too short when APP_ENV=production. Generate them with python -c "import secrets; print(secrets.token_hex(32))".

​
Full Setup

1

Prerequisites

Make sure the following are installed and available on your PATH before you begin:
ToolMinimum versionNotes
Python3.11+3.12 is used in CI
Node.js18+20 is used in CI
MySQL8.0+Create the zippi_db schema manually
Redis6+Required for Celery; default port 6379
Create the target MySQL database before running migrations:
CREATE DATABASE zippi_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
2

Clone the repository

git clone https://github.com/CRISTIANCAMACH34/Zippi.git
cd Zippi
3

Set up the Python virtual environment

All backend commands are run from the backend/ directory with the virtual environment active.
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
4

Copy and configure the environment file

Copy the example file to create your local .env. The app reads .env from inside the backend/ directory.
cp .env.example .env
Open backend/.env and set the three required secrets:
# Minimum 32 bytes each — use the generator below
SECRET_KEY=<your-32-byte-secret>
JWT_SECRET_KEY=<your-32-byte-jwt-secret>

# Match your local MySQL credentials
DATABASE_URL=mysql+pymysql://root:<password>@127.0.0.1:3306/zippi_db
Generate strong keys:
python -c "import secrets; print(secrets.token_hex(32))"
5

Run database migrations

Apply all pending Alembic migrations to bring the schema up to date:
python -m flask db upgrade
After migrations, seed the base configuration data (service types, order states, payment methods):
python scripts/seed_data.py
6

Start the backend API server

manage.py reads APP_HOST and APP_PORT from .env and starts Flask on 0.0.0.0:5000.
python manage.py
The server exposes a built-in health endpoint immediately after startup:
GET http://127.0.0.1:5000/health
→ {"success": true, "status": "ok", "service": "Zippi"}
7

Set up the frontend

Open a new terminal and work from the frontend/ directory at the repo root.
cd frontend
npm ci
cp .env.example .env
8

Configure the frontend API URL

Open frontend/.env and point the frontend at the running backend:
VITE_API_URL=http://127.0.0.1:5000
Set VITE_USE_MOCKS=true in frontend/.env to run the UI with mock data when you don’t have the backend running. This is useful for pure UI development or when working on frontend components in isolation.
9

Start the frontend dev server

npm run dev
Vite starts on port 5174 by default.
10

Verify the setup

With both processes running you should be able to reach all services:
ServiceURLDescription
Backend APIhttp://127.0.0.1:5000/api/v1REST endpoints for all modules
Health checkhttp://127.0.0.1:5000/healthLiveness probe
Readiness checkhttp://127.0.0.1:5000/readyConfirms DB connectivity
Frontend UIhttp://127.0.0.1:5174Vite dev server with hot reload
If the backend fails to start, check that:
  • Your virtual environment is active (which python shows .venv/)
  • DATABASE_URL in backend/.env matches your MySQL credentials
  • The zippi_db database exists and MySQL is running
  • Redis is running on 127.0.0.1:6379 (or REDIS_URL is updated)

​
Optional: Celery Worker

Background jobs (order assignment timeouts, notifications) run in a separate Celery worker process. Redis must be running before starting the worker. 
# From backend/ with the venv active
python scripts/run_worker.py
The broker and result backend default to redis://127.0.0.1:6379/0 — adjust CELERY_BROKER_URL and CELERY_RESULT_BACKEND in .env if your Redis instance listens elsewhere.

​
Optional: Create an Admin User

Use create_admin.py to bootstrap an administrative account scoped to a specific branch or the whole platform: 
python scripts/create_admin.py \
  --email gerente@zippi.local \
  --password "<SECRET>" \
  --name "Gerente Centro" \
  --role admin_sucursal \
  --scope-type sucursal \
  --scope-id 1 \
  --scope-label "Sucursal Centro"
See backend/docs/rbac_roles_matrix.md for the full role and scope matrix.

Build docs developers (and LLMs) love

Get started for freeTalk to us