Logistics Route Optimizer

Open Source система управления логистикой для высоконагруженных операций.

---

Проблема

Современные логистические операции требуют надежной системы обработки заказов, отслеживания транспорта и автоматической диспетчеризации. Существующие решения сложны в внедрении и не справляются с высокими нагрузками.

Решение

Logistics Route Optimizer — Open Source TMS с enterprise-grade надежностью:

• Transactional Outbox — ни одного потерянного события
• Saga Dispatch — автоматическая диспетчеризация с retry и компенсацией
• Идемпотентность — без дубликатов при любой нагрузке
• 50 000+ сообщений в секунду — обработка телеметрии без потерь

Устанавливаете на свой сервер — данные никогда не покидают вашу инфраструктуру.

---

Key Features

OSRM Маршрутизация	Open Source Routing Machine с A* алгоритмом. Оптимальные маршруты по дорогам России (12ГБ OSM данных), расчёт ETA с учётом типов дорог
Saga Dispatch	Автоматический подбор ТС, расчёт маршрута, назначение. 5 попыток с exponential backoff
Transaction Outbox	События пишутся в БД в той же транзакции что и данные — гарантия доставки
Высокие нагрузки	Backpressure в Kafka consumer, batch записи в PostgreSQL (50k+ rows/sec), партиционирование
Идемпотентность	Database-based idempotency guards — ни одного дубликата даже при rebalance
PDF Счета	Генерация через pdfkit, хранение в MinIO (S3-совместимое хранилище)
Мониторинг	Prometheus + Grafana (дашборды Kafka lag, gRPC latency, PG pool), Jaeger (distributed tracing), OpenTelemetry
Безопасность	JWT + Refresh tokens, RBAC, API Keys, audit logging

---

Screenshots

	Карта маршрутов в реальном времени
	Контрагенты, договоры, тарифы
	Настройки: пользователи, роли, аудит

---

Архитектура

flowchart TB
subgraph Clients
Web[Web App<br/>localhost:5173]
Mobile[Mobile App]
External[External APIs]
end
subgraph Gateway
API[API Gateway<br/>:3000<br/>JWT · RBAC · WebSocket]
end
subgraph "Backend Services"
Order[order-service<br/>:50051]
Fleet[fleet-service<br/>:50053]
Routing[routing-service<br/>:50054]
Tracking[tracking-service<br/>:50055]
Dispatcher[dispatcher-service<br/>:50056]
Counterparty[counterparty-service<br/>:50057]
Invoice[invoice-service<br/>:50052]
end
subgraph "Databases"
PG1[(pg-order)]
PG2[(pg-fleet<br/>PostGIS)]
PG3[(pg-routing<br/>PostGIS)]
PG4[(pg-tracking<br/>partitioned)]
PG5[(pg-dispatcher)]
PG6[(pg-counterparty)]
PG7[(pg-invoices)]
PGA[(pg-auth)]
end
subgraph Infrastructure
Kafka[Kafka<br/>:9092]
OSRM[OSRM<br/>:5000]
MinIO[MinIO<br/>:9000]
Prometheus[Prometheus<br/>:9090]
Grafana[Grafana<br/>:3001]
Jaeger[Jaeger<br/>:16686]
end
Web --> API
Mobile --> API
External --> API
API --> Order
API --> Fleet
API --> Routing
API --> Tracking
API --> Counterparty
API --> Invoice
Dispatcher --> Order
Dispatcher --> Fleet
Dispatcher --> Routing
Order --> PG1
Order --> Kafka
Fleet --> PG2
Routing --> PG3
Routing -.-> OSRM
Tracking --> PG4
Dispatcher --> PG5
Counterparty --> PG6
Invoice --> PG7
Invoice --> MinIO
API --> PGA
Order -.publish.-> Kafka
Kafka -.consume.-> Dispatcher
Kafka -.consume.-> Tracking

Loading

Сервисы

