Dispatch Main

This repository serves as the central orchestration point for the entire ecosystem, providing infrastructure configuration, API gateway management, and service coordination.

Quickstart

To fetch all the services and run the platform:

make run

This configures everything EXCEPT the keycloak realm. To configure that, run the import-realm script:

python keycloak/import-realm.py

Double check to see if the dispatch realm has been added to keycloak afterwards.

Access Points:

• API Gateway: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Keycloak Admin: http://localhost:8081

---

Overview

The Dispatch platform follows a modern microservices architecture:

• API Gateway (Kong): Single entry point for all client requests, handling routing to various services.
• Identity & Access Management (Keycloak): Centralized authentication and authorization.
• Object Storage (SeaweedFS): S3-compatible storage for logos, documents, and other binary data.
• Relational Data (Postgres): Primary transactional database for services.
• Time-Series Data (TimescaleDB): Optimized storage for analytics and event tracking.
• Caching (Redis): High-performance data caching.

Services

• Management Service: Admin portal and platform-wide configuration.
• Merchant Service: Handles merchant profiles, API keys, and merchant-specific settings.
• Courier Service: Manages courier companies, supervisors, and drivers.
• Shipment Service: Core logic for creating, tracking, and managing the lifecycle of shipments.
• Analytics Service: Processes and provides insights from platform events.

---

Prerequisites

Ensure you have the following installed:

• Docker & Docker Compose
• Make (optional, but recommended for easy setup)

---

Additional Setup

Running Dependencies Only

If you are developing a specific service locally and only need the infrastructure:

make install-dependencies

Alternatively: docker compose -f dependencies.yml up -d

Stopping the Platform

make stop

Alternatively: docker compose -f docker-compose.dev.yml down

---

API Documentation

The platform includes a built-in documentation service accessible at http://localhost:8000/docs.

The documentation is generated using Bruno and served via OpenCollection. You can find the raw Open API specifications in the docs/open-api/ directory.

---

Repository Structure

├── docs/               # API documentation and spec files
├── keycloak/           # Keycloak realm exports and setup scripts
├── kong/               # API Gateway declarative configuration
├── postgres/           # Database initialization scripts
├── dependencies.yml    # Infrastructure-only docker-compose
├── docker-compose.yml  # Full platform docker-compose
└── makefile            # Automation scripts for setup and deployment