# hamas-aboalmaali/sarh-orders-console architecture

> Architecture diagram of the GitHub repository hamas-aboalmaali/sarh-orders-console, 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/hamas-aboalmaali/sarh-orders-console
- Repository: https://github.com/hamas-aboalmaali/sarh-orders-console

## Overview

Orders Console lets agents authenticate, search and browse a large order history, register phone orders safely, and view deliberately slow order statistics; admins can also delete orders. The main path runs from the web console through authenticated API routes to PostgreSQL. The graph preserves the separate list, creation/idempotency, authentication, and overview stages. Some client hooks and API modules were not excerpted, so their links are included only where the README documents the behavior or a read file shows the reference.

Main entry points: [`apps/api/src/orders/orders.routes.ts`](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/orders.routes.ts) (Order endpoints), [`apps/web/src/App.tsx`](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/App.tsx) (Console shell), [`apps/api/src/auth/require-auth.ts`](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/auth/require-auth.ts) (Session and role guard), [`apps/api/src/db/schema.ts`](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/db/schema.ts) (PostgreSQL data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_app["Console shell<br/>[App.tsx]"]
  node_login["Sign-in page<br/>[LoginPage.tsx]"]
  node_websession["Session client<br/>[session.ts]"]
  node_orderspage["Orders workspace<br/>[OrdersPage.tsx]"]
  node_ordertable["Virtual order table<br/>[OrdersTable.tsx]"]
  node_createui["Order entry dialog"]
  node_createhook["Create mutation"]
  node_orderkeys["Order query keys<br/>[order-keys.ts]"]
  node_overview["Overview screen<br/>[OverviewPage.tsx]"]
  node_statshook["Stats query<br/>[use-order-stats.ts]"]
  node_apiclient["HTTP client<br/>[api-client.ts]"]
end

subgraph group_api["API services"]
  node_approutes["API composition<br/>[app.ts]"]
  node_authroutes["Auth endpoints<br/>[auth.routes.ts]"]
  node_authguard["Session and role guard<br/>[require-auth.ts]"]
  node_orderroutes["Order endpoints<br/>[orders.routes.ts]"]
  node_orderservice["Search and deletion<br/>[orders.service.ts]"]
  node_createorder["Idempotent creation<br/>[create-order.ts]"]
  node_orderstats["Order statistics<br/>[order-stats.ts]"]
end

subgraph group_data["Persistence and contracts"]
  node_database[("PostgreSQL data<br/>[schema.ts]")]
  node_contracts["Shared Zod contracts<br/>[orders.ts]"]
end

node_agent(("Agent / admin"))

node_agent -->|"uses"| node_app
node_app -->|"shows"| node_login
node_app -->|"checks session"| node_websession
node_app -->|"shows orders"| node_orderspage
node_app -->|"shows overview"| node_overview
node_login -->|"signs in"| node_websession
node_websession -->|"requests session"| node_apiclient
node_orderspage -->|"renders"| node_ordertable
node_orderspage -->|"opens"| node_createui
node_createui -->|"submits through"| node_createhook
node_createhook -->|"posts order"| node_apiclient
node_createhook -->|"invalidates cache"| node_orderkeys
node_overview -->|"loads stats"| node_statshook
node_statshook -->|"uses query key"| node_orderkeys
node_approutes -->|"mounts"| node_authroutes
node_approutes -->|"protects orders"| node_authguard
node_approutes -->|"mounts"| node_orderroutes
node_authroutes -->|"checks identity"| node_authguard
node_authguard -->|"loads user"| node_database
node_orderroutes -->|"checks role"| node_authguard
node_orderroutes -->|"validates requests"| node_contracts
node_orderroutes -->|"lists and deletes"| node_orderservice
node_orderroutes -->|"creates order"| node_createorder
node_orderroutes -->|"gets statistics"| node_orderstats
node_orderservice -->|"reads and deletes"| node_database
node_createorder -->|"claims and writes"| node_database
node_orderstats -->|"aggregates"| node_database
node_ordertable -->|"uses order types"| node_contracts
node_orderroutes -.->|"serves client requests"| node_apiclient

click node_app "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/App.tsx"
click node_login "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/auth/LoginPage.tsx"
click node_websession "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/auth/session.ts"
click node_orderspage "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/OrdersPage.tsx"
click node_ordertable "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/OrdersTable.tsx"
click node_createui "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/create/CreateOrderDialog.tsx"
click node_createhook "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/create/use-create-order.ts"
click node_orderkeys "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/order-keys.ts"
click node_overview "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/stats/OverviewPage.tsx"
click node_statshook "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/stats/use-order-stats.ts"
click node_apiclient "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/lib/api-client.ts"
click node_approutes "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/app.ts"
click node_authroutes "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/auth/auth.routes.ts"
click node_authguard "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/auth/require-auth.ts"
click node_orderroutes "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/orders.routes.ts"
click node_orderservice "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/orders.service.ts"
click node_createorder "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/create-order.ts"
click node_orderstats "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/order-stats.ts"
click node_database "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/db/schema.ts"
click node_contracts "https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/packages/shared/src/orders.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_app,node_login,node_websession,node_orderspage,node_ordertable,node_createui,node_createhook,node_orderkeys,node_overview,node_statshook,node_apiclient toneBlue
class node_approutes,node_authroutes,node_authguard,node_orderroutes,node_orderservice,node_createorder,node_orderstats toneAmber
class node_database,node_contracts toneMint
class node_agent toneIndigo
```

## Components

### Web console

- [Console shell](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Sign-in page](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/auth/LoginPage.tsx): `apps/web/src/features/auth/LoginPage.tsx`
- [Session client](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/auth/session.ts): `apps/web/src/features/auth/session.ts`
- [Orders workspace](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/OrdersPage.tsx): `apps/web/src/features/orders/OrdersPage.tsx`
- [Virtual order table](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/OrdersTable.tsx): `apps/web/src/features/orders/OrdersTable.tsx`
- [Order entry dialog](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/create/CreateOrderDialog.tsx): `apps/web/src/features/orders/create/CreateOrderDialog.tsx`
- [Create mutation](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/create/use-create-order.ts): `apps/web/src/features/orders/create/use-create-order.ts`
- [Order query keys](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/orders/order-keys.ts): `apps/web/src/features/orders/order-keys.ts`
- [Overview screen](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/stats/OverviewPage.tsx): `apps/web/src/features/stats/OverviewPage.tsx`
- [Stats query](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/features/stats/use-order-stats.ts): `apps/web/src/features/stats/use-order-stats.ts`
- [HTTP client](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/web/src/lib/api-client.ts): `apps/web/src/lib/api-client.ts`

### API services

- [API composition](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Auth endpoints](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/auth/auth.routes.ts): `apps/api/src/auth/auth.routes.ts`
- [Session and role guard](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/auth/require-auth.ts): `apps/api/src/auth/require-auth.ts`
- [Order endpoints](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/orders.routes.ts): `apps/api/src/orders/orders.routes.ts`
- [Search and deletion](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/orders.service.ts): `apps/api/src/orders/orders.service.ts`
- [Idempotent creation](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/create-order.ts): `apps/api/src/orders/create-order.ts`
- [Order statistics](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/orders/order-stats.ts): `apps/api/src/orders/order-stats.ts`

### Persistence and contracts

- [PostgreSQL data](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/apps/api/src/db/schema.ts): `apps/api/src/db/schema.ts`
- [Shared Zod contracts](https://github.com/hamas-aboalmaali/sarh-orders-console/blob/main/packages/shared/src/orders.ts): `packages/shared/src/orders.ts`

### Other components

- **Agent / admin**

## Connections

- Agent / admin → Console shell: uses (evidence: `README.md`)
- Console shell → Sign-in page: shows (evidence: `apps/web/src/App.tsx`)
- Console shell → Session client: checks session (evidence: `apps/web/src/App.tsx`)
- Console shell → Orders workspace: shows orders (evidence: `apps/web/src/App.tsx`)
- Console shell → Overview screen: shows overview (evidence: `apps/web/src/App.tsx`)
- Sign-in page → Session client: signs in (evidence: `apps/web/src/features/auth/LoginPage.tsx`)
- Session client → HTTP client: requests session (evidence: `apps/web/src/features/auth/session.ts`)
- Orders workspace → Virtual order table: renders (evidence: `apps/web/src/features/orders/OrdersPage.tsx`)
- Orders workspace → Order entry dialog: opens (evidence: `apps/web/src/features/orders/OrdersPage.tsx`)
- Order entry dialog → Create mutation: submits through (evidence: `apps/web/src/features/orders/create/CreateOrderDialog.tsx`)
- Create mutation → HTTP client: posts order (evidence: `apps/web/src/features/orders/create/use-create-order.ts`)
- Create mutation → Order query keys: invalidates cache (evidence: `apps/web/src/features/orders/create/use-create-order.ts`)
- Overview screen → Stats query: loads stats (evidence: `apps/web/src/features/stats/OverviewPage.tsx`)
- Stats query → Order query keys: uses query key (evidence: `apps/web/src/features/stats/use-order-stats.ts`)
- API composition → Auth endpoints: mounts (evidence: `apps/api/src/app.ts`)
- API composition → Session and role guard: protects orders (evidence: `apps/api/src/app.ts`)
- API composition → Order endpoints: mounts (evidence: `apps/api/src/app.ts`)
- Auth endpoints → Session and role guard: checks identity (evidence: `apps/api/src/auth/auth.routes.ts`)
- Session and role guard → PostgreSQL data: loads user (evidence: `apps/api/src/auth/require-auth.ts`)
- Order endpoints → Session and role guard: checks role (evidence: `apps/api/src/orders/orders.routes.ts`)
- Order endpoints → Shared Zod contracts: validates requests (evidence: `apps/api/src/orders/orders.routes.ts`)
- Order endpoints → Search and deletion: lists and deletes (evidence: `apps/api/src/orders/orders.routes.ts`)
- Order endpoints → Idempotent creation: creates order (evidence: `apps/api/src/orders/orders.routes.ts`)
- Order endpoints → Order statistics: gets statistics (evidence: `apps/api/src/orders/orders.routes.ts`)
- Search and deletion → PostgreSQL data: reads and deletes (evidence: `apps/api/src/orders/orders.service.ts`)
- Idempotent creation → PostgreSQL data: claims and writes (evidence: `apps/api/src/orders/create-order.ts`)
- Order statistics → PostgreSQL data: aggregates (evidence: `apps/api/src/orders/order-stats.ts`)
- Virtual order table → Shared Zod contracts: uses order types (evidence: `apps/web/src/features/orders/OrdersTable.tsx`)
- Order endpoints → HTTP client: serves client requests (evidence: `README.md`)
