Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/123048152-JJDS/CafeteriaPM_S203/llms.txt

Use this file to discover all available pages before exploring further.

The CafeteriaPM API is a FastAPI application served by Uvicorn. It can be run directly with Python or containerized with Docker. All configuration is provided through environment variables read by python-decouple, which looks for a .env file in the project root and falls back to real environment variables — making it equally at home in local development and container-based production deployments.

​
Prerequisites

Before you start, make sure you have the following installed and available:
  • Python 3.11+ — the Docker image uses python:3.11-slim; local development works with 3.10 or later
  • PostgreSQL 14+ — create a dedicated database and user before running the API
  • pip — used to install Python dependencies
  • gcc and libpq-dev (Linux) — required to compile psycopg2-binary; on macOS use brew install libpq

​
Local Setup

1

Clone the repository and change into the API directory

git clone <repository-url>
cd CafeteriaPM_S203/api
2

Create and activate a virtual environment

# macOS / Linux
python -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate
3

Install Python dependencies

pip install -r requirements.txt
Key packages installed include fastapi==0.111.0, uvicorn==0.29.0, sqlalchemy==2.0.30, psycopg2-binary==2.9.9, python-jose==3.3.0, bcrypt==4.0.1, python-decouple==3.8, reportlab==4.2.0, and openpyxl==3.1.2.
4

Copy the example env file and configure it

cp .env.example .env
Open .env in your editor and fill in your database credentials and a strong secret key. See the Environment Variables section below for the full reference.
5

Initialize the database and seed reference data

python scripts/seed_all.py
seed_all.py runs the full sequence automatically: it calls init_db.py to load the schema from the bundled SQL file, then executes seed_admin.py, seed_estados.py, seed_productos.py, and seed_demo_data.py in order.
6

Start the development server

uvicorn main:app --reload --host 0.0.0.0 --port 8000
The API will be available at http://localhost:8000. Interactive Swagger docs are at /docs and ReDoc at /redoc.

​
Environment Variables

Every setting is loaded from your .env file (or real environment variables) by python-decouple. The file api/app/core/config.py defines all defaults.
DEBUG=True and the default CORS allow_origins=["*"] are intentionally permissive for local development. Before deploying to production, set DEBUG=False, replace SECRET_KEY with a cryptographically random string of at least 32 characters, and restrict allow_origins to your actual frontend domain(s).

​
Database

​
DB_HOST
string
default:"localhost"
Hostname or IP address of your PostgreSQL server. When running the API inside Docker and the database is on the host machine, use host.docker.internal.
​
DB_USER
string
required
PostgreSQL username. Example: cafeteria_user.
​
DB_PASSWORD
string
required
Password for the PostgreSQL user. Example: cafeteria_pass.
​
DB_NAME
string
required
Name of the PostgreSQL database. Example: cafeteria_db.
​
DB_PORT
integer
default:"5432"
Port PostgreSQL is listening on.

​
Authentication (JWT)

​
SECRET_KEY
string
required
The HMAC key used to sign and verify JWT tokens. Minimum 32 characters. Generate a safe value with:
python -c "import secrets; print(secrets.token_hex(32))"
​
ALGORITHM
string
default:"HS256"
JWT signing algorithm. HS256 is recommended for single-server deployments.
​
ACCESS_TOKEN_EXPIRE_MINUTES
integer
default:"480"
Token time-to-live in minutes. The default of 480 equals 8 hours — a typical full shift for cafeteria staff.

​
Application

​
APP_NAME
string
default:"CafeteriaPM API"
Application name returned in the health-check response.
​
APP_VERSION
string
default:"1.0.0"
Application version string returned in the health-check response.
​
ENVIRONMENT
string
default:"development"
Runtime environment. Accepted values: development, production.
​
DEBUG
boolean
default:"True"
Enables FastAPI/Uvicorn debug mode and verbose error responses. Set to False in production.

​
Docker

The api/Dockerfile uses a python:3.11-slim base image. It installs the gcc and libpq-dev system packages needed to compile psycopg2, copies requirements.txt and installs all Python dependencies with --no-cache-dir, then copies the full application source. Port 8000 is exposed and the container starts with: 
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

​
Build and run

# Build the image
docker build -t cafeteriapm-api ./api

# Run the container, passing environment variables at runtime
docker run -p 8000:8000 \
  -e DB_HOST=host.docker.internal \
  -e DB_USER=cafeteria_user \
  -e DB_PASSWORD=cafeteria_pass \
  -e DB_NAME=cafeteria_db \
  -e SECRET_KEY=your_secret_key_here \
  cafeteriapm-api
You can also use a --env-file flag to pass your .env file directly: 
docker run -p 8000:8000 --env-file ./api/.env cafeteriapm-api

​
Health Check

Once the server is running, GET / returns a JSON object confirming the application name, version, and status: 
{
  "app": "CafeteriaPM API",
  "version": "1.0.0",
  "status": "ok",
  "docs": "/docs"
}
EndpointDescription
GET /Health check — returns app name, version, and status
GET /docsInteractive Swagger UI
GET /redocReDoc API reference

​
Seed Scripts

The api/scripts/ directory contains a collection of utility scripts for database initialization and test data loading. Run them with python scripts/<script>.py from the api/ directory with your virtual environment activated.
ScriptPurpose
init_db.pyInitializes the database schema by executing the bundled SQL file (sql/CafeteriaPM_S203.sql) against the configured PostgreSQL database. Run this first on a fresh database.
seed_admin.pyCreates a single admin user. Useful when you only need an admin account without the full reference dataset.
seed_all.pyRuns the full seed sequence in order: init_db.py → seed_admin.py → seed_estados.py → seed_productos.py → seed_demo_data.py. Use this for a complete fresh install including demo data.
seed_demo_data.pyLoads sample products, ingredients, dining tables, and orders. Intended for development and QA environments only.
seed_estados.pySeeds order state records (pendiente, en_preparacion, listo, entregado, pagado, cancelado, reservado) and payment methods (efectivo, tarjeta, transferencia, otro).
seed_productos.pySeeds a sample product catalog with names, prices, and categories.
check_db.pyVerifies database connectivity by attempting a connection with the configured credentials. Useful for diagnosing configuration issues before running the app.

Build docs developers (and LLMs) love

Get started for freeTalk to us