# ali00209/dms_saas architecture

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

- Interactive diagram: https://gitdiagram.com/ali00209/dms_saas
- Repository: https://github.com/ali00209/dms_saas

## Overview

This repository is a multi-tenant inventory and order-management SaaS, with a React client and an Express API. The visible workflow is a user making API requests, passing account and organization checks, and reaching inventory and stock operations backed by PostgreSQL. Authentication and organization policy are integrated through Better Auth. The README also specifies order/delivery and driver cash-settlement capabilities, but no implementing modules for those appear in the supplied tree; those nodes are shown as documented, unverified scope. Edges are limited to relationships shown in excerpts or explicitly documented.

Main entry points: [`backend/src/modules/inventory/presentation/inventoryRoutes.ts`](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/presentation/inventoryRoutes.ts) (Inventory API), [`backend/src/infrastructure/auth/auth.ts`](https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/auth/auth.ts) (Authentication), [`backend/src/app.ts`](https://github.com/ali00209/dms_saas/blob/main/backend/src/app.ts) (Express application), [`backend/src/routes/index.ts`](https://github.com/ali00209/dms_saas/blob/main/backend/src/routes/index.ts) (Route registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["React client<br/>[App.tsx]"]
  node_http_client["HTTP client<br/>[axios.ts]"]
end

subgraph group_api["API and identity"]
  node_server["Server startup<br/>[server.ts]"]
  node_application["Express application<br/>[app.ts]"]
  node_route_registry["Route registry<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

subgraph group_tenancy["Accounts and tenancy"]
  node_accounts["Account use cases<br/>[accountUseCases.ts]"]
  node_account_guards["Account guards<br/>[accountGuards.ts]"]
  node_account_repository["Account repository"]
  node_organizations["Organization API"]
  node_org_status["Organization status"]
  node_api_key_policy["API key policy<br/>[apiKeyPolicy.ts]"]
  node_permissions["Permission model<br/>[permissions.ts]"]
end

subgraph group_inventory["Inventory operations"]
  node_inventory_routes["Inventory API<br/>[inventoryRoutes.ts]"]
  node_inventory_service["Inventory catalog"]
  node_locations["Stock locations<br/>[locationService.ts]"]
  node_stock_service["Stock ledger<br/>[stockService.ts]"]
  node_transfer_return_routes["Transfers and returns"]
  node_order_delivery["Orders and delivery"]
  node_driver_finance["Driver cash settlement"]
end

subgraph group_data["Persistence and infrastructure"]
  node_db_client["Database client<br/>[client.ts]"]
  node_database[("PostgreSQL")]
  node_schema["Database schema<br/>[auth.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -->|"makes requests"| node_http_client
node_http_client -->|"calls API"| node_application
node_server -->|"starts"| node_application
node_application -->|"mounts authentication"| node_auth
node_application -->|"mounts routes"| node_route_registry
node_route_registry -->|"registers"| node_organizations
node_route_registry -->|"registers"| node_inventory_routes
node_route_registry -->|"registers"| node_transfer_return_routes
node_route_registry -->|"registers admin routes"| node_accounts
node_account_guards -->|"resolves session"| node_auth
node_account_guards -->|"loads account"| node_account_repository
node_organizations -->|"checks permissions"| node_auth
node_organizations -->|"checks key policy"| node_api_key_policy
node_organizations -->|"checks tenant status"| node_org_status
node_auth -->|"configures access"| node_permissions
node_auth -->|"enforces tenant status"| node_org_status
node_auth -->|"checks key creation"| node_api_key_policy
node_inventory_routes -->|"guards requests"| node_account_guards
node_inventory_routes -->|"checks tenant status"| node_org_status
node_inventory_routes -->|"calls catalog"| node_inventory_service
node_inventory_routes -->|"reads movements"| node_stock_service
node_inventory_routes -->|"calls location operations"| node_locations
node_transfer_return_routes -->|"calls stock operations"| node_stock_service
node_transfer_return_routes -->|"calls location operations"| node_locations
node_stock_service -->|"validates locations"| node_locations
node_db_client -->|"connects"| node_database
node_db_client -->|"loads schema"| node_schema
node_order_delivery -.->|"documented API scope"| node_application
node_driver_finance -.->|"documented API scope"| node_application

click node_frontend "https://github.com/ali00209/dms_saas/blob/main/frontend/src/app/App.tsx"
click node_http_client "https://github.com/ali00209/dms_saas/blob/main/frontend/src/api/axios.ts"
click node_server "https://github.com/ali00209/dms_saas/blob/main/backend/src/server.ts"
click node_application "https://github.com/ali00209/dms_saas/blob/main/backend/src/app.ts"
click node_route_registry "https://github.com/ali00209/dms_saas/blob/main/backend/src/routes/index.ts"
click node_auth "https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/auth/auth.ts"
click node_accounts "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/accounts/application/accountUseCases.ts"
click node_account_guards "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/accounts/presentation/accountGuards.ts"
click node_account_repository "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/accounts/infrastructure/accountRepository.ts"
click node_organizations "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/organizations/presentation/organizationRoutes.ts"
click node_org_status "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/organizations/application/organizationStatus.ts"
click node_api_key_policy "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/organizations/application/apiKeyPolicy.ts"
click node_permissions "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/access/permissions.ts"
click node_inventory_routes "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/presentation/inventoryRoutes.ts"
click node_inventory_service "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/application/inventoryService.ts"
click node_locations "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/application/locationService.ts"
click node_stock_service "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/application/stockService.ts"
click node_transfer_return_routes "https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/presentation/stockTransferRoutes.ts"
click node_order_delivery "https://github.com/ali00209/dms_saas/tree/main/backend/src/modules"
click node_driver_finance "https://github.com/ali00209/dms_saas/tree/main/backend/src/modules"
click node_db_client "https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/database/client.ts"
click node_schema "https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/database/schema/auth.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_frontend,node_http_client,node_user toneBlue
class node_server,node_application,node_route_registry,node_auth toneAmber
class node_accounts,node_account_guards,node_account_repository,node_organizations,node_org_status,node_api_key_policy,node_permissions toneMint
class node_inventory_routes,node_inventory_service,node_locations,node_stock_service,node_transfer_return_routes,node_order_delivery,node_driver_finance toneRose
class node_db_client,node_database,node_schema toneIndigo
```

## Components

### Client

- [React client](https://github.com/ali00209/dms_saas/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [HTTP client](https://github.com/ali00209/dms_saas/blob/main/frontend/src/api/axios.ts): `frontend/src/api/axios.ts`

### API and identity

- [Server startup](https://github.com/ali00209/dms_saas/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Express application](https://github.com/ali00209/dms_saas/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Route registry](https://github.com/ali00209/dms_saas/blob/main/backend/src/routes/index.ts): `backend/src/routes/index.ts`
- [Authentication](https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/auth/auth.ts): `backend/src/infrastructure/auth/auth.ts`

### Accounts and tenancy

- [Account use cases](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/accounts/application/accountUseCases.ts): `backend/src/modules/accounts/application/accountUseCases.ts`
- [Account guards](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/accounts/presentation/accountGuards.ts): `backend/src/modules/accounts/presentation/accountGuards.ts`
- [Account repository](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/accounts/infrastructure/accountRepository.ts): `backend/src/modules/accounts/infrastructure/accountRepository.ts`
- [Organization API](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/organizations/presentation/organizationRoutes.ts): `backend/src/modules/organizations/presentation/organizationRoutes.ts`
- [Organization status](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/organizations/application/organizationStatus.ts): `backend/src/modules/organizations/application/organizationStatus.ts`
- [API key policy](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/organizations/application/apiKeyPolicy.ts): `backend/src/modules/organizations/application/apiKeyPolicy.ts`
- [Permission model](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/access/permissions.ts): `backend/src/modules/access/permissions.ts`

### Inventory operations

- [Inventory API](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/presentation/inventoryRoutes.ts): `backend/src/modules/inventory/presentation/inventoryRoutes.ts`
- [Inventory catalog](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/application/inventoryService.ts): `backend/src/modules/inventory/application/inventoryService.ts`
- [Stock locations](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/application/locationService.ts): `backend/src/modules/inventory/application/locationService.ts`
- [Stock ledger](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/application/stockService.ts): `backend/src/modules/inventory/application/stockService.ts`
- [Transfers and returns](https://github.com/ali00209/dms_saas/blob/main/backend/src/modules/inventory/presentation/stockTransferRoutes.ts): `backend/src/modules/inventory/presentation/stockTransferRoutes.ts`
- [Orders and delivery](https://github.com/ali00209/dms_saas/tree/main/backend/src/modules): `backend/src/modules`
- [Driver cash settlement](https://github.com/ali00209/dms_saas/tree/main/backend/src/modules): `backend/src/modules`

### Persistence and infrastructure

- [Database client](https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/database/client.ts): `backend/src/infrastructure/database/client.ts`
- **PostgreSQL**
- [Database schema](https://github.com/ali00209/dms_saas/blob/main/backend/src/infrastructure/database/schema/auth.ts): `backend/src/infrastructure/database/schema/auth.ts`

### Other components

- **User**

## Connections

- User → React client: uses (evidence: `README.md`)
- React client → HTTP client: makes requests (evidence: `frontend/src/app/App.tsx`)
- HTTP client → Express application: calls API (evidence: `README.md`)
- Server startup → Express application: starts (evidence: `backend/src/server.ts`)
- Express application → Authentication: mounts authentication (evidence: `backend/src/app.ts`)
- Express application → Route registry: mounts routes (evidence: `backend/src/app.ts`)
- Route registry → Organization API: registers (evidence: `backend/src/routes/index.ts`)
- Route registry → Inventory API: registers (evidence: `backend/src/routes/index.ts`)
- Route registry → Transfers and returns: registers (evidence: `backend/src/routes/index.ts`)
- Route registry → Account use cases: registers admin routes (evidence: `backend/src/routes/index.ts`)
- Account guards → Authentication: resolves session (evidence: `backend/src/modules/accounts/presentation/accountGuards.ts`)
- Account guards → Account repository: loads account (evidence: `backend/src/modules/accounts/presentation/accountGuards.ts`)
- Organization API → Authentication: checks permissions (evidence: `backend/src/modules/organizations/presentation/organizationRoutes.ts`)
- Organization API → API key policy: checks key policy (evidence: `backend/src/modules/organizations/presentation/organizationRoutes.ts`)
- Organization API → Organization status: checks tenant status (evidence: `backend/src/modules/organizations/presentation/organizationRoutes.ts`)
- Authentication → Permission model: configures access (evidence: `backend/src/infrastructure/auth/auth.ts`)
- Authentication → Organization status: enforces tenant status (evidence: `backend/src/infrastructure/auth/auth.ts`)
- Authentication → API key policy: checks key creation (evidence: `backend/src/infrastructure/auth/auth.ts`)
- Inventory API → Account guards: guards requests (evidence: `backend/src/modules/inventory/presentation/inventoryRoutes.ts`)
- Inventory API → Organization status: checks tenant status (evidence: `backend/src/modules/inventory/presentation/inventoryRoutes.ts`)
- Inventory API → Inventory catalog: calls catalog (evidence: `backend/src/modules/inventory/presentation/inventoryRoutes.ts`)
- Inventory API → Stock ledger: reads movements (evidence: `backend/src/modules/inventory/presentation/inventoryRoutes.ts`)
- Inventory API → Stock locations: calls location operations (evidence: `backend/src/modules/inventory/presentation/inventoryRoutes.ts`)
- Transfers and returns → Stock ledger: calls stock operations (evidence: `backend/src/modules/inventory/presentation/stockTransferRoutes.ts`)
- Transfers and returns → Stock locations: calls location operations (evidence: `backend/src/modules/inventory/presentation/stockTransferRoutes.ts`)
- Stock ledger → Stock locations: validates locations (evidence: `backend/src/modules/inventory/application/stockService.ts`)
- Database client → PostgreSQL: connects (evidence: `backend/src/infrastructure/database/client.ts`)
- Database client → Database schema: loads schema (evidence: `backend/src/infrastructure/database/client.ts`)
- Orders and delivery → Express application: documented API scope (evidence: `README.md`)
- Driver cash settlement → Express application: documented API scope (evidence: `README.md`)
