🚚 OmniLogistics Core

A full-stack logistics platform built with modern architecture patterns, showcasing Clean Architecture in NestJS, React Native mobile app, and an admin dashboard.

✨ Features

• Real-time Driver Tracking — WebSocket-based live location updates using Socket.IO
• Trip Management — Full lifecycle from request to completion with fare calculation
• Complaint System — AI-powered complaint analysis (Gemini integration)
• Wallet System — Ledger-based financial operations with double-entry bookkeeping
• Multi-role Authentication — Passport JWT for passengers, drivers, and admins
• Background Jobs — BullMQ for trip completion and notification scheduling

🏗️ Architecture

omnilogistics-core/
├── apps/
│   ├── api/           # NestJS Backend (Clean Architecture)
│   ├── mobile/        # Expo React Native App
│   └── admin/         # Admin Dashboard
├── packages/
│   ├── shared/        # Shared TypeScript types
│   ├── db/            # Prisma Schema (PostgreSQL)
│   └── config/        # ESLint, TypeScript, Prettier configs
├── docs/              # Architecture documentation
└── turbo.json         # Monorepo orchestration

🚀 Quick Start

Prerequisites

• Node.js 20+
• npm 10+
• Docker & Docker Compose

One-Command Setup

# Clone and setup everything automatically
git clone https://github.com/yourusername/omnilogistics-core.git
cd omnilogistics-core
./scripts/setup-local.sh

Manual Setup

# 1. Clone the repository
git clone https://github.com/yourusername/omnilogistics-core.git
cd omnilogistics-core

# 2. Start Docker services (PostgreSQL, MongoDB, Redis)
docker compose up -d

# 3. Install dependencies
npm install

# 4. Environment variables are created automatically by the setup script
# Or manually: cp .env.example .env

# 5. Generate Prisma client and run migrations
cd packages/db && npx prisma generate && npx prisma migrate deploy
cd ../..

Development

# Start all apps in development mode
npm run dev

# Start specific app
npm run dev --filter=api        # API only (http://localhost:3000)
npm run dev --filter=admin     # Admin only (http://localhost:5173)
cd apps/mobile && npm start    # Expo (requires Metro)

Build

# Build all apps
npm run build

# Type check all packages
npm run typecheck

# Lint all packages
npm run lint

Docker Services

Service	Port	Credentials
PostgreSQL	5432	postgres:postgres
MongoDB	27017	mongo:mongo
Redis	6379	No auth

Database: omnilogistics

Connection URL:

postgresql://postgres:postgres@localhost:5432/omnilogistics?schema=public

To stop services: docker compose down To reset data: docker compose down -v (deletes all data)

📱 Apps

App	Description	Tech Stack
apps/api	REST API + WebSocket server	NestJS, MongoDB, PostgreSQL, Redis
apps/mobile	Passenger & Driver app	Expo, React Native, Zustand
apps/admin	Admin dashboard	React, Vite

📦 Packages

Package	Purpose
@omnilogistics/shared	Shared TypeScript types and constants
@omnilogistics/db	Prisma schema and database configuration
@omnilogistics/config	Shared ESLint, TypeScript, Prettier configs

🛠️ Tech Stack

Backend

• Framework: NestJS 11 with TypeScript strict mode
• Databases: MongoDB (documents) + PostgreSQL (relational)
• Cache/Queue: Redis + BullMQ
• Real-time: Socket.IO
• Auth: Passport JWT with bcrypt

Mobile

• Framework: Expo SDK 54
• State: Zustand for global state
• Navigation: Expo Router (file-based routing)
• API Client: Axios + React Query
• Maps: React Native Maps with Google Maps API

DevOps

• Monorepo: Turborepo 2.4
• Linting: ESLint flat config
• Code Quality: Prettier + Husky + Commitlint

📂 Project Structure

apps/
├── api/
│   ├── src/
│   │   ├── logistics/
│   │   │   ├── domain/          # Entities, Value Objects, Ports
│   │   │   ├── application/     # Use Cases, DTOs, Services
│   │   │   └── infrastructure/   # Controllers, Adapters, Gateways
│   │   ├── shared/               # Cross-cutting concerns
│   │   └── main.ts
│   └── test/
│
├── mobile/
│   ├── app/                      # Expo Router screens
│   │   ├── (auth)/               # Auth screens
│   │   ├── (passenger)/          # Passenger screens
│   │   └── (driver)/             # Driver screens
│   ├── components/               # Reusable UI components
│   ├── services/                 # API integration
│   ├── store/                    # Zustand stores
│   └── constants/                 # App constants
│
└── admin/
    ├── index.html
    ├── styles.css
    └── app.js

🔌 API Endpoints

Method	Endpoint	Description
POST	/auth/login	User authentication
POST	/auth/register	User registration
GET	/trips	List all trips
POST	/trips	Create new trip
GET	/trips/:id	Get trip details
PATCH	/trips/:id	Update trip status
POST	/complaints	Submit complaint
GET	/complaints	List complaints
PATCH	/complaints/:id	Update complaint status
WS	/tracking	Real-time driver location

📖 Documentation

• Architecture Overview
• API Documentation
• Mobile App Setup
• Admin Dashboard

🤝 Contributing

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

📄 License

This project is proprietary and unlicensed.

---

Built with 💜 using NestJS, React Native, and Turborepo