A Universal Package Tracker built with FastAPI, React, and PostgreSQL. Features secure JWT user authentication (including SMTP password recovery) and tracking for multiple carriers via KeyDelivery API.

• Secure JWT Authentication: User registration, login, and password recovery via SMTP
• Multi-Carrier Support: Unified tracking via KeyDelivery API
  • Supports 20+ carriers including DHL, UPS, FedEx, Correos, GLS, SEUR, and more
  • Automatic carrier detection
• RESTful API: Built with FastAPI with automatic OpenAPI documentation
• Modern Frontend: React-based user interface with responsive design
• Dockerized: Fully containerized application stack
• 80%+ Test Coverage: Comprehensive unit tests for backend

• Security: JWT tokens, bcrypt password hashing, secure password reset flow
• Database: PostgreSQL with SQLAlchemy ORM
• Tracking Service: KeyDelivery API integration for universal carrier tracking
• API Documentation: Auto-generated at /docs

• Authentication: Login, registration, password reset
• Dashboard: Add, view, and track packages
• API Integration: Axios-based API client

• User management
• Package tracking storage

• Backend: FastAPI, SQLAlchemy, PostgreSQL, Python 3.11
• Frontend: React 18, Vite, Tailwind CSS, Axios
• Authentication: JWT (python-jose), bcrypt (passlib)
• Email: SMTP for password recovery
• Testing: pytest, pytest-cov
• Containerization: Docker, Docker Compose

• Docker and Docker Compose
• (Optional) Python 3.11+ for local development
• (Optional) Node.js 18+ for local frontend development

1. Clone the repository:

git clone https://github.com/xhiena/packageTracker.git
cd packageTracker

2. Create environment file:

cp backend/.env.example backend/.env

3. Configure SMTP settings in backend/.env (optional, for password recovery):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=your-email@gmail.com

4. Start the application:

docker-compose up -d

5. Access the application:

• Frontend: http://localhost:5173 (development) or http://localhost:3000 (Docker)
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Set up database and run
uvicorn app.main:app --reload

cd frontend
npm install
npm run dev  # Development server at http://localhost:5173

The backend includes comprehensive unit tests with 80%+ coverage:

cd backend
pytest
pytest --cov=app --cov-report=html

View coverage report in backend/htmlcov/index.html

• POST /api/auth/register - Register a new user
• POST /api/auth/login - Login and get JWT token
• POST /api/auth/password-reset-request - Request password reset
• POST /api/auth/password-reset - Reset password with token

• GET /api/packages/carriers - Get supported carriers
• POST /api/packages/ - Add a new package
• GET /api/packages/ - List all user packages
• GET /api/packages/{id} - Get package details
• PUT /api/packages/{id} - Update package
• DELETE /api/packages/{id} - Delete package
• GET /api/packages/{id}/track - Get real-time tracking info

The package tracking system uses KeyDelivery API for universal carrier support:

from app.strategies import keydelivery

# Detect carrier from tracking number
carriers = keydelivery.detect_carrier(tracking_number)

# Track package with specific carrier
tracking_info = keydelivery.track(tracking_number, carrier_code)

The system supports 20+ carriers through KeyDelivery:

• International: DHL, UPS, FedEx, USPS, TNT, Aramex
• European: Correos, GLS, SEUR, Deutsche Post DHL, Royal Mail
• Asian: China Post, SF Express, Japan Post, Singapore Post
• And many more!

• Password Hashing: bcrypt for secure password storage
• JWT Tokens: Secure authentication with expiration
• SMTP Password Recovery: Secure password reset flow
• Input Validation: Pydantic models for request validation
• CORS Configuration: Controlled cross-origin access
• Environment Variables: Sensitive data stored securely

1. Make changes to code
2. Run tests: pytest
3. Check coverage: pytest --cov=app
4. Build and test with Docker: docker-compose up --build
5. Commit and push changes

All carriers supported by KeyDelivery are automatically available. To add a new carrier to the system:

1. Add the carrier to backend/app/data/carriers.py:

CARRIERS = [
    ("dhl", "DHL"),
    ("ups", "UPS"),
    ("new_carrier", "New Carrier Name"),  # Add here
    # ... other carriers
]

2. The carrier will automatically be available in the API and frontend

No code changes needed - KeyDelivery handles all tracking logic!

Contributions are welcome! Please ensure:

• Tests pass and coverage remains above 80%
• Code follows existing patterns
• New features are properly documented

This project is open source and available under the MIT License.

• xhiena

• FastAPI for the excellent web framework
• React for the frontend library
• PostgreSQL for reliable data storage