# samir-saudagar/vortex architecture

> Architecture diagram of the GitHub repository samir-saudagar/vortex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samir-saudagar/vortex
- Repository: https://github.com/samir-saudagar/vortex

## Overview

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: [`backend/src/main/java/com/vortex/api/rest/JourneyController.java`](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/api/rest/JourneyController.java) (Journey REST), [`backend/src/main/java/com/vortex/movement/application/MovementService.java`](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/movement/application/MovementService.java) (Movement coordination), [`frontend/src/app/App.tsx`](https://github.com/samir-saudagar/vortex/blob/main/frontend/src/app/App.tsx) (Dashboard), [`backend/src/main/java/com/vortex/bagstate/application/PersistentBagLifecycle.java`](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/bagstate/application/PersistentBagLifecycle.java) (Bag lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operations dashboard"]
  node_app["Dashboard<br/>[App.tsx]"]
  node_operations["Operations state<br/>[useOperations.ts]"]
  node_contracts["UI contracts<br/>[contracts.ts]"]
end

subgraph group_api["Backend entry points"]
  node_rest["Journey REST"]
end

subgraph group_workflow["Baggage workflows"]
  node_checkin["Check-in service"]
  node_bag["Bag lifecycle"]
  node_flight["Flight verification"]
  node_routing["Route planning"]
  node_movement["Movement coordination"]
  node_retry["Retry workflow"]
end

subgraph group_messaging["Event transport"]
  node_outbox["Transactional outbox<br/>[OutboxWriter.java]"]
  node_kafka["Kafka workflow"]
  node_simlistener["Simulator reports"]
  node_events["Event envelopes<br/>[EventEnvelope.java]"]
end

subgraph group_simulator["Equipment simulation"]
  node_simadapter["Kafka adapter<br/>[kafka_adapter.py]"]
  node_simservice["Simulator service<br/>[service.py]"]
  node_journal[("Command journal<br/>[command_journal.py]")]
end

node_operator(("Operator"))
node_postgres[("PostgreSQL")]
node_broker["Kafka broker"]
node_browser(("Browser client"))

node_operator -->|"uses"| node_app
node_app -->|"reads"| node_operations
node_app -.->|"requests"| node_rest
node_browser -->|"renders"| node_app
node_operations -->|"uses types"| node_contracts
node_operations -->|"subscribes"| node_broker
node_rest -->|"dispatches"| node_checkin
node_rest -->|"dispatches"| node_retry
node_checkin -->|"creates bag"| node_bag
node_checkin -->|"persists"| node_postgres
node_bag -.->|"persists state"| node_postgres
node_kafka -.->|"dispatches"| node_flight
node_flight -.->|"plans route"| node_routing
node_movement -->|"reads route"| node_routing
node_movement -->|"updates state"| node_bag
node_movement -->|"appends events"| node_outbox
node_retry -->|"transitions"| node_bag
node_retry -->|"appends event"| node_outbox
node_outbox -->|"relays"| node_broker
node_events -.->|"encoded for"| node_broker
node_broker -->|"delivers commands"| node_simadapter
node_simadapter -->|"delegates"| node_simservice
node_simservice -->|"records commands"| node_journal
node_simadapter -->|"publishes reports"| node_broker
node_broker -->|"delivers reports"| node_simlistener
node_simlistener -.->|"dispatches reports"| node_movement
node_rest -.->|"queries"| node_postgres

click node_app "https://github.com/samir-saudagar/vortex/blob/main/frontend/src/app/App.tsx"
click node_operations "https://github.com/samir-saudagar/vortex/blob/main/frontend/src/app/useOperations.ts"
click node_rest "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/api/rest/JourneyController.java"
click node_checkin "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/checkin/application/CheckInService.java"
click node_bag "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/bagstate/application/PersistentBagLifecycle.java"
click node_flight "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/flight/application/PersistentFlightVerification.java"
click node_routing "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/routing/application/PersistentRoutePlanning.java"
click node_movement "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/movement/application/MovementService.java"
click node_retry "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java"
click node_outbox "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/outbox/OutboxWriter.java"
click node_kafka "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/kafka/WorkflowKafkaListener.java"
click node_simlistener "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/kafka/SimulatorReportKafkaListener.java"
click node_events "https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/envelope/EventEnvelope.java"
click node_simadapter "https://github.com/samir-saudagar/vortex/blob/main/simulator/src/vortex_simulator/kafka_adapter.py"
click node_simservice "https://github.com/samir-saudagar/vortex/blob/main/simulator/src/vortex_simulator/service.py"
click node_journal "https://github.com/samir-saudagar/vortex/blob/main/simulator/src/vortex_simulator/command_journal.py"
click node_contracts "https://github.com/samir-saudagar/vortex/blob/main/frontend/src/types/contracts.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_operations,node_contracts,node_browser toneBlue
class node_rest,node_postgres toneAmber
class node_checkin,node_bag,node_flight,node_routing,node_movement,node_retry toneMint
class node_outbox,node_kafka,node_simlistener,node_events toneRose
class node_simadapter,node_simservice,node_journal,node_operator,node_broker toneIndigo
```

## Components

### Operations dashboard

- [Dashboard](https://github.com/samir-saudagar/vortex/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Operations state](https://github.com/samir-saudagar/vortex/blob/main/frontend/src/app/useOperations.ts): `frontend/src/app/useOperations.ts`
- [UI contracts](https://github.com/samir-saudagar/vortex/blob/main/frontend/src/types/contracts.ts): `frontend/src/types/contracts.ts`

### Backend entry points

- [Journey REST](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/api/rest/JourneyController.java): `backend/src/main/java/com/vortex/api/rest/JourneyController.java`

### Baggage workflows

- [Check-in service](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/checkin/application/CheckInService.java): `backend/src/main/java/com/vortex/checkin/application/CheckInService.java`
- [Bag lifecycle](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/bagstate/application/PersistentBagLifecycle.java): `backend/src/main/java/com/vortex/bagstate/application/PersistentBagLifecycle.java`
- [Flight verification](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/flight/application/PersistentFlightVerification.java): `backend/src/main/java/com/vortex/flight/application/PersistentFlightVerification.java`
- [Route planning](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/routing/application/PersistentRoutePlanning.java): `backend/src/main/java/com/vortex/routing/application/PersistentRoutePlanning.java`
- [Movement coordination](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/movement/application/MovementService.java): `backend/src/main/java/com/vortex/movement/application/MovementService.java`
- [Retry workflow](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java): `backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java`

### Event transport

- [Transactional outbox](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/outbox/OutboxWriter.java): `backend/src/main/java/com/vortex/messaging/outbox/OutboxWriter.java`
- [Kafka workflow](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/kafka/WorkflowKafkaListener.java): `backend/src/main/java/com/vortex/messaging/kafka/WorkflowKafkaListener.java`
- [Simulator reports](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/kafka/SimulatorReportKafkaListener.java): `backend/src/main/java/com/vortex/messaging/kafka/SimulatorReportKafkaListener.java`
- [Event envelopes](https://github.com/samir-saudagar/vortex/blob/main/backend/src/main/java/com/vortex/messaging/envelope/EventEnvelope.java): `backend/src/main/java/com/vortex/messaging/envelope/EventEnvelope.java`

### Equipment simulation

- [Kafka adapter](https://github.com/samir-saudagar/vortex/blob/main/simulator/src/vortex_simulator/kafka_adapter.py): `simulator/src/vortex_simulator/kafka_adapter.py`
- [Simulator service](https://github.com/samir-saudagar/vortex/blob/main/simulator/src/vortex_simulator/service.py): `simulator/src/vortex_simulator/service.py`
- [Command journal](https://github.com/samir-saudagar/vortex/blob/main/simulator/src/vortex_simulator/command_journal.py): `simulator/src/vortex_simulator/command_journal.py`

### Other components

- **Operator**
- **PostgreSQL**
- **Kafka broker**
- **Browser client**

## Connections

- Operator → Dashboard: uses (evidence: `README.md`)
- Dashboard → Operations state: reads (evidence: `frontend/src/app/App.tsx`)
- Dashboard → Journey REST: requests
- Browser client → Dashboard: renders
- Operations state → UI contracts: uses types (evidence: `frontend/src/app/useOperations.ts`)
- Operations state → Kafka broker: subscribes (evidence: `README.md`)
- Journey REST → Check-in service: dispatches (evidence: `backend/src/main/java/com/vortex/api/rest/JourneyController.java`)
- Journey REST → Retry workflow: dispatches (evidence: `backend/src/main/java/com/vortex/api/rest/JourneyController.java`)
- Check-in service → Bag lifecycle: creates bag (evidence: `backend/src/main/java/com/vortex/checkin/application/CheckInService.java`)
- Check-in service → PostgreSQL: persists (evidence: `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 (evidence: `backend/src/main/java/com/vortex/movement/application/MovementService.java`)
- Movement coordination → Bag lifecycle: updates state (evidence: `backend/src/main/java/com/vortex/movement/application/MovementService.java`)
- Movement coordination → Transactional outbox: appends events (evidence: `backend/src/main/java/com/vortex/movement/application/MovementService.java`)
- Retry workflow → Bag lifecycle: transitions (evidence: `backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java`)
- Retry workflow → Transactional outbox: appends event (evidence: `backend/src/main/java/com/vortex/messaging/workflow/RetryBagService.java`)
- Transactional outbox → Kafka broker: relays (evidence: `README.md`)
- Event envelopes → Kafka broker: encoded for
- Kafka broker → Kafka adapter: delivers commands (evidence: `README.md`)
- Kafka adapter → Simulator service: delegates (evidence: `simulator/src/vortex_simulator/kafka_adapter.py`)
- Simulator service → Command journal: records commands (evidence: `simulator/src/vortex_simulator/service.py`)
- Kafka adapter → Kafka broker: publishes reports (evidence: `README.md`)
- Kafka broker → Simulator reports: delivers reports (evidence: `README.md`)
- Simulator reports → Movement coordination: dispatches reports
- Journey REST → PostgreSQL: queries
