# praveen-christuraj/hydrocarbon-accounting-otms architecture

> Architecture diagram of the GitHub repository praveen-christuraj/hydrocarbon-accounting-otms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/praveen-christuraj/hydrocarbon-accounting-otms
- Repository: https://github.com/praveen-christuraj/hydrocarbon-accounting-otms

## Overview

#### Purpose and entry points
Hydrocarbon Accounting is a terminal-operations accounting system covering asset setup, operational entries, vessel/truck/barge tracking, stock ledgers, material balance, reporting, workflow tasks, and auditability. It is a React/Vite frontend backed by a Python API service.
- Frontend bootstrap/routing: `frontend/src/main.jsx`, `frontend/src/App.jsx`
- Backend API composition: `backend/app/main.py`
- Local container composition: `docker-compose.yaml`

#### Client application and API boundary
The frontend is a page-oriented single-page application. Screen modules call domain-specific API adapters, which centralize HTTP/token behavior before reaching backend routers. Permission-aware rendering is enforced in the client but must be treated as a UX boundary, not the authorization authority.
- API client and token handling: `frontend/src/api/apiClient.js`, `frontend/src/api/authToken.js`
- Access-gated UI: `frontend/src/components/PermissionGuard.jsx`
- Representative workflow pages: `frontend/src/pages/OperationEntry.jsx`, `frontend/src/pages/MaterialBalanceReport.jsx`, `frontend/src/pages/OperationTaskManager.jsx`

#### Identity, RBAC, and scope enforcement
Authentication, JWT handling, permissions, roles, user assignments, and location scope form the primary security control plane. Backend dependencies are the request-time enforcement boundary; routers expose administration and assignment operations.
- Auth and permission dependencies: `backend/app/dependencies/auth.py`, `backend/app/dependencies/permissions.py`
- Security utilities: `backend/app/utils/jwt.py`, `backend/app/utils/totp.py`, `backend/app/utils/password_policy.py`
- RBAC administration endpoints: `backend/app/routers/users.py`, `backend/app/routers/roles.py`, `backend/app/routers/role_permissions.py`

#### Master data and operational configuration
Reference data establishes the accounting context before transactions are entered: locations and accounting-day settings, assets/types/assignments, calibration, operation templates/types, workflow policies, movement mappings, and Table 11 factors. These definitions constrain or feed downstream operational and reporting calculations.
- Shared persistence model/schema layer: `backend/app/models.py`, `backend/app/schemas.py`, `backend/app/database.py`
- Asset and calibration domain: `backend/app/routers/assets.py`, `backend/app/routers/asset_assignments.py`, `backend/app/routers/asset_calibration_tables.py`
- Operation/configuration domain: `backend/app/routers/operation_templates.py`, `backend/app/routers/workflow_policies.py`, `backend/app/routers/movement_mappings.py`

#### Transaction capture, workflow, and movement tracking
Operation entries produce transactions, potentially subject to policy-driven task workflow and correction handling. Specialized tracking supports tanker, barge, shuttle, and FSO movements; flowmeter records and vessel operations provide related operational inputs. The frontend contains reusable layouts for domain-specific entry forms.
- Core entry/transaction/task endpoints: `backend/app/routers/operation_entries.py`, `backend/app/routers/operation_transactions.py`, `backend/app/routers/operation_tasks.py`
- Tracking endpoints: `backend/app/routers/tanker_tracking.py`, `backend/app/routers/barge_trip_tracking.py`, `backend/app/routers/shuttle_fso_voyages.py`
- Form layouts: `frontend/src/components/operationLayouts/TankGaugingLayout.jsx`, `frontend/src/components/operationLayouts/StockMovementLayout.jsx`, `frontend/src/components/operationLayouts/VesselCycleLayout.jsx`

#### Accounting derivation, reporting, and exports
Recorded operations and movement data flow into tank/vessel stock ledgers, out-turn summaries, and material-balance reporting. Calculation logic is separated into backend services, while reporting endpoints and frontend report pages present/export results.
- Accounting/report endpoints: `backend/app/routers/tank_stock_ledger.py`, `backend/app/routers/material_balance_templates.py`, `backend/app/routers/reports.py`
- Calculation services: `backend/app/services/stock_ledger_helpers.py`, `backend/app/services/material_balance_helpers.py`, `backend/app/services/transaction_helpers.py`
- Export surface: `backend/app/routers/export_operations.py`, `frontend/src/pages/ExportOperations.jsx`

#### Governance, recovery, and runtime infrastructure
Audit logging, notifications, backup/restore, and an administrative database browser support operational governance. The backend is containerized Python with dependencies declared separately; the frontend is containerized Vite/React. Database configuration and migrations are application-owned.
- Governance/recovery routers: `backend/app/routers/audit_logs.py`, `backend/app/routers/backup_restore.py`, `backend/app/routers/system_notifications.py`
- Persistence lifecycle: `backend/app/config.py`, `backend/app/utils/db_migrations.py`
- Runtime artifacts: `backend/Dockerfile`, `frontend/Dockerfile`, `backend/requirements.txt`

