Unified Parcel Tracker is a containerized web application designed to track parcels from multiple courier services through a single unified dashboard. It integrates background task processing, a PostgreSQL database, and Redis-based Celery workers for asynchronous operations — all orchestrated using Docker Compose.
- Unified Tracking: Track parcels across different courier APIs (e.g., FedEx, DHL, UPS, etc.) in one interface.
- Background Tasks: Celery + Redis handle background updates and sync jobs.
- Admin Dashboard: Monitor database and tasks via Adminer and Flower dashboards.
- API-Driven: Built using a modern Python web stack (FastAPI / Flask style).
- Modular Design: Clean structure with separate modules for models, schemas, tasks, and templates.
- Dockerized: Fully containerized with isolated services for development and production.
| Component | Technology Used |
|---|---|
| Backend | Python (FastAPI / Flask) |
| Database | PostgreSQL |
| Task Queue | Celery |
| Broker | Redis |
| Admin Tool | Adminer (DB) + Flower (Celery Monitor) |
| Containerization | Docker Compose |
docker-compose up --buildThis command builds all services (web, db, redis, worker, beat, flower, adminer) and starts the application stack.
| Service | URL | Description |
|---|---|---|
| Web App | http://localhost:8000 | Main application interface |
| Adminer | http://localhost:8080 | PostgreSQL management dashboard |
| Flower | http://localhost:5555 | Celery monitoring dashboard |
| Database | localhost:5432 | PostgreSQL (username: postgres / password: password) |
Set in docker-compose.yml:
DATABASE_URL=postgresql://postgres:password@db:5432/unified_parcel_tracker
REDIS_URL=redis://redis:6379/0The project includes three Celery-related containers:
- worker → Executes background jobs.
- beat → Schedules periodic tasks (e.g., parcel updates).
- flower → Web UI to monitor tasks.
If you prefer running outside Docker:
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Run server
uvicorn app.main:app --reload# Run Celery worker
celery -A app.celery_app worker --loglevel=info
# Run Celery beat scheduler
celery -A app.celery_app beat --loglevel=info
# Start Flower monitoring tool
celery -A app.celery_app flower --port=5555- The project is a smaller prototype version of the project delivered to actual client
- To integrate new courier APIs, add a new module under
app/vendors/and register it with the main tracking system.
Contributions are welcome! Fork the repo, create a new branch, and submit a pull request.
This project is licensed under the MIT License.