# jaiscode/fuel-marking architecture

> Architecture diagram of the GitHub repository jaiscode/fuel-marking, 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/jaiscode/fuel-marking
- Repository: https://github.com/jaiscode/fuel-marking

## Overview

Fuel Marking System tracks rum containers and truck markings across offline-capable marking sites and head office. At a site, staff sign in, manage shifts and seals, then register, dose, dispense and verify trucks; warehouse, transfer, incident and stock-count work support custody tracking. The desktop syncs site records to the central backend, which provides web reporting and master-data administration and sends master data back to sites. The README documents these system-level flows; sampled source supports selected implementation details, but unsampled modules are represented at subsystem level.

Main entry points: [`src/main/java/org/jai/fuelmarking/ui`](https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/ui) (Desktop UI), [`backend/src/main/java/org/jai/fuelmarking/central/sync/SyncController.java`](https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/sync/SyncController.java) (Site sync API), [`web/src/app/app.routes.ts`](https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/app.routes.ts) (Angular web app), [`src/main/java/org/jai/fuelmarking/service/MarkingService.java`](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/MarkingService.java) (Truck marking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Marking-site desktop"]
  node_desktop["Desktop UI"]
  node_siteauth["PIN sign-in<br/>[AuthService.java]"]
  node_marking["Truck marking"]
  node_containers["Container custody"]
  node_operations["Site operations"]
  node_scale["Scale interface"]
  node_syncagent["Site sync agent<br/>[SyncAgent.java]"]
end

subgraph group_central["Central services"]
  node_backend["Central backend"]
  node_syncapi["Site sync API"]
  node_masteradmin["Master-data admin"]
  node_masteroutbox["Master-data outbox"]
  node_readapi["Reports and reads"]
end

subgraph group_web["Head-office web"]
  node_angular["Angular web app<br/>[app.routes.ts]"]
  node_webauth["OIDC sign-in<br/>[auth.service.ts]"]
  node_webapi["API client<br/>[api.service.ts]"]
end

subgraph group_shared["Persistence and messaging"]
  node_siteoutbox["Site sync outbox<br/>[Outbox.java]"]
  node_sitepg[("Site PostgreSQL<br/>[Tx.java]")]
  node_centralpg[("Central PostgreSQL<br/>[SyncService.java]")]
  node_kafka["Kafka topic"]
end

node_staff(("Site staff"))
node_webuser(("Head-office user"))
node_oidc{{"OIDC provider"}}

node_staff -->|"uses"| node_desktop
node_desktop -->|"signs in"| node_siteauth
node_desktop -->|"runs workflow"| node_marking
node_marking -.->|"tracks custody"| node_containers
node_desktop -->|"records activity"| node_operations
node_desktop -.->|"weighs"| node_scale
node_marking -.->|"persists"| node_sitepg
node_operations -.->|"persists"| node_sitepg
node_sitepg -.->|"queues changes"| node_siteoutbox
node_siteoutbox -.->|"feeds"| node_syncagent
node_syncagent -->|"pushes records"| node_syncapi
node_syncapi -.->|"stores and serves"| node_centralpg
node_syncapi -->|"returns transfers"| node_syncagent
node_syncapi -->|"receives master data"| node_kafka
node_masteradmin -.->|"queues updates"| node_masteroutbox
node_masteroutbox -->|"publishes"| node_kafka
node_webuser -->|"uses"| node_angular
node_angular -->|"authenticates"| node_webauth
node_webauth -.->|"signs in with"| node_oidc
node_angular -.->|"requests data"| node_webapi
node_webapi -.->|"calls"| node_readapi
node_readapi -.->|"reads"| node_centralpg
node_angular -->|"maintains master data"| node_masteradmin

click node_desktop "https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/ui"
click node_siteauth "https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/AuthService.java"
click node_marking "https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/MarkingService.java"
click node_containers "https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/ContainerService.java"
click node_operations "https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/service"
click node_scale "https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/hardware"
click node_siteoutbox "https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/dao/Outbox.java"
click node_sitepg "https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/config/Tx.java"
click node_syncagent "https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/sync/SyncAgent.java"
click node_backend "https://github.com/jaiscode/fuel-marking/tree/main/backend/src/main/java/org/jai/fuelmarking/central"
click node_syncapi "https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/sync/SyncController.java"
click node_masteradmin "https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/master/AdminController.java"
click node_masteroutbox "https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/master/MasterDataOutbox.java"
click node_centralpg "https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/sync/SyncService.java"
click node_angular "https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/app.routes.ts"
click node_webauth "https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/core/auth.service.ts"
click node_webapi "https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/core/api.service.ts"
click node_readapi "https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/web/ReadController.java"

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_desktop,node_siteauth,node_marking,node_containers,node_operations,node_scale,node_syncagent,node_webuser toneBlue
class node_backend,node_syncapi,node_masteradmin,node_masteroutbox,node_readapi toneAmber
class node_angular,node_webauth,node_webapi toneMint
class node_siteoutbox,node_sitepg,node_centralpg,node_kafka toneRose
class node_staff,node_oidc toneIndigo
```

## Components

### Marking-site desktop

- [Desktop UI](https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/ui): `src/main/java/org/jai/fuelmarking/ui`
- [PIN sign-in](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/AuthService.java): `src/main/java/org/jai/fuelmarking/service/AuthService.java`
- [Truck marking](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/MarkingService.java): `src/main/java/org/jai/fuelmarking/service/MarkingService.java`
- [Container custody](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/service/ContainerService.java): `src/main/java/org/jai/fuelmarking/service/ContainerService.java`
- [Site operations](https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/service): `src/main/java/org/jai/fuelmarking/service`
- [Scale interface](https://github.com/jaiscode/fuel-marking/tree/main/src/main/java/org/jai/fuelmarking/hardware): `src/main/java/org/jai/fuelmarking/hardware`
- [Site sync agent](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/sync/SyncAgent.java): `src/main/java/org/jai/fuelmarking/sync/SyncAgent.java`

### Central services

- [Central backend](https://github.com/jaiscode/fuel-marking/tree/main/backend/src/main/java/org/jai/fuelmarking/central): `backend/src/main/java/org/jai/fuelmarking/central`
- [Site sync API](https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/sync/SyncController.java): `backend/src/main/java/org/jai/fuelmarking/central/sync/SyncController.java`
- [Master-data admin](https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/master/AdminController.java): `backend/src/main/java/org/jai/fuelmarking/central/master/AdminController.java`
- [Master-data outbox](https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/master/MasterDataOutbox.java): `backend/src/main/java/org/jai/fuelmarking/central/master/MasterDataOutbox.java`
- [Reports and reads](https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/web/ReadController.java): `backend/src/main/java/org/jai/fuelmarking/central/web/ReadController.java`

### Head-office web

- [Angular web app](https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/app.routes.ts): `web/src/app/app.routes.ts`
- [OIDC sign-in](https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/core/auth.service.ts): `web/src/app/core/auth.service.ts`
- [API client](https://github.com/jaiscode/fuel-marking/blob/main/web/src/app/core/api.service.ts): `web/src/app/core/api.service.ts`

### Persistence and messaging

- [Site sync outbox](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/dao/Outbox.java): `src/main/java/org/jai/fuelmarking/dao/Outbox.java`
- [Site PostgreSQL](https://github.com/jaiscode/fuel-marking/blob/main/src/main/java/org/jai/fuelmarking/config/Tx.java): `src/main/java/org/jai/fuelmarking/config/Tx.java`
- [Central PostgreSQL](https://github.com/jaiscode/fuel-marking/blob/main/backend/src/main/java/org/jai/fuelmarking/central/sync/SyncService.java): `backend/src/main/java/org/jai/fuelmarking/central/sync/SyncService.java`
- **Kafka topic**

### Other components

- **Site staff**
- **Head-office user**
- **OIDC provider**

## Connections

- Site staff → Desktop UI: uses (evidence: `README.md`)
- Desktop UI → PIN sign-in: signs in (evidence: `README.md`)
- Desktop UI → Truck marking: runs workflow (evidence: `README.md`)
- Truck marking → Container custody: tracks custody
- Desktop UI → Site operations: records activity (evidence: `README.md`)
- Desktop UI → Scale interface: weighs
- Truck marking → Site PostgreSQL: persists (evidence: `src/main/java/org/jai/fuelmarking/service/MarkingService.java`)
- Site operations → Site PostgreSQL: persists (evidence: `src/main/java/org/jai/fuelmarking/service/AuthService.java`)
- Site PostgreSQL → Site sync outbox: queues changes
- Site sync outbox → Site sync agent: feeds
- Site sync agent → Site sync API: pushes records (evidence: `README.md`)
- Site sync API → Central PostgreSQL: stores and serves (evidence: `backend/src/main/java/org/jai/fuelmarking/central/sync/SyncController.java`)
- Site sync API → Site sync agent: returns transfers (evidence: `README.md`)
- Site sync API → Kafka topic: receives master data (evidence: `README.md`)
- Master-data admin → Master-data outbox: queues updates (evidence: `backend/src/main/java/org/jai/fuelmarking/central/master/AdminController.java`)
- Master-data outbox → Kafka topic: publishes (evidence: `README.md`)
- Head-office user → Angular web app: uses (evidence: `README.md`)
- Angular web app → OIDC sign-in: authenticates (evidence: `web/src/app/app.routes.ts`)
- OIDC sign-in → OIDC provider: signs in with
- Angular web app → API client: requests data
- API client → Reports and reads: calls
- Reports and reads → Central PostgreSQL: reads
- Angular web app → Master-data admin: maintains master data (evidence: `README.md`)
