Parcel Locker

A smart, automated parcel locker management system built in Python. The application simulates a real-world parcel delivery infrastructure — complete with multi-city locker networks, intelligent compartment allocation, email notifications, report generation, and a hands-free voice-controlled interface powered by OpenAI and ElevenLabs.

---

Table of Contents

• Overview
• Key Features
• Architecture
• Project Structure
• Tech Stack
• Getting Started
• Running Tests
• License

---

Overview

The Parcel Locker project models a complete parcel delivery ecosystem. Users can send and receive parcels through automated lockers placed across multiple cities. The system handles the entire lifecycle — from parcel registration through locker assignment to delivery tracking — all while keeping users informed via automated email updates.

What sets this project apart is its voice control integration: using speech recognition and AI-powered text-to-speech, users can interact with the system entirely hands-free, querying delivery statuses and managing parcels through natural conversation.

---

Key Features

Parcel & Locker Management

• Register users, parcels, and lockers with full data validation
• Assign parcels to locker compartments based on size (Small / Medium / Large)
• Track deliveries with sender, receiver, send date, and expected delivery date
• Support for multiple cities with GPS coordinates (New York, Los Angeles, Chicago, San Francisco)

Email Notifications

• Automated email alerts for parcel status updates
• Notifications about available locker space
• Report delivery via email with file attachments
• SMTP integration with secure credential management via .env

Voice Control Interface

• Speech-to-text input using Google Speech Recognition
• AI-powered text-to-speech responses via ElevenLabs
• Natural language interaction powered by OpenAI GPT
• Conversational interface for querying deliveries and managing parcels

Data Persistence & Validation

• JSON-based data storage for users, parcels, lockers, and deliveries
• Comprehensive input validation with dedicated validator classes
• Type-safe data models with converter layer for JSON serialization
• Repository pattern for clean data access abstraction

Reporting

• Automated report generation with delivery summaries
• Export reports to text files

---

Architecture

The project follows a layered architecture with clear separation of concerns:

┌──────────────────────────────────────────────────┐
│                   main.py                        │
│              (Application Entry Point)           │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌─────────────────┐    ┌──────────────────────┐ │
│  │ SpeechRecognizer │    │  EmailService        │ │
│  │ (Voice Control)  │    │  (Notifications)     │ │
│  └────────┬────────┘    └──────────┬───────────┘ │
│           │                        │             │
│  ┌────────▼────────────────────────▼───────────┐ │
│  │         PurchaseSummaryService               │ │
│  │         (Core Business Logic)                │ │
│  └────────┬────────────────────────┬───────────┘ │
│           │                        │             │
│  ┌────────▼────────┐    ┌─────────▼────────────┐ │
│  │   Repositories   │    │  ReportGenerator     │ │
│  │ (Data Access)    │    │  (Reports)           │ │
│  └────────┬────────┘    └──────────────────────┘ │
│           │                                      │
│  ┌────────▼────────────────────────────────────┐ │
│  │  Validators → Converters → FileService      │ │
│  │  (Validation)  (Serialization) (JSON I/O)   │ │
│  └─────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

Design Patterns Used

Pattern	Where	Purpose
Repository	repository.py	Abstract data access from business logic
Strategy	validator.py	Pluggable validation rules per entity type
Converter	converter.py	Separate serialization logic from domain models
Service Layer	service.py	Encapsulate business operations
Dependency Injection	main.py	Wire components together at the entry point

---

Project Structure

ParcelLocker/
├── main.py                         # Application entry point
├── Pipfile                         # Dependency management
├── Pipfile.lock
├── pytest.ini                      # Test configuration
│
├── data/                           # JSON data storage
│   ├── users.json
│   ├── parcels.json
│   ├── lockers.json
│   └── delivers.json
│
├── src/                            # Source code
│   ├── model.py                    # Domain models (Users, Parcels, Lockers, Delivers)
│   ├── validator.py                # Input validation for all entity types
│   ├── converter.py                # JSON ↔ domain model converters
│   ├── file_service.py             # JSON file readers/writers
│   ├── repository.py               # Data repositories (CRUD operations)
│   ├── service.py                  # Business logic (PurchaseSummaryService)
│   ├── email_sender.py             # SMTP email sending
│   ├── email_service.py            # Email notification service
│   ├── report_generate.py          # Report generation
│   ├── speech_recognizer.py        # Voice control interface
│   └── speech_recognizer_service.py # Speech recognition service layer
│
└── tests/                          # Unit tests (pytest)
    ├── conftest.py                 # Shared test fixtures
    ├── conventer/                  # Converter tests
    ├── email_sender/               # Email sender tests
    ├── email_service/              # Email service tests
    ├── file_service/               # File service tests
    ├── model/                      # Model tests
    ├── report_generate/            # Report generator tests
    ├── repository/                 # Repository tests
    ├── service/                    # Service tests
    ├── speech_recognizer/          # Speech recognizer tests
    ├── speech_recognizer_service/  # Speech recognizer service tests
    └── validator/                  # Validator tests

---

Tech Stack

Technology	Purpose
Python 3.13	Programming language
OpenAI API	Natural language understanding for voice commands
ElevenLabs	AI-powered text-to-speech voice responses
SpeechRecognition	Speech-to-text input processing
PyAudio	Microphone audio capture
geopy	Geolocation and distance calculations
email-validator	Email address validation
python-dotenv	Secure environment variable management
pytest	Unit testing framework
pytest-cov	Test coverage reporting
mypy / pyright	Static type checking
Pipenv	Dependency & virtual environment management

---

Getting Started

Prerequisites

• Python 3.13+
• Pipenv
• A microphone (for voice control features)
• API keys for OpenAI and ElevenLabs (optional, for voice features)

Installation

# Clone the repository
git clone https://github.com/WiktoriaSmulska/ParcelLocker.git
cd ParcelLocker

# Install dependencies
pipenv install --dev

# Activate the virtual environment
pipenv shell

Configuration

Create a .env file in the project root with your credentials:

SMTP_SERVER=smtp.gmail.com
PORT=587
SENDER_EMAIL=your-email@gmail.com
SENDER_PASSWORD=your-app-password
OPENAI_API_KEY=your-openai-key
ELEVENLABS_API_KEY=your-elevenlabs-key

Running the Application

pipenv run start
# or
python main.py

---

Running Tests

The project includes a comprehensive test suite covering all modules:

# Run all tests with coverage
pipenv run test

# Run type checking
pipenv run check      # pyright
pipenv run check2     # mypy

---

License

This project is open source and available for academic and educational purposes.

---

Author

Wiktoria Smulska — GitHub