How samir-saudagar/vortex works
VORTEX is a local baggage-routing and tracking simulator. An operator checks in a bag through the dashboard; the Spring backend records it, verifies flight eligibility, plans a route, and coordinates equipment movement, scanner observations, and bag-state updates. Kafka carries asynchronous workflow and simulator messages, while PostgreSQL is the durable source of truth. The Python simulator processes equipment commands with a durable journal; the React UI presents operational status and journey details. The tree and excerpts establish key calls; several asynchronous connections are shown as documented or unverified.
Main entry points: JourneyController.java Journey REST · MovementService.java Movement coordination · App.tsx Dashboard · PersistentBagLifecycle.java Bag lifecycle
Components 21
Operations dashboard
- Dashboard
frontend/src/app/App.tsx - Operations state
frontend/src/app/useOperations.ts - UI contracts
frontend/src/types/contracts.ts
Backend entry points
- Journey REST
backend/src/main/java/com/vortex/api/rest/JourneyController.java
Baggage workflows
- Check-in service
backend/src/main/java/com/vortex/checkin/application/CheckInService.java - Bag lifecycle
backend/src/main/java/com/vortex/bagstate/application/PersistentBagLifecycle.java - Flight verification
backend/src/main/java/com/vortex/flight/application/PersistentFlightVerification.java - Route planning
backend/src/main/java/com/vortex/routing/application/PersistentRoutePlanning.java - Movement coordination
backend/src/main/java/com/vortex/movement/application/MovementService.java - Retry workflow
backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java
Event transport
- Transactional outbox
backend/src/main/java/com/vortex/messaging/outbox/OutboxWriter.java - Kafka workflow
backend/src/main/java/com/vortex/messaging/kafka/WorkflowKafkaListener.java - Simulator reports
backend/src/main/java/com/vortex/messaging/kafka/SimulatorReportKafkaListener.java - Event envelopes
backend/src/main/java/com/vortex/messaging/envelope/EventEnvelope.java
Equipment simulation
- Kafka adapter
simulator/src/vortex_simulator/kafka_adapter.py - Simulator service
simulator/src/vortex_simulator/service.py - Command journal
simulator/src/vortex_simulator/command_journal.py
Other components
- Operator
- PostgreSQL
- Kafka broker
- Browser client
Connections 27
- Operator → Dashboard: uses
README.md - Dashboard → Operations state: reads
frontend/src/app/App.tsx - Dashboard → Journey REST: requests
- Browser client → Dashboard: renders
- Operations state → UI contracts: uses types
frontend/src/app/useOperations.ts - Operations state → Kafka broker: subscribes
README.md - Journey REST → Check-in service: dispatches
backend/src/main/java/com/vortex/api/rest/JourneyController.java - Journey REST → Retry workflow: dispatches
backend/src/main/java/com/vortex/api/rest/JourneyController.java - Check-in service → Bag lifecycle: creates bag
backend/src/main/java/com/vortex/checkin/application/CheckInService.java - Check-in service → PostgreSQL: persists
backend/src/main/java/com/vortex/checkin/application/CheckInService.java - Bag lifecycle → PostgreSQL: persists state
- Kafka workflow → Flight verification: dispatches
- Flight verification → Route planning: plans route
- Movement coordination → Route planning: reads route
backend/src/main/java/com/vortex/movement/application/MovementService.java - Movement coordination → Bag lifecycle: updates state
backend/src/main/java/com/vortex/movement/application/MovementService.java - Movement coordination → Transactional outbox: appends events
backend/src/main/java/com/vortex/movement/application/MovementService.java - Retry workflow → Bag lifecycle: transitions
backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java - Retry workflow → Transactional outbox: appends event
backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java - Transactional outbox → Kafka broker: relays
README.md - Event envelopes → Kafka broker: encoded for
- Kafka broker → Kafka adapter: delivers commands
README.md - Kafka adapter → Simulator service: delegates
simulator/src/vortex_simulator/kafka_adapter.py - Simulator service → Command journal: records commands
simulator/src/vortex_simulator/service.py - Kafka adapter → Kafka broker: publishes reports
README.md - Kafka broker → Simulator reports: delivers reports
README.md - Simulator reports → Movement coordination: dispatches reports
- Journey REST → PostgreSQL: queries