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.

This guide walks you through cloning the Zippi monorepo, configuring your local environment, running database migrations, seeding initial data, and starting both servers. By the end you will have the Flask API running on port 5000 and the Vite frontend running on port 5174.
1

Clone the repo and verify prerequisites

Clone the Zippi monorepo and confirm that the required runtimes are installed before proceeding.
git clone https://github.com/CRISTIANCAMACH34/Zippi.git
cd Zippi
Required dependencies:
DependencyMinimum versionNotes
Python3.10Python 3.10 or newer required
Node.js18LTS recommended
MySQL8.0Create the zippi_db database before running migrations
Redis6+Required for Celery workers; optional for basic API usage
Create the database before continuing:
CREATE DATABASE zippi_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
2

Set up the Python backend

Create a virtual environment, install all development dependencies, and copy the example environment file.
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env
The application reads .env from the backend/ directory. Keep your terminal working directory inside backend/ when running Flask commands.
3

Configure .env

Open backend/.env in your editor. The three variables below are mandatory — the application will not start without them.
backend/.env
# Database — build the URL from the DB_* parts or set DATABASE_URL directly
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=zippi_db
DB_USERNAME=root
DB_PASSWORD=your_mysql_password
DATABASE_URL=mysql+pymysql://root:your_mysql_password@127.0.0.1:3306/zippi_db

# Application security — generate strong random values for production
SECRET_KEY=change_me_to_a_long_random_string
JWT_SECRET_KEY=change_me_to_another_long_random_string

# Redis (required for Celery workers)
REDIS_URL=redis://127.0.0.1:6379/0
CELERY_BROKER_URL=redis://127.0.0.1:6379/0
CELERY_RESULT_BACKEND=redis://127.0.0.1:6379/0
Other notable variables you may want to set now:
VariableDefaultDescription
APP_ENVdevelopmentSet to production in prod
TIMEZONEAmerica/BogotaUsed for timestamps and SLAs
CORS_ALLOWED_ORIGINShttp://localhost:5173,...Add your frontend URL
WOMPI_ENVsandboxSwitch to production for live payments
STORAGE_DRIVERlocalSet to s3 and fill AWS vars for S3
Never commit .env to version control. The .env.example file is the only checked-in reference.
4

Run migrations and seed data

Apply all Alembic migrations to create the schema, then run the seed script to populate base configuration, service types, order states, and payment methods.
# Still inside backend/ with .venv active
python -m flask db upgrade
python scripts/seed_data.py
seed_data.py registers the base configuration, service type catalog, order state definitions, and payment methods. Run it exactly once on a fresh database.
The create_admin.py script accepts any of the 16 role keys from rbac.py. Common bootstrap roles are super_admin (global scope) and city_admin (city scope). See Roles & Portals for the full list.
5

Set up the frontend

Open a new terminal, move to the frontend/ directory, install npm dependencies, and configure the frontend environment file.
cd frontend
npm ci
cp .env.example .env
Edit frontend/.env and point VITE_API_URL at the backend:
frontend/.env
# Must point to the BACKEND port, not the Vite dev server port
VITE_API_URL=http://127.0.0.1:5000

# Optional: serve mock data without a running backend
VITE_USE_MOCKS=false
VITE_API_URL must point to the backend (:5000), not to the Vite dev server (:5174). Mixing them up is the most common local setup mistake.
6

Start both servers

Run the backend and frontend in two separate terminals. They listen on different ports and communicate over HTTP.
cd backend
source .venv/bin/activate   # or .\.venv\Scripts\Activate.ps1 on Windows
python manage.py
# Flask API listening on http://127.0.0.1:5000

​
Local URLs Reference

ServiceURLDescription
Flask APIhttp://127.0.0.1:5000/api/v1Main REST API (all endpoints)
Health checkhttp://127.0.0.1:5000/healthReturns {"status":"ok"}
Readiness checkhttp://127.0.0.1:5000/readyPings the database
Vite frontendhttp://127.0.0.1:5174All portal surfaces
WhatsApp webhookhttp://127.0.0.1:5000/api/v1/whatsappRequires tunnel (ngrok) for Meta verification
Wompi webhookhttp://127.0.0.1:5000/api/v1/payments/wompi/webhookRequires tunnel for sandbox callbacks
Mocks mode: Set VITE_USE_MOCKS=true in frontend/.env to run the frontend with in-memory mock data. This is useful for working on UI components without a running backend or database. Mock mode does not validate permissions or scope — it is for UI development only.

Build docs developers (and LLMs) love

Get started for freeTalk to us