Repository navigation
Architecture Overview
Atlas Logistics is an event-driven, domain-driven Supply Chain Management (SCM) platform optimized for freight forwarding operations. It is designed around clean bounded contexts, strict aggregate consistency boundaries, transactional event publishing (Outbox Pattern), versioned workflow orchestration, and high-performance CQRS read model projections.
┌──────────────────────────────────────────────────────────────────────────────────┐
│ OPERATIONS BFF │
│ GET /operational/shipments-360 GET /operational/cockpit (My Work Queue) │
│ GET /operational/shipments/:id/360 POST /operational/cockpit/:id/execute │
└────────────────────────────────────────┬─────────────────────────────────────────┘
│ Queries Projected Views
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ CQRS PROJECTION STORE │
│ op_intelligence_shipment_360_views_v2 op_intelligence_cockpit_items_v2 │
└────────────────────────────────────────▲─────────────────────────────────────────┘
│ Updates asynchronously / read-through
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ TRANSACTIONAL OUTBOX & BUS │
│ platform_gov_outbox_v2 ──► platform_gov_inbox_v2 │
│ (PENDING -> PROCESSING -> PROCESSED | FAILED / DLQ) │
└────────────────────────────────────────▲─────────────────────────────────────────┘
│ Emitted inside atomic DB transactions
▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│ OPERATIONAL CORE AGGREGATES │
│ Party & CRM Shipment Execution Transport Planning Workflow Engine │
│ party_crm_* shipment_exec_* transport_plan_* wf_engine_* │
│ Tracking & Milestones Work Management Cargo & Equipment │
│ tracking_* work_mgmt_* cargo_equip_* │
└──────────────────────────────────────────────────────────────────────────────────┘
Persistent storage is backed by normalized SQLite tables (src/db/schema/scm_entities_sqlite.ts):
-
Party & CRM (
party_crm_*):- Aggregate Root:
Party(party_crm_parties_v2). - Owned Entities:
PartyAddress,PartyContact,PartyRole,PartyRelationship,PartyExternalIdentifier. - Invariant: Parties hold polymorphic roles (
CUSTOMER,CARRIER,SHIPPER,CONSIGNEE) without duplicating records.
- Aggregate Root:
-
Shipment Execution (
shipment_exec_*):- Aggregate Root:
Shipment(shipment_exec_shipments_v2). - Owned Entities:
ShipmentReference,ShipmentPartyRole,ShipmentAssignment. - Invariant: A Shipment references other contexts by ID only, not physical navigation. Optimistic locking enforced via
versioncolumn.
- Aggregate Root:
-
Transport Planning (
transport_plan_*):- Aggregate Root:
RoutePlan(transport_plan_route_plans_v2). - Versioned child:
RouteVersion(transport_plan_route_versions_v2). - Composed components:
RouteStop,TransportLeg.
- Aggregate Root:
-
Milestone Tracking (
tracking_*):- Aggregate Root:
MilestonePlan(tracking_milestone_plans_v2). - Dynamic milestones:
Milestone,EstimateRevision.
- Aggregate Root:
-
Work Management (
work_mgmt_*):- Aggregate Root:
Task(work_mgmt_tasks_v2). - Graph Association:
TaskDependency(work_mgmt_task_dependencies_v2). - Invariant: Strict Directed Acyclic Graph (DAG) enforcement. Direct self-loops and transitive multi-hop cycles are rejected before persistence.
- Aggregate Root:
To guarantee that aggregate state changes and domain events never desynchronize:
-
Atomic Transaction Boundaries:
Mutations to aggregates and insertions into
platform_gov_outbox_v2share the exact same SQLite transaction (db.transaction(...)). -
Outbox Lifecycle:
-
PENDING: Enqueued and ready for relay. -
PROCESSING: Picked up by the relay processor. -
PROCESSED: Successfully dispatched to all registered idempotent subscribers. -
FAILED: Dead-lettered after exceeding retry limit (default: 3 attempts).
-
-
Dead Letter Queue (DLQ) & Replay:
Failed events are preserved with error telemetry and can be inspected via
GET /api/scm/v1/operational/outbox/dlqand replayed withPOST /api/scm/v1/operational/outbox/dlq/:eventId/replay. -
Consumer Idempotency:
The
platform_gov_inbox_v2table records(event_id, consumer_id). Duplicate deliveries are safely skipped. -
Command Deduplication:
Endpoints accept
x-idempotency-keyand store execution fingerprints inplatform_gov_command_idempotency_v2. -
Operational Audit Trail:
The causality chain can be reconstructed on demand (
GET /api/scm/v1/operational/shipments/:id/audit-trail):$$\text{Shipment Created} \to \text{Route Planned} \to \text{Milestones Generated} \to \text{Workflow Started} \to \text{Task Completed} \to \text{Task Unblocked}$$
Inspired by BPMN/Camunda but tailored for freight forwarding (src/scm/contexts/workflow-engine/):
-
Separation of Definition vs Instance:
- Definitions:
WorkflowDefinition,WorkflowDefinitionVersion,TaskDefinition,DependencyDefinition. - Instances:
WorkflowInstance,TaskInstance.
- Definitions:
-
Version Immutability:
Once a version transitions to
PUBLISHED, its task definitions and dependency graph become strictly immutable (WORKFLOW_VERSION_IMMUTABLE). -
Pre-Publication DAG Cycle Validation:
Publishing runs a topological cycle detection algorithm (
assertVersionIsDAG). Definitions containing cycles cannot be published. -
Dynamic Instantiation & Materialization:
When a shipment route is planned (
RoutePlanned.v2), the engine selects the active published definition (e.g.,OCEAN_EXPORT_STANDARDv1), instantiatesWorkflowInstance, and materializes tasks intoscmLogicalTasksandscmLogicalTaskDependencies. -
Auto-Finalization:
When the final task of an instance is completed, the workflow instance automatically transitions to
COMPLETEDand emitsworkflow_engine.WorkflowInstanceCompleted.v2.
Optimized for high-performance UI rendering without transactional table joins (src/scm/contexts/operational-intelligence/):
-
Shipment 360 Projected Read Model:
- Stored denormalized in
op_intelligence_shipment_360_views_v2. - Aggregates shipment metadata, routing stops & legs, milestone progress, workflow execution state, health scores, and task action metadata.
- Self-healing read-through: If a view is queried before the outbox ticks, it computes, stores, and serves the projection instantly.
- Stored denormalized in
-
Operations Cockpit ("Work-to-User" Paradigm):
- Stored in
op_intelligence_cockpit_items_v2. - Serves prioritized work queues for operators:
- Only actionable tasks are highlighted (
status === "OPEN"andisBlocked === false). - Blocked tasks clearly document which predecessor task must finish first.
-
attentionScore(0–100) dynamically ranks tasks by priority, service mode, and SLA urgency.
- Only actionable tasks are highlighted (
- Stored in
-
In-situ Execution Endpoint (
POST /operational/cockpit/:workItemId/execute):- Operators resolve tasks directly from the Cockpit view.
- The BFF completes the task, flushes event cascades, re-projects the shipment, and returns newly unlocked work items in the same response.
Atlas Logistics · Enterprise Multimodal Logistics & Freight Forwarding Operating System
Main Repository: xpallares1987-ai/Atlas-Logistics · Licensed Documentation