# wahidakhtar/arcad architecture

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

- Interactive diagram: https://gitdiagram.com/wahidakhtar/arcad
- Repository: https://github.com/wahidakhtar/arcad

## Overview

ARCAD is a web application for managing project and site operations, people, billing, transactions, tickets, and administration. Users enter through the authenticated frontend; the application routes them to feature pages, which request API data and receive live update events. The backend mounts API routes that implement domain operations using services and persistent models. The supplied material has no README, and many domain files were not excerpted, so some feature-to-API relationships are shown only as unverified links rather than asserted call chains.

Main entry points: [`backend/app/main.py`](https://github.com/wahidakhtar/arcad/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/App.tsx) (Page router), [`backend/app/core/database.py`](https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/database.py) (Relational database), [`frontend/src/hooks/useWebSocket.ts`](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/hooks/useWebSocket.ts) (Live updates client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["Page router<br/>[App.tsx]"]
  node_authctx["Auth context<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_ws_client["Live updates client<br/>[useWebSocket.ts]"]
  node_transactions_ui["Transactions UI"]
  node_site_ui["Site detail UI<br/>[useSiteDetail.ts]"]
  node_billing_ui["PO detail UI<br/>[usePoDetail.ts]"]
end

subgraph group_api["API and access"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_authz["Session authorization<br/>[auth.py]"]
  node_auth_service["Auth service<br/>[auth.py]"]
end

subgraph group_operations["Operations domains"]
  node_ops_routes["Operations routes<br/>[sites.py]"]
  node_ops_services["Operations services<br/>[sites.py]"]
  node_projects_routes["Project routes<br/>[projects.py]"]
  node_tickets_routes["Ticket routes<br/>[tickets.py]"]
  node_transaction_routes["Transaction routes<br/>[transactions.py]"]
  node_dashboard_service["Dashboard service<br/>[dashboard.py]"]
end

subgraph group_billing["Billing and finance"]
  node_billing_routes["Billing routes<br/>[billing.py]"]
  node_billing_service["Billing service<br/>[billing.py]"]
  node_accounting_rules["Accounting rules<br/>[acc_rules.py]"]
end

subgraph group_runtime["Runtime services"]
  node_database[("Relational database<br/>[database.py]")]
  node_cache["Session cache<br/>[cache.py]"]
  node_ws_manager["WebSocket manager<br/>[ws_manager.py]"]
  node_auth_models["Auth records<br/>[auth.py]"]
  node_core_models["Core records<br/>[core.py]"]
  node_hr_models["People records<br/>[hr.py]"]
end

node_user(("Staff user"))
node_redis[("Redis")]

node_user -->|"uses"| node_app
node_app -->|"checks session"| node_authctx
node_app -->|"opens live connection"| node_ws_client
node_app -->|"routes to"| node_transactions_ui
node_app -->|"routes to"| node_site_ui
node_app -->|"routes to"| node_billing_ui
node_authctx -->|"requests session"| node_api_client
node_transactions_ui -->|"fetches records"| node_api_client
node_transactions_ui -->|"subscribes events"| node_ws_client
node_site_ui -->|"loads site data"| node_api_client
node_site_ui -->|"subscribes events"| node_ws_client
node_billing_ui -->|"subscribes events"| node_ws_client
node_api_client -.->|"HTTP requests"| node_backend
node_ws_client -.->|"receives broadcasts"| node_ws_manager
node_backend -->|"mounts routes"| node_auth_routes
node_backend -->|"mounts routes"| node_billing_routes
node_backend -->|"mounts routes"| node_ops_routes
node_backend -->|"mounts routes"| node_projects_routes
node_backend -->|"mounts routes"| node_tickets_routes
node_backend -->|"mounts routes"| node_transaction_routes
node_backend -->|"loads dashboard"| node_dashboard_service
node_auth_routes -->|"uses service"| node_auth_service
node_auth_routes -->|"uses authorization"| node_authz
node_authz -->|"reads session cache"| node_cache
node_authz -->|"loads user context"| node_database
node_auth_service -->|"invalidates sessions"| node_cache
node_auth_service -->|"persists tokens"| node_auth_models
node_auth_service -->|"reads users"| node_hr_models
node_cache -->|"uses store"| node_redis
node_database -->|"configured at startup"| node_backend
node_billing_routes -->|"calls service"| node_billing_service
node_billing_routes -->|"applies rules"| node_accounting_rules
node_billing_routes -->|"broadcasts updates"| node_ws_manager
node_billing_service -.->|"uses persistence"| node_database
node_ops_routes -.->|"uses service"| node_ops_services
node_accounting_rules -.->|"uses persistence"| node_database
node_database -->|"model base"| node_core_models
node_database -->|"model base"| node_auth_models

click node_app "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/App.tsx"
click node_authctx "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/context/AuthContext.tsx"
click node_api_client "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/lib/api.ts"
click node_ws_client "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/hooks/useWebSocket.ts"
click node_transactions_ui "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/features/transactions/hooks/useTransactionsPage.ts"
click node_site_ui "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/features/sites/siteDetail/hooks/useSiteDetail.ts"
click node_billing_ui "https://github.com/wahidakhtar/arcad/blob/main/frontend/src/features/billing/po/hooks/usePoDetail.ts"
click node_backend "https://github.com/wahidakhtar/arcad/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/auth.py"
click node_authz "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/auth.py"
click node_auth_service "https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/auth.py"
click node_ops_routes "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/sites.py"
click node_ops_services "https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/sites.py"
click node_projects_routes "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/projects.py"
click node_tickets_routes "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/tickets.py"
click node_transaction_routes "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/transactions.py"
click node_billing_routes "https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/billing.py"
click node_billing_service "https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/billing.py"
click node_accounting_rules "https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/acc_rules.py"
click node_dashboard_service "https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/dashboard.py"
click node_database "https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/database.py"
click node_cache "https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/cache.py"
click node_ws_manager "https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/ws_manager.py"
click node_auth_models "https://github.com/wahidakhtar/arcad/blob/main/backend/app/models/auth.py"
click node_core_models "https://github.com/wahidakhtar/arcad/blob/main/backend/app/models/core.py"
click node_hr_models "https://github.com/wahidakhtar/arcad/blob/main/backend/app/models/hr.py"

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_authctx,node_api_client,node_ws_client,node_transactions_ui,node_site_ui,node_billing_ui,node_user toneBlue
class node_backend,node_auth_routes,node_authz,node_auth_service,node_redis toneAmber
class node_ops_routes,node_ops_services,node_projects_routes,node_tickets_routes,node_transaction_routes,node_dashboard_service toneMint
class node_billing_routes,node_billing_service,node_accounting_rules toneRose
class node_database,node_cache,node_ws_manager,node_auth_models,node_core_models,node_hr_models toneIndigo
```

## Components

### Web application

- [Page router](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Live updates client](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`
- [Transactions UI](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/features/transactions/hooks/useTransactionsPage.ts): `frontend/src/features/transactions/hooks/useTransactionsPage.ts`
- [Site detail UI](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/features/sites/siteDetail/hooks/useSiteDetail.ts): `frontend/src/features/sites/siteDetail/hooks/useSiteDetail.ts`
- [PO detail UI](https://github.com/wahidakhtar/arcad/blob/main/frontend/src/features/billing/po/hooks/usePoDetail.ts): `frontend/src/features/billing/po/hooks/usePoDetail.ts`

### API and access

- [FastAPI application](https://github.com/wahidakhtar/arcad/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Session authorization](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Auth service](https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`

### Operations domains

- [Operations routes](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/sites.py): `backend/app/api/routes/sites.py`
- [Operations services](https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/sites.py): `backend/app/services/sites.py`
- [Project routes](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/projects.py): `backend/app/api/routes/projects.py`
- [Ticket routes](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/tickets.py): `backend/app/api/routes/tickets.py`
- [Transaction routes](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/transactions.py): `backend/app/api/routes/transactions.py`
- [Dashboard service](https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/dashboard.py): `backend/app/services/dashboard.py`

### Billing and finance

- [Billing routes](https://github.com/wahidakhtar/arcad/blob/main/backend/app/api/routes/billing.py): `backend/app/api/routes/billing.py`
- [Billing service](https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/billing.py): `backend/app/services/billing.py`
- [Accounting rules](https://github.com/wahidakhtar/arcad/blob/main/backend/app/services/acc_rules.py): `backend/app/services/acc_rules.py`

### Runtime services

- [Relational database](https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Session cache](https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/cache.py): `backend/app/core/cache.py`
- [WebSocket manager](https://github.com/wahidakhtar/arcad/blob/main/backend/app/core/ws_manager.py): `backend/app/core/ws_manager.py`
- [Auth records](https://github.com/wahidakhtar/arcad/blob/main/backend/app/models/auth.py): `backend/app/models/auth.py`
- [Core records](https://github.com/wahidakhtar/arcad/blob/main/backend/app/models/core.py): `backend/app/models/core.py`
- [People records](https://github.com/wahidakhtar/arcad/blob/main/backend/app/models/hr.py): `backend/app/models/hr.py`

### Other components

- **Staff user**
- **Redis**

## Connections

- Staff user → Page router: uses (evidence: `frontend/src/App.tsx`)
- Page router → Auth context: checks session (evidence: `frontend/src/App.tsx`)
- Page router → Live updates client: opens live connection (evidence: `frontend/src/App.tsx`)
- Page router → Transactions UI: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Site detail UI: routes to (evidence: `frontend/src/App.tsx`)
- Page router → PO detail UI: routes to (evidence: `frontend/src/App.tsx`)
- Auth context → API client: requests session (evidence: `frontend/src/context/AuthContext.tsx`)
- Transactions UI → API client: fetches records (evidence: `frontend/src/features/transactions/hooks/useTransactionsPage.ts`)
- Transactions UI → Live updates client: subscribes events (evidence: `frontend/src/features/transactions/hooks/useTransactionsPage.ts`)
- Site detail UI → API client: loads site data (evidence: `frontend/src/features/sites/siteDetail/hooks/useSiteDetail.ts`)
- Site detail UI → Live updates client: subscribes events (evidence: `frontend/src/features/sites/siteDetail/hooks/useSiteDetail.ts`)
- PO detail UI → Live updates client: subscribes events (evidence: `frontend/src/features/billing/po/hooks/usePoDetail.ts`)
- API client → FastAPI application: HTTP requests
- Live updates client → WebSocket manager: receives broadcasts
- FastAPI application → Authentication routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Billing routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Operations routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Project routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Ticket routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Transaction routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Dashboard service: loads dashboard
- Authentication routes → Auth service: uses service (evidence: `backend/app/api/routes/auth.py`)
- Authentication routes → Session authorization: uses authorization (evidence: `backend/app/api/routes/auth.py`)
- Session authorization → Session cache: reads session cache (evidence: `backend/app/api/auth.py`)
- Session authorization → Relational database: loads user context (evidence: `backend/app/api/auth.py`)
- Auth service → Session cache: invalidates sessions (evidence: `backend/app/services/auth.py`)
- Auth service → Auth records: persists tokens (evidence: `backend/app/services/auth.py`)
- Auth service → People records: reads users (evidence: `backend/app/services/auth.py`)
- Session cache → Redis: uses store (evidence: `backend/app/core/cache.py`)
- Relational database → FastAPI application: configured at startup (evidence: `backend/app/main.py`)
- Billing routes → Billing service: calls service (evidence: `backend/app/api/routes/billing.py`)
- Billing routes → Accounting rules: applies rules (evidence: `backend/app/api/routes/billing.py`)
- Billing routes → WebSocket manager: broadcasts updates (evidence: `backend/app/api/routes/billing.py`)
- Billing service → Relational database: uses persistence
- Operations routes → Operations services: uses service
- Accounting rules → Relational database: uses persistence
- Relational database → Core records: model base (evidence: `backend/app/models/core.py`)
- Relational database → Auth records: model base (evidence: `backend/app/models/auth.py`)