Main entry points: [`backend/app/main.py`](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/main.py) (API Composition), [`backend/app/routers/operation_entries.py`](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_entries.py) (Operation Entries), [`backend/app/models.py`](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/models.py) (Persistence Model), [`frontend/src/App.jsx`](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/App.jsx) (React SPA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_spa["React SPA<br/>Vite client<br/>[App.jsx]"]
  node_ui_guard["Permission Guard<br/>UX access gate"]
  node_api_client["API Client<br/>HTTP/token adapter<br/>[apiClient.js]"]
  node_entry_forms["Operation Forms<br/>reusable layouts"]
  node_report_export_ui["Reports &amp; Export UI<br/>pages"]
end

subgraph group_api["Python API"]
  node_api_app["API Composition<br/>FastAPI application<br/>[main.py]"]
end

subgraph group_security["Security Control Plane"]
  node_authz{{"Request Auth &amp; Scope<br/>backend dependencies<br/>[permissions.py]"}}
  node_rbac_admin["RBAC Administration<br/>API routers<br/>[roles.py]"]
end

subgraph group_master["Master Data"]
  node_persistence[("Persistence Model<br/>models, schemas, database<br/>[models.py]")]
  node_asset_config["Assets &amp; Calibration<br/>configuration routers<br/>[assets.py]"]
  node_operation_config["Operation Policies<br/>templates and mappings"]
end

subgraph group_operations["Operations &amp; Workflow"]
  node_operation_entries["Operation Entries<br/>entry API"]
  node_transactions["Operation Transactions<br/>transaction API"]
  node_task_workflow["Task Workflow<br/>policy-driven tasks<br/>[operation_tasks.py]"]
  node_movement_tracking["Vessel &amp; Movement Tracking<br/>tracking APIs<br/>[tanker_tracking.py]"]
end

subgraph group_accounting["Accounting &amp; Governance"]
  node_calculation_services["Accounting Calculations<br/>backend services"]
  node_ledger_reports["Ledgers &amp; Reports<br/>reporting APIs<br/>[reports.py]"]
  node_exports["Operation Exports<br/>export API"]
  node_governance["Audit &amp; Recovery<br/>governance APIs<br/>[audit_logs.py]"]
end

node_runtime["Container Runtime<br/>Docker Compose"]

node_spa -->|"renders with"| node_ui_guard
node_spa -->|"uses"| node_entry_forms
node_spa -->|"hosts"| node_report_export_ui
node_entry_forms -->|"submits through"| node_api_client
node_report_export_ui -->|"queries through"| node_api_client
node_api_client -->|"HTTP requests"| node_api_app
node_api_app -->|"enforces request access"| node_authz
node_rbac_admin -->|"manages roles and assignments"| node_persistence
node_authz -->|"resolves users and scope"| node_persistence
node_api_app -->|"routes to"| node_operation_entries
node_api_app -->|"routes to"| node_movement_tracking
node_api_app -->|"routes to"| node_ledger_reports
node_api_app -->|"routes to"| node_exports
node_operation_config -->|"constrains"| node_operation_entries
node_asset_config -->|"provides asset context"| node_operation_entries
node_operation_entries -->|"produces"| node_transactions
node_operation_entries -.->|"may create tasks"| node_task_workflow
node_movement_tracking -->|"supplies movement inputs"| node_transactions
node_transactions -->|"stores"| node_persistence
node_task_workflow -->|"stores task state"| node_persistence
node_transactions -->|"feeds"| node_calculation_services
node_movement_tracking -->|"feeds"| node_calculation_services
node_asset_config -->|"provides calibration"| node_calculation_services
node_calculation_services -->|"derives results for"| node_ledger_reports
node_ledger_reports -->|"provides export data"| node_exports
node_api_app -->|"routes to"| node_governance
node_governance -->|"audits and recovers"| node_persistence
node_runtime -->|"runs frontend"| node_spa
node_runtime -->|"runs backend"| node_api_app

click node_spa "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/App.jsx"
click node_ui_guard "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/components/PermissionGuard.jsx"
click node_api_client "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/api/apiClient.js"
click node_entry_forms "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/components/operationLayouts/StockMovementLayout.jsx"
click node_report_export_ui "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/pages/MaterialBalanceReport.jsx"
click node_api_app "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/main.py"
click node_authz "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/dependencies/permissions.py"
click node_rbac_admin "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/roles.py"
click node_persistence "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/models.py"
click node_asset_config "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/assets.py"
click node_operation_config "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_templates.py"
click node_operation_entries "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_entries.py"
click node_transactions "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_transactions.py"
click node_task_workflow "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_tasks.py"
click node_movement_tracking "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/tanker_tracking.py"
click node_calculation_services "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/services/material_balance_helpers.py"
click node_ledger_reports "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/reports.py"
click node_exports "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/export_operations.py"
click node_governance "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/audit_logs.py"
click node_runtime "https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/docker-compose.yaml"

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_spa,node_ui_guard,node_api_client,node_entry_forms,node_report_export_ui toneBlue
class node_api_app toneAmber
class node_authz,node_rbac_admin toneMint
class node_persistence,node_asset_config,node_operation_config toneRose
class node_operation_entries,node_transactions,node_task_workflow,node_movement_tracking toneIndigo
class node_calculation_services,node_ledger_reports,node_exports,node_governance toneTeal
class node_runtime toneNeutral
```

## Components

### Frontend

- [React SPA](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/App.jsx): Vite client · Page-oriented terminal operations interface. · `frontend/src/App.jsx`
- [Permission Guard](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/components/PermissionGuard.jsx): UX access gate · Controls client-side visibility only. · `frontend/src/components/PermissionGuard.jsx`
- [API Client](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/api/apiClient.js): HTTP/token adapter · `frontend/src/api/apiClient.js`
- [Operation Forms](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/components/operationLayouts/StockMovementLayout.jsx): reusable layouts · `frontend/src/components/operationLayouts/StockMovementLayout.jsx`
- [Reports & Export UI](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/frontend/src/pages/MaterialBalanceReport.jsx): pages · `frontend/src/pages/MaterialBalanceReport.jsx`

### Python API

- [API Composition](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/main.py): FastAPI application · Composes routers and request handling. · `backend/app/main.py`

### Security Control Plane

- [Request Auth & Scope](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/dependencies/permissions.py): backend dependencies · JWT, permissions, assignments, and location scope are enforced here. · `backend/app/dependencies/permissions.py`
- [RBAC Administration](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/roles.py): API routers · `backend/app/routers/roles.py`

### Master Data

- [Persistence Model](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/models.py): models, schemas, database · Shared transactional persistence layer. · `backend/app/models.py`
- [Assets & Calibration](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/assets.py): configuration routers · `backend/app/routers/assets.py`
- [Operation Policies](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_templates.py): templates and mappings · Defines operation templates, workflow policies, and movement mappings. · `backend/app/routers/operation_templates.py`

### Operations & Workflow

- [Operation Entries](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_entries.py): entry API · Captures operational entries and corrections. · `backend/app/routers/operation_entries.py`
- [Operation Transactions](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_transactions.py): transaction API · `backend/app/routers/operation_transactions.py`
- [Task Workflow](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/operation_tasks.py): policy-driven tasks · `backend/app/routers/operation_tasks.py`
- [Vessel & Movement Tracking](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/tanker_tracking.py): tracking APIs · Tanker, barge, shuttle, and FSO movement inputs. · `backend/app/routers/tanker_tracking.py`

### Accounting & Governance

- [Accounting Calculations](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/services/material_balance_helpers.py): backend services · Derives transactions, stock ledger values, and material balance. · `backend/app/services/material_balance_helpers.py`
- [Ledgers & Reports](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/reports.py): reporting APIs · Provides stock ledger and material-balance results. · `backend/app/routers/reports.py`
- [Operation Exports](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/export_operations.py): export API · `backend/app/routers/export_operations.py`
- [Audit & Recovery](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/backend/app/routers/audit_logs.py): governance APIs · Audit logs, notifications, backup, and restore. · `backend/app/routers/audit_logs.py`

### Other components

- [Container Runtime](https://github.com/praveen-christuraj/hydrocarbon-accounting-otms/blob/main/docker-compose.yaml): Docker Compose · Runs frontend and backend containers locally. · `docker-compose.yaml`

## Connections

- React SPA → Permission Guard: renders with
- React SPA → Operation Forms: uses
- React SPA → Reports & Export UI: hosts
- Operation Forms → API Client: submits through
- Reports & Export UI → API Client: queries through
- API Client → API Composition: HTTP requests
- API Composition → Request Auth & Scope: enforces request access
- RBAC Administration → Persistence Model: manages roles and assignments
- Request Auth & Scope → Persistence Model: resolves users and scope
- API Composition → Operation Entries: routes to
- API Composition → Vessel & Movement Tracking: routes to
- API Composition → Ledgers & Reports: routes to
- API Composition → Operation Exports: routes to
- Operation Policies → Operation Entries: constrains
- Assets & Calibration → Operation Entries: provides asset context
- Operation Entries → Operation Transactions: produces
- Operation Entries → Task Workflow: may create tasks
- Vessel & Movement Tracking → Operation Transactions: supplies movement inputs
- Operation Transactions → Persistence Model: stores
- Task Workflow → Persistence Model: stores task state
- Operation Transactions → Accounting Calculations: feeds
- Vessel & Movement Tracking → Accounting Calculations: feeds
- Assets & Calibration → Accounting Calculations: provides calibration
- Accounting Calculations → Ledgers & Reports: derives results for
- Ledgers & Reports → Operation Exports: provides export data
- API Composition → Audit & Recovery: routes to
- Audit & Recovery → Persistence Model: audits and recovers
- Container Runtime → React SPA: runs frontend
- Container Runtime → API Composition: runs backend