By Muhammad Umar. This is the engineering summary of an open reference architecture. The paper, its object model as JSON and the model register are free to reuse under CC BY 4.0: https://codeatoms.ai/freight-corridor-customs-saudi-arabia/. DOI 10.5281/zenodo.24048557. The operator is described by class, never by name.
A national freight and logistics operator in Saudi Arabia moves containers and bulk from seaports to dry ports and freight yards, by rail and road, across corridors of more than two thousand kilometres. The expensive failure is a chain: a customs declaration stalls at the seaport, the road leg runs late for its train, the handover slot is lost, and the first anyone hears of it is the customer calling. Every fact needed to see that chain early already exists, spread over seven systems that each own one piece of it. The design joins them into one consignment story so a corridor planner sees the stall, the connection it will cost and the customer who will call, and approves the chase and the re booking before the call comes.
1. Seven sources, read only, behind two adapter families
The rail operations and yard management system owns trains, wagons, yard slots and the handover the corridor turns on. The transport management system owns the road legs. The customs authority's declaration and clearance interfaces, the port community system feeds, the haulier telematics feeds, the container tracking system and the customer service case log hold the rest. Every one is bound read only: no agent files, amends, re books or cancels a declaration or a booking, and the design never writes into a system of record.
Data enters through two adapter families, never directly: an integration adapter on Debezium with Apache Camel for the operational systems, and a telemetry adapter for the haulier feeds. Each adapter guarantees three things before any agent reasons over a fact: lineage, ordering and a staleness flag. The staleness flag is the quiet hero here. A stall is defined by time passing without an event, so the system has to know the difference between "nothing happened" and "the feed stopped". Apache Kafka 4.3 in KRaft mode carries every change the adapters emit, in order.
2. Fifteen objects, joined on the container number
The object model holds fifteen typed objects and eleven typed links: consignment, container, declaration, train, wagon, road leg, haulier, terminal, dry port, handover slot, exception and customer case, with the corridor planner, yard controller and service desk agent as actors. It is a projection over the seven systems, held in Hyper Ontology v0.9, never a migration and never a copy. It owns no record, only the crossing mappings that answer questions no single system can, and the key it joins on is the container number every system already carries.
A projection only works if the join is honest, so the design carries a weekly join success gate at 95 per cent with failures triaged by source system. A join failing silently is worse than no join at all.
3. One node, sized by arithmetic
GLM 5.3 is named by the requirement for the command center that answers questions about a consignment with citations, with GLM 5.2 under MIT as the licence fallback, and the register commits no model row until a live verification passes. At FP8 the weights take about 756 GB. One node of eight 141 GB HBM cards gives about 1,038 GB usable, which leaves about 280 GB of KV cache ceiling, and one node serves the phase one corridor. It sits in the operator's own data center in the country at about ten kilowatts of rack power. There is no edge tier, no camera and no new field sensing: everything this design needs is already being recorded. The node is a 4A090 class item for a D:3 and D:4 destination, so an export licence determination is a phase zero checkpoint before any GPU class is quoted.
Appendix A prices the node at about 569,000 US dollars to own over three years (541,000 to 594,000). Renting the same eight cards on the deepest three year commitment in AWS Middle East (UAE) is about 751,000, so ownership costs about three quarters of it; on demand is about 2.00 million. Renting is a price reference only: AWS listed no Saudi region on the day read, and every rented option would carry cargo, customer and declaration data across the border.
4. Three agents, named people
The agents draft and people decide, by name. The corridor planner approves the stall chase and the revised handover slot, the yard controller approves every re booking, and the service desk agent sends the cited answer. Approval authority is a property of the actor objects in the model, not a setting in an app. A per shift alert budget is agreed before any threshold is set, and the action rate is itself a gate. Nothing is trained into weights: every confirmed stall cause and accepted re booking is kept as memory the next plan reads.
5. Gates, not dates
Three phases carry 17 scope items (2, 14 and 1). Baseline and approvals first, gated on the residency approvals closing and the baseline being recorded. Then one corridor between one seaport and one dry port for a measured quarter, whose exit gate is the source bindings and lineage proven on one real week of production data. Then the other corridors. The headline measure is dry port dwell in hours against a nominal of 96, with stalled declarations, missed connections and answered questions counted beside it.
Made with CodeNinja Praxis, the CodeNinja Atoms platform for designing physical AI systems. The object model imports into Hyper Ontology. Paper, ontology and register: https://codeatoms.ai/freight-corridor-customs-saudi-arabia/
One of the CodeNinja Atoms worked examples of a sovereign AI architecture: read only systems of record below, a projection ontology joined by typed links, open weights on hardware the operator owns in its own country, and agents that draft while named people approve.
Top comments (0)