Hambaar - Package Delivery Platform

A modern, scalable package delivery platform that matches package senders with transporters, built with Node.js, NestJS, PostgreSQL, and Redis.

The system uses a modern containerized architecture with frontend/backend separation, leveraging relational and non-relational databases, cloud storage, and third-party API integrations.

• Frontend Container: Vue.js with Nginx for serving static files and handling HTTP requests with JWT cookies
• Backend Container: NestJS/Node.js handling core business logic, REST APIs, JWT authentication, and third-party API processing
• PostgreSQL Database: Self-hosted in Docker container, storing relational data (packages, users, delivery records) via Prisma ORM
• Redis: Self-hosted in Docker container with multiple databases:
  • Database 1: OTP data (one-time passwords)
  • Database 2: Session data
• AWS S3: Cloud storage for package images and transporter documents using pre-signed URLs
• External APIs:
  • Neshan Maps API: Map data and routing analysis
  • SMS API: OTP and notification delivery
  • Validation API: Transporter verification (personal info, vehicles)

Our PostgreSQL database is designed for scalability and data integrity:

Our security system implements a comprehensive authentication flow:

sequenceDiagram participant U as User participant S as System participant SMS as SMS Service U->>S: Phone Number S->>SMS: Send OTP SMS-->>U: OTP Code U->>S: Verify OTP S->>U: Temporary Token (20min) alt Sender Registration U->>S: Complete User Registration S->>U: Access Token (20 days) else Transporter Registration U->>S: User Registration (Stage One) S->>U: Progress Token (2 days) U->>S: Complete Authentication (Stage Two and Three) S->>U: Access Token (20 days) end 

• Role-based Access Control (RBAC)
• Resource ownership validation
• Route-level protection
• API rate limiting
• Input sanitization

flowchart TD A[New Package Created] --> B{Basic Filters} B -->|Active Trips| C{Geographic Analysis} B -->|No Match| Z[No Matches Found] C -->|Route Compatible| D{Capacity Check} C -->|Out of Route| Z D -->|Sufficient Capacity| E[Calculate Score] D -->|Over Capacity| Z E --> F[Rank Matches] F --> G[Present to Sender] G --> H{Sender Selects} H -->|Request Sent| I[Transporter Review] H -->|No Selection| Z I -->|Accepted| J[Match Confirmed] I -->|Rejected| K[Try Next Match] K --> G J --> L[Payment Opened] 

Our dynamic pricing system considers multiple factors for fair and competitive rates:

Major city advantages and rural area adjustments ensure fair pricing across all regions:

• Distance Deviation: 2,000 IRR per extra kilometer
• Time Deviation: 1,500 IRR per 10 minutes

Complete workflow from trip start to completion:

1. Trip Start: Transporter declares trip beginning
2. Package Pickup: Confirmation of package collection
3. Status Updates: Real-time location and status updates
4. Package Delivery: Delivery confirmation with codes
5. Trip Completion: Final trip closure and settlements

• Automatic Events: Trip start, pickup, delivery completion
• Manual Updates: Transporter location and status updates
• GPS Integration: Location-based city and route detection

Secure file management using AWS S3:

• Transporter Documents:

  • Profile pictures
  • National ID cards
  • Driver licenses
  • Vehicle photos
  • Vehicle registration documents

• Package Photos: Sender package documentation

• Balance Tracking: Real-time balance updates
• Escrow System: Payment security during delivery
• Transaction History: Detailed financial records

1. Package Creation: Price calculation and display
2. Payment Processing: Escrow during delivery
3. Delivery Confirmation: Automatic fund release
4. Settlement: Instant wallet updates

Package Price = Base Calculation + Special Handling + Geographic Factors + Deviation Costs Revenue Distribution: ├── Platform Commission (30%) ├── Transporter Share (70%) └── Deviation Fees (100% to Transporter) 

Advanced geographic features using Neshan Maps API:

• Distance/Time Calculation: Route analysis for pricing
• Intermediate Cities: Waypoint discovery for better matching
• Coordinate Management: GPS-based location handling
• Reverse Geocoding: Address extraction from coordinates
• Static Maps: Route visualization
• Navigation: Real-time routing for transporters

• Corridor System: Route deviation tolerance (configurable width)
• GeoJSON Integration: Standard geographic data format
• Turf.js Library: Advanced geospatial calculations

Our dashboard provides real-time insights and statistics tailored for each user role:

• Personal Details: Full name and profile picture
• Transporter Info: Experience, rate and bio
• Financial Status: Wallet balance

Our notification system keeps users informed about critical events and updates:

• Welcome
• Package Created
• Trip Created
• Trip Request Created, Canceled, Accepted and Rejected
• New Transporter Note
• Trip Started and Delayed
• Package Picked Up and Delivered

