A FastAPI-based order management system with customer and order tracking.
For manual installation:
- Python 3.9+
- PostgreSQL
- Redis (for Celery)
- uv package manager
For Docker Compose:
- Docker
- Docker Compose
-
Set up environment variables:
cp .env.example .env
Edit
.envwith your configuration:POSTGRES_USER=orderflow POSTGRES_PASSWORD=your_password POSTGRES_DB=order_flow POSTGRES_PORT=5432 REDIS_PORT=6379 BACKEND_PORT=8000
-
Build and start all services:
# Build the image first (recommended to avoid build conflicts) docker-compose build # Then start all services docker-compose up -d
Or build and start in one command:
docker-compose up -d --build
This will:
- Start PostgreSQL database
- Start Redis
- Run database migrations and load CSV data (via prestart service)
- Start the FastAPI backend
- Start Celery worker
- Start Celery beat scheduler (for periodic ETL jobs)
-
View logs:
docker-compose logs -f
-
Stop services:
docker-compose down
-
Rebuild after code changes:
docker-compose up -d --build
The API will be available at:
- API: http://localhost:8000
- Documentation: http://localhost:8000/docs
-
Install dependencies:
uv sync
Or using requirements.txt:
uv pip install -r requirements.txt
-
Set up environment variables:
cp .env.example .env
Edit
.envwith your PostgreSQL credentials:POSTGRES_SERVER=localhost POSTGRES_PORT=5432 POSTGRES_USER=your_username POSTGRES_PASSWORD=your_password POSTGRES_DB=order_flow
-
Create PostgreSQL database:
Option 1: Using SQL script (recommended):
psql -d postgres -f sql/init_db.sql
Edit
sql/init_db.sqlto change username and password if needed.Option 2: Using command line:
createdb order_flow
Option 3: Using psql:
psql postgres
Then in the psql prompt:
CREATE DATABASE order_flow; \q
-
Run database migrations:
make migrate # or uv run alembic upgrade head -
Load CSV data:
make load-data # or uv run python -m app.scripts.load_csv_dataOr run both at once:
make setup-db
Development server (with auto-reload):
make dev
# or
uv run uvicorn app.main:app --reloadProduction server:
make start
# or
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000The API will be available at:
- API: http://localhost:8000
- Documentation: http://localhost:8000/docs
Use make help to see all available commands, or use these common ones:
| Command | Description |
|---|---|
make install |
Install dependencies |
make dev |
Run development server |
make migrate |
Run database migrations |
make migrate-create MESSAGE="description" |
Create a new migration |
make migrate-down |
Rollback last migration |
make load-data |
Load CSV data into database |
make setup-db |
Setup database (migrate + load data) |
make db-init |
Initialize PostgreSQL database |
make celery-worker |
Start Celery worker |
make celery-beat |
Start Celery beat scheduler |
make celery-flower |
Start Celery Flower (monitoring) |
make test |
Run tests |
make test-cov |
Run tests with coverage report |
make clean |
Clean Python cache files |
You can also use uv run directly:
uv run load-data- Load CSV datauv run setup-db- Setup database
The project includes comprehensive test coverage for API endpoints.
Run all tests:
make test
# or
uv run pytest tests/ -vRun tests with coverage report:
make test-cov
# or
uv run pytest tests/ --cov=app --cov-report=html --cov-report=termRun specific test file:
uv run pytest tests/api/routes/test_customers.py -vRun specific test:
uv run pytest tests/api/routes/test_customers.py::test_get_all_customers -vThe test suite includes:
- Customer endpoints: Get all customers, get by ID, filtering by active status
- Order endpoints: Create orders, validation, error handling
All tests use an in-memory SQLite database for fast execution and isolation.
Test dependencies are included as optional dependencies in pyproject.toml. Install them with:
uv sync --extra dev
# or using requirements-dev.txt
uv pip install -r requirements-dev.txtThe application includes an ETL job that runs on a schedule to:
- Fetch all active customers from the API
- Transform data (concatenate firstname + surname to name)
- Send each customer to target API (postman-echo.com)
- Log HTTP response codes
Install and start Redis:
# macOS
brew install redis
brew services start redis
# Linux
sudo apt-get install redis-server
sudo systemctl start redisStart Celery Worker (processes tasks):
make celery-worker
# or
uv run celery -A app.core.celery_app worker --loglevel=infoStart Celery Beat (scheduler for periodic tasks):
make celery-beat
# or
uv run celery -A app.core.celery_app beat --loglevel=infoMonitor with Flower (optional):
make celery-flower
# or
uv run celery -A app.core.celery_app flowerTest the ETL task without Celery:
uv run python -m app.scripts.test_etlThe ETL job is configured to run every 15 minutes by default. To change the schedule, edit app/core/celery_app.py:
"schedule": crontab(minute="*/15"), # Every 15 minutes
# or
"schedule": crontab(hour="*/1"), # Every hourWhen an order is created via the API, it automatically sends an event to a queue. A Celery worker processes these events and saves each order as a text file in the order_events/ directory.
To test:
- Start Celery worker:
make celery-worker - Create an order via API:
POST /api/v1/orders - Check
order_events/directory for the generated text file
app/
├── alembic/ # Database migrations
├── api/ # API routes
├── core/ # Configuration
├── models/ # Database models
├── scripts/ # Utility scripts (Python)
└── tasks/ # Celery tasks (ETL jobs, order events)
data/ # CSV data files
order_events/ # Order event files (generated)
sql/ # SQL scripts (database setup)
tests/ # Test suite
├── api/ # API route tests
│ └── routes/ # Endpoint tests
└── conftest.py # Test fixtures and configuration