eBikes Africa — Orders Service

Manages the full order lifecycle for the eBikes Africa dispatch platform — from draft creation and bulk CSV import through to delivery, payment confirmation, and incident tracking.

---

Overview

The Orders service is the authoritative source of order state within the eBikes Africa platform. It governs the complete lifecycle of a delivery order, from pre-order drafts and bulk manifests through to terminal completion, cancellation, or loss. All downstream services — Assignment, Payment, and Notifications — integrate against the order state machine defined here.

Document storage for bulk CSV manifests uses AWS S3 via presigned URLs — clients upload directly to S3, the service confirms and processes the document asynchronously. Delivery tokens provide a short-lived, rate-limited portal for customers to submit or correct delivery location details without authentication.

Owns:

• Draft creation and bulk CSV manifest import
• Order lifecycle state machine and status transitions
• Cost adjustments (vendor-initiated price corrections)
• Delivery timeline tracking
• Delivery tokens and customer-facing delivery portal
• Tips and tip payment status
• Incident reporting and history
• Agent reassignment requests
• CSV document upload (presigned S3 flow)
• Outbox event log and retry management

Does not own:

• Agent identity and eligibility — belongs to Workforce Management
• Assignment strategy and candidate selection — belongs to Assignment
• Payment processing and M-Pesa integration — belongs to Payment & Billing (future)
• Routing and distance calculations — belongs to Routing & Pricing
• Vehicle lease management — belongs to Vehicles (future)

---

Platform Context

Relationship	Service	How
Consumed by	Assignment	Publishes OrderPendingAssignment — Assignment picks up and runs strategy
Consumed by	Notifications	OrderCreated, OrderCancelled, OrderDelivered etc. via RabbitMQ outbox
Publishes to	All	Order lifecycle events via RabbitMQ outbox pattern
Consumes	Assignment	AssignmentSucceeded, AssignmentFailed routing keys
Consumes	Routing & Pricing	ContactsResolved — enriches order with resolved contact data
Consumes	Payment & Billing	PaymentVerified, TipProcessed routing keys
Consumes	Delivery Agent	PickupConfirmed, DeliveryConfirmed routing keys
Auth via	Keycloak	JWT / OIDC — all endpoints require Bearer token except /delivery/{shortCode}
Storage	AWS S3	CSV manifest uploads via presigned URL — bucket: ebikes-orders-docs-{env}

---

Tech Stack

Concern	Technology
Language	Java 21
Framework	Spring Boot 3.x
Database	PostgreSQL (Liquibase migrations)
Messaging	RabbitMQ (outbox pattern)
Auth	Keycloak (JWT / OIDC)
Storage	AWS S3 (presigned URLs)
Cache	Redis (rate limiting)

---

Prerequisites

Tool	Version	Notes
Java	21+	Use SDKMAN: sdk install java 21
Docker	20.10+	Required for all local dependencies
Docker Compose	v2.0+	Bundled with Docker Desktop
Maven	3.9+	Or use the included mvnw
LocalStack	latest	S3 emulation for local document uploads
Redis	7+	Rate limiting for delivery token portal

---

# 1. Copy environment template and configure
cp .env.example .env
# Edit .env — see inline comments for required values

# 2. Start infrastructure dependencies
docker compose up -d

# 3. Run the service
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

S3: CSV document upload requires a running LocalStack instance. The .env.example points to http://localhost:4566 by default. AWS credentials are not required locally — LocalStack accepts AWS_ACCESS_KEY_ID=test and AWS_SECRET_ACCESS_KEY=test.

Redis: The delivery token rate limiter requires a running Redis instance. The .env.example points to localhost:6379 by default with no auth required for local development.

---

Running Tests

# Full verify — mirrors the CI quality gate
./mvnw verify

# Unit tests only
./mvnw test

Coverage report: target/site/jacoco/index.html

---

Database Schema

---

Environments & Deployment

Environment	Trigger	Image tag
dev	Push to dev (after CI passes)	dev + sha-*
staging	Push to staging (after CI)	staging + sha-*
production	Release Please semver tag	vX.Y.Z + sha-*

Images are published to AWS ECR. CI pipeline: .github/workflows/