Centralized AI production ecosystem powering a high-throughput intercity delivery platform. Four fully decoupled, stateless microservices handling computer vision, risk compliance, dynamic pricing, and customer guidance.
- Core Engineering Principles
- Microservice Ecosystem
- System Architecture
- Cross-Cutting Production Standards
- Infrastructure & Sizing Matrix
- Project Structure
- Getting Started
The ML suite is built around three strict software engineering paradigms to guarantee high availability across the full logistical grid.
| Principle | Description |
|---|---|
| Asynchronous Isolation | ML workloads are fully decoupled from the primary transactional database and Spring Boot API gateway — heavy inference cycles cannot exhaust transactional thread pools. |
| Stateless Ephemerality | Every microservice retains zero session or image footprint on disk. All inference runs through volatile RAM buffers, eliminating file I/O overhead and state synchronization complexity. |
| Hardware Efficiency | Neural networks and text embeddings are optimized for CPU-first deployments (x86_64 / ARM64) via quantization and matrix pruning, significantly reducing cloud hosting costs. |
Port 8001 · Courier Onboarding & KYC Compliance
Handles automated driver verification and KYC compliance checks during courier onboarding.
Tech Stack: FastAPI · PaddleOCR (PP-OCRv3 Arabic Weights) · OpenCV
Pipeline — Multi-Tier Fallback Strategy:
- Tier 1 — Isolates a focused Region of Interest (ROI) bounding box on the bottom 30% of the card to instantly compute characters.
- Tier 2 — Falls back to full-image text line tracking if Tier 1 yields low confidence.
- Tier 3 — Applies Adaptive Threshold Binarization to correct lighting anomalies or card skew.
After extraction, the engine validates structural checksum constraints including birth century indices, Gregorian calendar constraints, and official Egyptian Ministry of Interior governorate codes.
Port 8002 · Freight Pricing Across Intercity Zones
Computes optimal shipping and freight transport margins across distinct regional delivery zones.
Tech Stack: FastAPI · Scikit-Learn · Pandas
Pipeline — Semi-Supervised Ensemble Learning:
- Trains a
Random Forest Regressorvia an iterative Pseudo-Labeling Workflow, fusing sparse baseline market prices with continuous operational telemetry. - Ingests a multi-dimensional feature tensor:
| Feature Type | Fields |
|---|---|
| Geospatial | pickup_lat, pickup_lng, drop_lat, drop_lng |
| Structural | pickup_zone, drop_zone |
| Climate | temperature, rain |
| Temporal | day_of_week |
Port 8003 · Cargo Compliance & Safety Filtering
Inspects cargo attachment images during order booking to enforce shipping guidelines before orders reach the courier pool.
Tech Stack: FastAPI · PyTorch (CPU Runtime) · Ultralytics (Custom Object Detection)
Pipeline:
- Intercepts incoming binary image payloads directly in memory — no disk writes.
- Scans for unauthorized objects, protected cargo types, or live animals.
- Flags compliance exceptions at the entry gateway, drastically reducing manual inspection overhead.
Port 8004 · 24/7 Customer Support & Package Tracking
Provides scalable client onboarding, FAQ resolution, and package tracing without relying on heavy LLMs.
Tech Stack: FastAPI · Classical NLP Intent Matrices · TF-IDF Vectorizers
Pipeline:
- Engineered as a lightweight, production-grade alternative to over-engineered language models.
- Uses sparse text tokenization and synchronous mathematical intent classification.
- Guarantees ≤ 15ms response time under heavy concurrent load while consuming ≤ 100MB server memory.
All AI microservices operate inside an isolated private subnet, accessible exclusively via authenticated internal REST calls from the Spring Boot backend.
[ Flutter Mobile Frontend ]
│
▼ HTTPS (Public Traffic)
┌──────────────────────────────┐
│ API Gateway / Load Balancer │
└──────────────────────────────┘
│
▼ Internal Subnet
┌──────────────────────────────┐
│ Java Spring Boot Backend │
└──────────────────────────────┘
│
├──► [Port 8001] 𓋹 National ID OCR Service
├──► [Port 8002] 📊 Dynamic Pricing Engine
├──► [Port 8003] 🐾 Animal Image Checker
└──► [Port 8004] 💬 Delivery Guidance Chatbot
Zero Disk Trace
Raw images uploaded for OCR or safety filtering are decoded directly into memory via cv2.imdecode() — no temporary files ever touch permanent block storage.
Automated PII Log Masking
A custom logging.Filter pipeline interceptor scans all string buffers for PII identifiers and automatically replaces them with star masks (e.g., **********2456) before writing to any output stream.
Controlled Access Serialization
APIs always emit masked placeholders in responses. Raw data properties are only returned when the calling internal system explicitly injects the return_full=true authorization flag.
Token Bucket Rate Control Each service runs an isolated, thread-safe memory token bucket to prevent DoS states or execution stalls during flash-sale traffic spikes.
Strict Computation Cutoffs
All operations are protected by hard processing windows (e.g., REQUEST_TIMEOUT_MS=900). Requests that exceed the boundary are instantly dropped with a safe timeout error structure, preserving hardware cycles for downstream tasks.
Every service is packaged in hardened Linux containers using opencv-python-headless base layers to remove graphical utility bloat and minimize the system attack surface.
| Service | Container Name | Base Image | Port | CPU | RAM | p95 Latency |
|---|---|---|---|---|---|---|
| National ID OCR | national-id-ocr |
python:3.11-slim |
8001 | 2.0 vCPU | 2.5 GB | ≤ 850ms |
| Dynamic Pricing | dynamic-pricing |
python:3.11-slim |
8002 | 1.0 vCPU | 1.5 GB | ≤ 45ms |
| Animal Image Checker | animal-image-checker |
python:3.11-slim |
8003 | 2.0 vCPU | 2.0 GB | ≤ 350ms |
| Guidance Chatbot | guidance-chatbot |
python:3.11-slim |
8004 | 0.5 vCPU | 100 MB | ≤ 15ms |
MLGraduationTasks/
│
├── .gitattributes # Git LFS tracking config for deep learning weights
├── .gitignore # Build, environment, and PII exclusion filters
│
├── Egyptian National ID OCR/ # Driver & Courier Verification Service
│ ├── app/api/routes.py # Rate-limited async multipart endpoint handlers
│ ├── ocr_engine/ # Thread-safe PaddleOCR singleton wrapper
│ └── Dockerfile # Non-root user hardened execution template
│
├── dynamic_pricing/ # Geographical Delivery Pricing Engine
│ ├── deployment/api_service.py # Core FastAPI dynamic matrix endpoint handlers
│ ├── src/reinforced_trainer.py # Semi-supervised pseudo-labeling training loop
│ └── Dockerfile # Lightweight multi-stage distribution image
│
├── animal-image-checker/ # Safety & Compliance Checking Module
│ ├── app/services/ # In-memory matrix evaluation & filtering hooks
│ └── requirements.txt # Stripped dependencies (no GUI layers)
│
└── delivery-guidance-chatbot/ # Customer Care Virtual Assistant
├── main.py # High-availability intent classification API
└── training/ # Matrix vectorizer caching pipelines
Neural network weights and serialized model files are tracked via Git LFS. Make sure LFS is active before cloning.
# Activate Git LFS hooks on your workstation
git lfs install
# Clone the full engineering suite
git clone https://github.com/Graduation-Projectttt/graduation_ML.git
cd graduation_ML
# Pull all tracked neural network weights and serialized models
git lfs pullEach subdirectory is a fully independent project scope. To spin up any module:
# Enter the target service directory
cd "Egyptian National ID OCR"
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies and pre-cache model assets
pip install -r requirements.txt
python scripts/download_models.py
# Launch the local development server
uvicorn api.main:app --host 0.0.0.0 --port 8001Repeat the same steps for any other service — just change the directory and port number accordingly.
Built for the Graduation Project — Intercity Delivery Platform · Enterprise ML Engineering Suite