Сервис	Ответственность	База данных
order-service	Жизненный цикл заказов, Outbox	PostgreSQL
fleet-service	Автопарк, PostGIS геозоны	PostgreSQL + PostGIS
routing-service	Маршруты через OSRM (A*), кеширование, ETA	PostgreSQL + OSRM
tracking-service	GPS телеметрия, batch writes	PostgreSQL (partitioned)
dispatcher-service	Saga orchestrator	PostgreSQL
counterparty-service	Контрагенты, договоры, тарифы	PostgreSQL
invoice-service	Счета, PDF генерация в MinIO	PostgreSQL + MinIO
api-gateway	REST API, auth, aggregation	PostgreSQL

Инфраструктура

Сервис	Порт	Описание
osrm	5000	Open Source Routing Machine — маршрутизация по дорогам России
minio	9000	S3-совместимое хранилище для PDF
prometheus	9090	Сбор метрик
grafana	3001	Дашборды (Kafka lag, gRPC latency, PG pool)
jaeger	16686	Distributed tracing

---

Быстрый старт

# Клонируем
git clone https://github.com/your-org/logistics-optimizer
cd logistics-optimizer
# Полная инициализация (зависимости + OSM данные + Docker образы)
make init
# Запуск (Docker + фронтенд)
make up:dev
# Или отдельно:
make up # Только Docker
make web # Только фронтенд

URL:

• Frontend: http://localhost:5173
• API Gateway: http://localhost:3000
• OSRM: http://localhost:5000 (маршрутизация)
• MinIO: http://localhost:9000 (хранилище PDF)
• Grafana: http://localhost:3001 (admin/admin)
• Jaeger: http://localhost:16686
• Kafka UI: http://localhost:8080

Требования: Docker 24+, Docker Compose 2.20+, pnpm 9+, ~15GB диска

Разработка

# Сборка
make build
# Тесты
make test
make lint
make typecheck
# Логи
make logs
# Очистка
make clean # Контейнеры + тома
make clean:all # + node_modules + osrm-data

---

Tech Stack

Компонент	Технология
Backend	NestJS, TypeScript
База данных	PostgreSQL + PostGIS
Message broker	Apache Kafka
Inter-service	gRPC
Observability	OpenTelemetry, Prometheus, Grafana, Jaeger
Frontend	React, Zustand, TanStack Table

---

Надёжность

Transactional Outbox

asynccreateOrder(dto){returndataSource.transaction(async(em)=>{constorder=em.create(OrderEntity,dto);awaitem.save(order);// Событие в той же транзакции — не потеряетсяawaitem.save(OutboxEvent,{eventType: 'order.created',payload: {orderId: order.id, ...dto}});});}

Saga Dispatch

order.created
→ GetAvailableVehicles (fleet-service)
→ CalculateRoute (routing-service) → AssignVehicle (fleet-service, optimistic lock)
→ UpdateOrderStatus (order-service)
→ Order Assigned ✓
При ошибке:
→ ReleaseVehicle
→ Retry × 5 (1s → 2s → 4s → 8s → 16s)
→ Order Failed

Backpressure

Kafka Consumer → Queue (500) → Batch Writer → PostgreSQL
↓
If overloaded:
Pause Kafka partition
Resume after flush

---

Roadmap

• Kubernetes Helm charts
• СМС/Email уведомления
• Мобильное приложение
• Интеграции (Wildberries, СДЭК, Деловые Линии)

---

Разработка

# Установить зависимости
make install
# Запуск всех сервисов (dev mode)
pnpm start:dev
# Один сервис
pnpm --filter @logistics/order-service start:dev
# Тесты
make test
make lint
make typecheck
# Очистка
make clean
make clean:all

---

Документация

Полная документация доступна в директории docs/:

Файл	Содержимое
docs/README.md	Обзор архитектуры с диаграммами
docs/SERVICES.md	Детальное описание каждого сервиса
docs/COMMUNICATION.md	gRPC методы и Kafka топики
docs/DATABASE.md	Схемы всех баз данных
docs/API.md	REST API reference
docs/FEATURES.md	Паттерны: Outbox, Saga, Idempotency, Backpressure
docs/PROJECT.md	Product vision и бизнес-фичи

---

License

MIT — бесплатно, навсегда, без ограничений.