praveen-christuraj/hydrocarbon-accounting-otms

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