Ensure you have the following installed:

Create a .env.development or .env.production file with the following configuration:

[Set envs at ./.docker/.env if you use Docker to run project.]

# 🗄️ Database Configuration DATABASE_URL=postgresql://postgres:postgres@hambaar.postgres:5432/hambaar-db # 🔴 Redis Configuration REDIS_PASSWORD=redis REDIS_URL=redis://:${REDIS_PASSWORD}@hambaar.redis:6379 OTP_REDIS_URL=redis://:${REDIS_PASSWORD}@hambaar.redis:6379/1 SESSION_REDIS_URL=redis://:${REDIS_PASSWORD}@hambaar.redis:6379/2 # 🔐 Security Secrets SESSION_SECRET=your-session-secret-here COOKIE_SECRET=your-cookie-secret-here JWT_ACCESS_SECRET_KEY=your-jwt-access-secret JWT_TEMP_SECRET_KEY=your-jwt-temp-secret JWT_PROGRESS_SECRET_KEY=your-jwt-progress-secret # ☁️ AWS S3 Configuration AWS_ENDPOINT=your-s3-endpoint AWS_ACCESS_KEY=your-access-key AWS_SECRET_KEY=your-secret-key AWS_BUCKET_NAME=your-bucket-name # 🌐 External API Keys MAP_API_KEY=your-neshan-api-key MAP_API_URL=https://api.neshan.org/v1 SMS_API_KEY=your-sms-api-key # ⚙️ Optional Configuration (With default values) PORT=3000 COOKIE_MAX_AGE=1296000000 # 15 days CORRIDOR_WIDTH=10 # kilometers # Otp Envs OTP_EXPIRATION_TIME=120000 # 2 minutes MAX_SEND_ATTEMPTS=5 MAX_CHECK_ATTEMPTS=10 SEND_WINDOW=30 * 60 * 1000 # in milliseconds BASE_BLOCK_TIME=20 * 60 * 1000 # in milliseconds ## Pricing envs PRICING_BASE_PRICE=50000 PRICING_FUEL_RATE=200 PRICING_WEIGHT_BASE_RATE=8000 PRICING_PLATFORM_COMMISSION=0.3 PRICING_DRIVER_SHARE=0.7 ### Special Handling Multipliers PRICING_FRAGILE_MULTIPLIER=1.25 PRICING_PERISHABLE_MULTIPLIER=1.35 PRICING_BOTH_FRAGILE_PERISHABLE=1.5 ### City Premium Factors PRICING_MAJOR_CITY_ORIGIN=0.9 PRICING_MAJOR_CITY_DESTINATION=1.2 PRICING_BOTH_MAJOR_CITIES=1.0 PRICING_SMALL_CITY_FACTOR=1.15 ### Route Deviation Costs PRICING_DEVIATION_RATE=2000 PRICING_TIME_DEVIATION_RATE=1500 ### Distance Tier Rates (IRR per km) PRICING_TIER_1_RATE=1200 PRICING_TIER_2_RATE=1000 PRICING_TIER_3_RATE=850 PRICING_TIER_4_RATE=750 PRICING_TIER_5_RATE=650 ### Major Cities (comma-separated) PRICING_MAJOR_CITIES=تهران,اصفهان,مشهد,شیراز,تبریز,اهواز

make prod

docker compose -f ./docker-compose.yml -p hambaar-app \ --profile frontend --profile backend up -d --build

# Run database migrations npm run prisma:push # Seed initial data (admin user, cities, vehicle models) npm run seed

• Frontend: http://localhost:8080
• Backend API: http://localhost:3000
• API Documentation: http://localhost:3000/docs

Our comprehensive API documentation is available through Swagger UI at /docs when the application is running.

• Automated test suites for core functionality
• Integration tests for external API interactions
• Unit tests for business logic components

The project includes a complete CI/CD pipeline:

1. Code Push: Triggers automated workflow
2. Test Execution: Runs comprehensive test suite
3. Build Process: Creates Docker images on test success
4. Registry Push: Pushes images to Docker Hub
5. Deployment: Automatic deployment to Liara Cloud

graph LR A[Code Push] --> B[Automated Tests] B --> C{Tests Pass?} C -->|✅ Yes| D[Build Docker Images] C -->|❌ No| E[Some Tests Are Failed] D --> F[Push to Registry] F --> G[Deploy to Staging] G --> H[Production Deployment] style A fill:#3498db style B fill:#f39c12 style D fill:#27ae60 style G fill:#e74c3c style H fill:#8e44ad 

We welcome contributions to HamBaar! Please follow our guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.