# hainhtat/lotayapos architecture

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

- Interactive diagram: https://gitdiagram.com/hainhtat/lotayapos
- Repository: https://github.com/hainhtat/lotayapos

## Overview

Lotaya is an internal Myanmar COD-delivery ERP and rider app. The principal workflow runs from shop pickup and batch/advance recording, through parcel intake and dispatch, to rider delivery outcomes, returns, settlements, cashbook close, and reporting. The backend API coordinates these domain services and persists shared operational and accounting state. The README documents the major capabilities and business stages; sampled source and the SOURCE INDEX support selected API-to-service relationships, but not every UI/API call or finance implementation detail.

Main entry points: [`backend/src/app.ts`](https://github.com/hainhtat/lotayapos/blob/main/backend/src/app.ts) (HTTP API), [`backend/src/services/ledger.service.ts`](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/ledger.service.ts) (Double-Entry Ledger), [`backend/src/services/parcel.service.ts`](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/parcel.service.ts) (Parcel Lifecycle), [`backend/src/controllers/operations.controller.ts`](https://github.com/hainhtat/lotayapos/blob/main/backend/src/controllers/operations.controller.ts) (Dispatch and Handover)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["ERP and Rider Apps"]
  node_web["ERP Workspaces"]
  node_mobile["Rider App<br/>[index.tsx]"]
end

subgraph group_api["API and Access"]
  node_api["HTTP API<br/>[app.ts]"]
  node_auth["Authentication and Roles<br/>[auth.ts]"]
  node_authsvc["Session Service<br/>[auth.service.ts]"]
  node_database[("Operational Database<br/>[database.ts]")]
end

subgraph group_delivery["Delivery Operations"]
  node_master["Master Data"]
  node_batches["Batches and Advances"]
  node_manifest["Manifest Import"]
  node_parcels["Parcel Lifecycle<br/>[parcel.service.ts]"]
  node_dispatch["Dispatch and Handover"]
  node_riderwork["Rider Outcomes<br/>[parcel.service.ts]"]
  node_returns["Shop Returns<br/>[os-returns.ts]"]
  node_pdf["Manifest Documents<br/>[manifest-pdf.ts]"]
end

subgraph group_finance["Finance and Reporting"]
  node_osaccounts["Shop Accounts"]
  node_ridersettle["Rider Settlements"]
  node_ossettle["Shop Settlements<br/>[os-settlements.ts]"]
  node_cashbook["Cashbook Close<br/>[cashbook-close.ts]"]
  node_ledger["Double-Entry Ledger<br/>[ledger.service.ts]"]
  node_reports["Reports<br/>[reports.service.ts]"]
end

node_staff(("Operations and Finance Staff"))
node_rider(("Rider"))

node_staff -->|"uses"| node_web
node_rider -->|"uses"| node_mobile
node_web -->|"accesses"| node_api
node_mobile -->|"accesses"| node_api
node_api -->|"guards routes"| node_auth
node_api -->|"configures"| node_database
node_auth -->|"checks user"| node_database
node_api -.->|"routes requests"| node_authsvc
node_api -->|"routes requests"| node_master
node_api -->|"routes operations"| node_batches
node_api -->|"routes operations"| node_parcels
node_api -->|"previews import"| node_manifest
node_api -->|"routes requests"| node_dispatch
node_dispatch -->|"calls"| node_batches
node_dispatch -->|"generates"| node_pdf
node_parcels -->|"records outcomes"| node_riderwork
node_riderwork -->|"queues failed parcels"| node_returns
node_batches -->|"finalizes accounting"| node_osaccounts
node_parcels -->|"posts corrections"| node_ledger
node_returns -.->|"credits returns"| node_osaccounts
node_ridersettle -.->|"posts settlements"| node_ledger
node_ossettle -.->|"posts settlements"| node_ledger
node_cashbook -.->|"closes accounting"| node_ledger
node_staff -->|"settles riders"| node_ridersettle
node_staff -->|"settles shops"| node_ossettle
node_staff -->|"closes day"| node_cashbook
node_staff -->|"reviews"| node_reports

click node_web "https://github.com/hainhtat/lotayapos/blob/main/frontend/src/pages/operations-page.tsx"
click node_mobile "https://github.com/hainhtat/lotayapos/blob/main/mobile/app/(tabs)/index.tsx"
click node_api "https://github.com/hainhtat/lotayapos/blob/main/backend/src/app.ts"
click node_auth "https://github.com/hainhtat/lotayapos/blob/main/backend/src/middleware/auth.ts"
click node_authsvc "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/auth.service.ts"
click node_database "https://github.com/hainhtat/lotayapos/blob/main/backend/src/config/database.ts"
click node_master "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/master-data.service.ts"
click node_batches "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/operations.service.ts"
click node_manifest "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/manifest-import.service.ts"
click node_parcels "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/parcel.service.ts"
click node_dispatch "https://github.com/hainhtat/lotayapos/blob/main/backend/src/controllers/operations.controller.ts"
click node_riderwork "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/parcel.service.ts"
click node_returns "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/os-returns.ts"
click node_osaccounts "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/os-account.service.ts"
click node_ridersettle "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/rider-settlements.ts"
click node_ossettle "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/os-settlements.ts"
click node_cashbook "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/cashbook-close.ts"
click node_ledger "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/ledger.service.ts"
click node_reports "https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/reports.service.ts"
click node_pdf "https://github.com/hainhtat/lotayapos/blob/main/backend/src/utils/manifest-pdf.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_web,node_mobile toneBlue
class node_api,node_auth,node_authsvc,node_database toneAmber
class node_master,node_batches,node_manifest,node_parcels,node_dispatch,node_riderwork,node_returns,node_pdf toneMint
class node_osaccounts,node_ridersettle,node_ossettle,node_cashbook,node_ledger,node_reports toneRose
class node_staff,node_rider toneIndigo
```

## Components

### ERP and Rider Apps

- [ERP Workspaces](https://github.com/hainhtat/lotayapos/blob/main/frontend/src/pages/operations-page.tsx): `frontend/src/pages/operations-page.tsx`
- [Rider App](https://github.com/hainhtat/lotayapos/blob/main/mobile/app/(tabs)/index.tsx): `mobile/app/(tabs)/index.tsx`

### API and Access

- [HTTP API](https://github.com/hainhtat/lotayapos/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Authentication and Roles](https://github.com/hainhtat/lotayapos/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [Session Service](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [Operational Database](https://github.com/hainhtat/lotayapos/blob/main/backend/src/config/database.ts): `backend/src/config/database.ts`

### Delivery Operations

- [Master Data](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/master-data.service.ts): `backend/src/services/master-data.service.ts`
- [Batches and Advances](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/operations.service.ts): `backend/src/services/operations.service.ts`
- [Manifest Import](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/manifest-import.service.ts): `backend/src/services/manifest-import.service.ts`
- [Parcel Lifecycle](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/parcel.service.ts): `backend/src/services/parcel.service.ts`
- [Dispatch and Handover](https://github.com/hainhtat/lotayapos/blob/main/backend/src/controllers/operations.controller.ts): `backend/src/controllers/operations.controller.ts`
- [Rider Outcomes](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/parcel.service.ts): `backend/src/services/parcel.service.ts`
- [Shop Returns](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/os-returns.ts): `backend/src/services/finance/os-returns.ts`
- [Manifest Documents](https://github.com/hainhtat/lotayapos/blob/main/backend/src/utils/manifest-pdf.ts): `backend/src/utils/manifest-pdf.ts`

### Finance and Reporting

- [Shop Accounts](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/os-account.service.ts): `backend/src/services/os-account.service.ts`
- [Rider Settlements](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/rider-settlements.ts): `backend/src/services/finance/rider-settlements.ts`
- [Shop Settlements](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/os-settlements.ts): `backend/src/services/finance/os-settlements.ts`
- [Cashbook Close](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/finance/cashbook-close.ts): `backend/src/services/finance/cashbook-close.ts`
- [Double-Entry Ledger](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/ledger.service.ts): `backend/src/services/ledger.service.ts`
- [Reports](https://github.com/hainhtat/lotayapos/blob/main/backend/src/services/reports.service.ts): `backend/src/services/reports.service.ts`

### Other components

- **Operations and Finance Staff**
- **Rider**

## Connections

- Operations and Finance Staff → ERP Workspaces: uses (evidence: `README.md`)
- Rider → Rider App: uses (evidence: `README.md`)
- ERP Workspaces → HTTP API: accesses (evidence: `README.md`)
- Rider App → HTTP API: accesses (evidence: `README.md`)
- HTTP API → Authentication and Roles: guards routes
- HTTP API → Operational Database: configures (evidence: `backend/src/app.ts`)
- Authentication and Roles → Operational Database: checks user (evidence: `backend/src/middleware/auth.ts`)
- HTTP API → Session Service: routes requests
- HTTP API → Master Data: routes requests
- HTTP API → Batches and Advances: routes operations
- HTTP API → Parcel Lifecycle: routes operations
- HTTP API → Manifest Import: previews import
- HTTP API → Dispatch and Handover: routes requests
- Dispatch and Handover → Batches and Advances: calls (evidence: `backend/src/controllers/operations.controller.ts`)
- Dispatch and Handover → Manifest Documents: generates (evidence: `backend/src/controllers/operations.controller.ts`)
- Parcel Lifecycle → Rider Outcomes: records outcomes (evidence: `README.md`)
- Rider Outcomes → Shop Returns: queues failed parcels (evidence: `README.md`)
- Batches and Advances → Shop Accounts: finalizes accounting (evidence: `backend/src/services/operations.service.ts`)
- Parcel Lifecycle → Double-Entry Ledger: posts corrections (evidence: `backend/src/services/parcel.service.ts`)
- Shop Returns → Shop Accounts: credits returns
- Rider Settlements → Double-Entry Ledger: posts settlements
- Shop Settlements → Double-Entry Ledger: posts settlements
- Cashbook Close → Double-Entry Ledger: closes accounting
- Operations and Finance Staff → Rider Settlements: settles riders (evidence: `README.md`)
- Operations and Finance Staff → Shop Settlements: settles shops (evidence: `README.md`)
- Operations and Finance Staff → Cashbook Close: closes day (evidence: `README.md`)
- Operations and Finance Staff → Reports: reviews (evidence: `README.md`)