System Map
Engineering ReferenceEnd-to-end overview of Orda for engineers and founders. Read top to bottom in ~15 minutes.
1. Product Overview
Users create posts from the mobile app or by sending a WhatsApp-style broadcast. Orda Brain parses the message, structures it into LoadPost or VehiclePost records, finds matching recipients, and queues deliveries. Orda Ops monitors quality and feeds corrections back into the AI.
flowchart TD A[User Input] --> B[Orda API] B --> C[Orda Brain] C --> D[LoadPost / VehiclePost] D --> E[Opportunity Matching] E --> F[OpportunityDelivery] F --> G[Delivery Worker / Notifications] C --> H[Orda Ops Review] H --> I[Feedback Loop] I --> C
2. Orda Brain Pipeline
Every inbound broadcast goes through a sequential pipeline before becoming a structured post. The same pipeline is reused by Brain Lab, but runs in an isolated path — no posts or deliveries are created.
flowchart TD A[Raw Broadcast Text] --> B[Block Segmentation] B --> C[Block Classification] C --> D[Post Derivation / Parsing] D --> E[KB Normalization] E --> F[Vehicle Canonicalization] F --> G[Post Persistence] G --> H[Recipient Matching] H --> I[Delivery Queue]
- •Block Segmentation — splits a single messy message into individual route/vehicle items
- •Block Classification — LLM decides load / vehicle / unknown for each block
- •Post Derivation — LLM extracts route, vehicle type, weight, goods from the block
- •KB Normalization — applies normalization_rules.json to fix common spelling variations
- •Vehicle Canonicalization — maps raw vehicle words to canonical types and groups via vehicle_aliases.json
- •Recipient Matching — scores potential recipients using route, city, category, and vehicle group signals
3. Brain Lab Pipeline
Brain Lab processes offline CSV messages through the same AI pipeline (split → classify → parse) without creating posts, notifications, or deliveries. It is completely isolated from production data flows.
flowchart TD A[CSV Upload] --> B[BrainLabSession] B --> C[BrainLabJob per row] C --> D[Split] D --> E[Classify] E --> F[Parse] F --> G[BrainLabBlock] G --> H[Admin Review] H --> I[ClassificationFeedback Source = Lab]
- •CSV Upload — admin uploads a CSV; one BrainLabSession and one BrainLabJob per row are created
- •Isolated queue — BrainLabWorker claims only from brain_lab_jobs; BroadcastWorker never sees Lab rows
- •Same AI pipeline — uses the same splitter, classifier, and parser as production broadcasts
- •No side effects — no LoadPost, VehiclePost, OpportunityDelivery, or notifications are created
- •Lab corrections — ClassificationFeedback.Source = "Lab" keeps corrections out of few-shot injection
Separation at a glance — Production uses: broadcast_messages · LoadPost / VehiclePost · OpportunityDelivery. Brain Lab uses: brain_lab_jobs · brain_lab_blocks. Shared: splitter · classifier · parser (via SplitInput adapter).
4. Core Data Model
Six entities cover the full lifecycle from raw input to matched delivery.
erDiagram
USER ||--o{ LOAD_POST : creates
USER ||--o{ VEHICLE_POST : creates
BROADCAST_MESSAGE ||--o{ LOAD_POST : derives
BROADCAST_MESSAGE ||--o{ VEHICLE_POST : derives
LOAD_POST ||--o{ OPPORTUNITY_DELIVERY : creates
VEHICLE_POST ||--o{ OPPORTUNITY_DELIVERY : creates
BROADCAST_MESSAGE ||--o{ CLASSIFICATION_FEEDBACK : improves| Entity / File | Description |
|---|---|
| User | Driver, broker, transporter — anyone on the platform |
| BroadcastMessage | Raw inbound message captured for Orda Brain processing |
| LoadPost | Structured load demand (route, weight, goods) |
| VehiclePost | Structured vehicle supply (location, vehicle type, route) |
| OpportunityDelivery | A matched post queued for delivery to a specific recipient |
| ClassificationFeedback | Admin correction that improves future AI few-shot examples |
5. Ops Workflow
Orda Ops is not just a monitoring tool — it actively improves the AI and protects data quality.
flowchart TD A[AI Review] --> B[Admin marks Load / Vehicle / Correct] B --> C[ClassificationFeedback saved] C --> D[Used as few-shot examples] D --> E[Future Orda Brain calls improve] F[All Posts] --> G[Review low confidence posts] G --> H[Hide / flag bad data if needed]
- •AI Review — teaches the classifier with real correction examples (highest impact action in this dashboard)
- •All Posts — inspect live post quality, filter by low confidence, hidden, or spam
- •Stale Queue — surface posts with no responses that need attention
- •Verifications — approve or reject user identity documents before granting verified status
- •How to Use — non-technical admin guide; System Map (this page) — engineering reference
6. Knowledgebase
Five JSON files sit alongside the API code and are loaded at startup. They are the bridge between raw user language and the structured data the matching engine needs.
flowchart LR A[Raw Text] --> B[normalization_rules.json] B --> C[LLM Parse / Classify] C --> D[vehicle_aliases.json] D --> E[vehicle_groups.json] E --> F[Matching Signals]
| Entity / File | Description |
|---|---|
| vehicle_aliases.json | Raw vehicle words → canonical type (e.g. 32ft sxl → SXL) |
| vehicle_groups.json | Canonical type → group (e.g. SXL → CONTAINERS) |
| normalization_rules.json | Fixes common spelling and typing variations before LLM sees the text |
| weight_mappings.json | Vehicle type → expected weight hints used in parsing |
| intent_phrases.json | Phrases that signal load / vehicle / unknown classification |
7. Infrastructure Overview
High level only. For exact implementation details, inspect the API, ops app, and mobile app repositories.
flowchart TD A[Flutter App] --> B[Orda API] C[Orda Ops / Next.js] --> B B --> D[(PostgreSQL)] B --> E[OpenAI / Claude LLM] B --> F[Messaging Provider] B --> G[Supabase Storage]
The API is ASP.NET Core 9. State is in PostgreSQL via EF Core. LLM calls go to OpenAI or Claude depending on task. Documents are stored in Supabase Storage with short-lived signed URLs. Push notifications use Firebase Cloud Messaging.
This page is read-only and has no backend dependency. Update it by editing app/system-map/page.tsx.