# bigm-o/chosen-energy architecture

> Architecture diagram of the GitHub repository bigm-o/chosen-energy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bigm-o/chosen-energy
- Repository: https://github.com/bigm-o/chosen-energy

## Overview

Chosen Energy Operations Portal manages diesel procurement and distribution, tanker fleet operations, sales, driver logs, and approvals. Users enter through the React portal; authentication establishes role-aware access, then operational pages support distinct purchasing, inventory, supply, fleet, and daily-log work. The .NET API exposes domain controllers and services backed by PostgreSQL; the sampled truck controller also performs direct Dapper queries. README capabilities are represented, but detailed wiring for unsampled pages and services is not asserted.

Main entry points: [`frontend/src/app/App.tsx`](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/App.tsx) (Portal Router), [`backend/ChosenEnergy.API/Controllers/TrucksController.cs`](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/TrucksController.cs) (Truck API), [`frontend/src/app/pages/DriverDailyLogPage.tsx`](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/DriverDailyLogPage.tsx) (Driver and Admin Logs), [`frontend/src/app/pages/PurchasingPage.tsx`](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/PurchasingPage.tsx) (Purchasing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Operations Portal"]
  node_frontend["Portal Router<br/>[App.tsx]"]
  node_login["Login Page<br/>[LoginPage.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_dailylogs["Driver and Admin Logs"]
  node_purchasingui["Purchasing<br/>[PurchasingPage.tsx]"]
  node_supplyui["Supply and Invoices<br/>[SupplyPage.tsx]"]
  node_fleetui["Fleet Management<br/>[TrucksPage.tsx]"]
  node_transloadui["Transloading"]
  node_approvalui["Approvals<br/>[ApprovalsPage.tsx]"]
end

subgraph group_identity["Identity and Access"]
  node_authstate["Auth State<br/>[useAuth.tsx]"]
  node_authclient["Auth API Client<br/>[authService.ts]"]
  node_authcontroller["Auth Controller<br/>[AuthController.cs]"]
  node_authservice["Auth Service<br/>[AuthService.cs]"]
  node_userrepo["User Repository<br/>[UserRepository.cs]"]
end

subgraph group_operations["Fleet and Inventory"]
  node_truck["Truck API"]
  node_fleetservices["Fleet and Log Services<br/>[Services]"]
end

subgraph group_commercial["Sales and Governance"]
  node_purchase["Purchasing API"]
  node_supply["Supply API"]
  node_commercialservices["Sales and Purchase Services<br/>[Services]"]
end

node_users(("Staff and Drivers"))
node_database[("PostgreSQL")]

node_users -->|"use portal"| node_frontend
node_frontend -->|"renders unauthenticated"| node_login
node_frontend -->|"routes authenticated"| node_dashboard
node_frontend -->|"routes drivers"| node_dailylogs
node_frontend -->|"routes purchasing"| node_purchasingui
node_frontend -->|"routes supply"| node_supplyui
node_frontend -->|"routes fleet"| node_fleetui
node_frontend -->|"routes transfers"| node_transloadui
node_frontend -->|"routes approvals"| node_approvalui
node_frontend -->|"provides auth"| node_authstate
node_authstate -->|"requests login"| node_authclient
node_authclient -->|"HTTP auth"| node_authcontroller
node_authcontroller -->|"delegates auth"| node_authservice
node_authservice -->|"looks up users"| node_userrepo
node_userrepo -->|"reads and writes"| node_database
node_purchasingui -->|"purchase operations"| node_purchase
node_purchase -->|"delegates purchase"| node_commercialservices
node_supplyui -->|"supply operations"| node_supply
node_supply -->|"delegates supply"| node_commercialservices
node_fleetui -->|"truck operations"| node_truck
node_truck -->|"queries and updates"| node_database
node_truck -->|"gets truck balance"| node_fleetservices
node_dailylogs -->|"driver logging"| node_users
node_transloadui -->|"fuel transfers"| node_users
node_approvalui -->|"reviews approvals"| node_users

click node_frontend "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/App.tsx"
click node_login "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/LoginPage.tsx"
click node_dashboard "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/DashboardPage.tsx"
click node_dailylogs "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/DriverDailyLogPage.tsx"
click node_purchasingui "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/PurchasingPage.tsx"
click node_supplyui "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/SupplyPage.tsx"
click node_fleetui "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/TrucksPage.tsx"
click node_transloadui "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/TransloadingPage.tsx"
click node_approvalui "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/ApprovalsPage.tsx"
click node_authstate "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/hooks/useAuth.tsx"
click node_authclient "https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/services/authService.ts"
click node_authcontroller "https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/AuthController.cs"
click node_authservice "https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Services/AuthService.cs"
click node_userrepo "https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Repositories/UserRepository.cs"
click node_purchase "https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/PurchasesController.cs"
click node_supply "https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/SuppliesController.cs"
click node_truck "https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/TrucksController.cs"
click node_fleetservices "https://github.com/bigm-o/chosen-energy/tree/main/backend/ChosenEnergy.API/Services"
click node_commercialservices "https://github.com/bigm-o/chosen-energy/tree/main/backend/ChosenEnergy.API/Services"

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_frontend,node_login,node_dashboard,node_dailylogs,node_purchasingui,node_supplyui,node_fleetui,node_transloadui,node_approvalui toneBlue
class node_authstate,node_authclient,node_authcontroller,node_authservice,node_userrepo,node_database toneAmber
class node_truck,node_fleetservices toneMint
class node_purchase,node_supply,node_commercialservices toneRose
class node_users toneIndigo
```

## Components

### Operations Portal

- [Portal Router](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Login Page](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/LoginPage.tsx): `frontend/src/app/pages/LoginPage.tsx`
- [Dashboard](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/DashboardPage.tsx): `frontend/src/app/pages/DashboardPage.tsx`
- [Driver and Admin Logs](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/DriverDailyLogPage.tsx): `frontend/src/app/pages/DriverDailyLogPage.tsx`
- [Purchasing](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/PurchasingPage.tsx): `frontend/src/app/pages/PurchasingPage.tsx`
- [Supply and Invoices](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/SupplyPage.tsx): `frontend/src/app/pages/SupplyPage.tsx`
- [Fleet Management](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/TrucksPage.tsx): `frontend/src/app/pages/TrucksPage.tsx`
- [Transloading](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/TransloadingPage.tsx): `frontend/src/app/pages/TransloadingPage.tsx`
- [Approvals](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/app/pages/ApprovalsPage.tsx): `frontend/src/app/pages/ApprovalsPage.tsx`

### Identity and Access

- [Auth State](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/hooks/useAuth.tsx): `frontend/src/hooks/useAuth.tsx`
- [Auth API Client](https://github.com/bigm-o/chosen-energy/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Auth Controller](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/AuthController.cs): `backend/ChosenEnergy.API/Controllers/AuthController.cs`
- [Auth Service](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Services/AuthService.cs): `backend/ChosenEnergy.API/Services/AuthService.cs`
- [User Repository](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Repositories/UserRepository.cs): `backend/ChosenEnergy.API/Repositories/UserRepository.cs`

### Fleet and Inventory

- [Truck API](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/TrucksController.cs): `backend/ChosenEnergy.API/Controllers/TrucksController.cs`
- [Fleet and Log Services](https://github.com/bigm-o/chosen-energy/tree/main/backend/ChosenEnergy.API/Services): `backend/ChosenEnergy.API/Services`

### Sales and Governance

- [Purchasing API](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/PurchasesController.cs): `backend/ChosenEnergy.API/Controllers/PurchasesController.cs`
- [Supply API](https://github.com/bigm-o/chosen-energy/blob/main/backend/ChosenEnergy.API/Controllers/SuppliesController.cs): `backend/ChosenEnergy.API/Controllers/SuppliesController.cs`
- [Sales and Purchase Services](https://github.com/bigm-o/chosen-energy/tree/main/backend/ChosenEnergy.API/Services): `backend/ChosenEnergy.API/Services`

### Other components

- **Staff and Drivers**
- **PostgreSQL**

## Connections

- Staff and Drivers → Portal Router: use portal
- Portal Router → Login Page: renders unauthenticated
- Portal Router → Dashboard: routes authenticated
- Portal Router → Driver and Admin Logs: routes drivers
- Portal Router → Purchasing: routes purchasing
- Portal Router → Supply and Invoices: routes supply
- Portal Router → Fleet Management: routes fleet
- Portal Router → Transloading: routes transfers
- Portal Router → Approvals: routes approvals
- Portal Router → Auth State: provides auth
- Auth State → Auth API Client: requests login
- Auth API Client → Auth Controller: HTTP auth
- Auth Controller → Auth Service: delegates auth
- Auth Service → User Repository: looks up users
- User Repository → PostgreSQL: reads and writes
- Purchasing → Purchasing API: purchase operations
- Purchasing API → Sales and Purchase Services: delegates purchase
- Supply and Invoices → Supply API: supply operations
- Supply API → Sales and Purchase Services: delegates supply
- Fleet Management → Truck API: truck operations
- Truck API → PostgreSQL: queries and updates
- Truck API → Fleet and Log Services: gets truck balance
- Driver and Admin Logs → Staff and Drivers: driver logging
- Transloading → Staff and Drivers: fuel transfers
- Approvals → Staff and Drivers: reviews approvals