# dracula-5/procurax architecture

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

- Interactive diagram: https://gitdiagram.com/dracula-5/procurax
- Repository: https://github.com/dracula-5/procurax

## Overview

ProcuraX is a multi-tenant procurement platform whose main workflow takes a user from authenticated purchase-request submission through policy-controlled approval and budget checks into purchase-order, receipt, invoice-matching, and payment-approval stages. The React SPA is the user surface; a FastAPI modular monolith hosts domain rules and procurement services, with PostgreSQL providing tenant-scoped persistence and audit history. The README documents additional spend intelligence, sourcing, and invoice-assistance capabilities. Some feature modules were not sampled, so their internal call paths are not asserted.

Main entry points: [`backend/app/api/router.py`](https://github.com/dracula-5/procurax/blob/main/backend/app/api/router.py) (API router), [`backend/app/modules/procurement/service.py`](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/service.py) (Request approvals), [`backend/app/modules/audit/service.py`](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/audit/service.py) (Audit trail), [`frontend/src/App.tsx`](https://github.com/dracula-5/procurax/blob/main/frontend/src/App.tsx) (React SPA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_spa["React SPA<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_ui["Session context<br/>[AuthContext.tsx]"]
  node_work_ui["Procurement screens<br/>[PurchaseToPay.tsx]"]
end

subgraph group_api["API and identity"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_api_routes["API router<br/>[router.py]"]
  node_identity["Identity service<br/>[service.py]"]
  node_request_context["Authenticated principal<br/>[deps.py]"]
end

subgraph group_procurement["Procurement workflow"]
  node_proc_service["Request approvals<br/>[service.py]"]
  node_p2p_records["P2P records<br/>[records_router.py]"]
  node_procurement_features["Delegation and escalation"]
  node_vendors["Vendor master<br/>[service.py]"]
  node_org_budgets["Organization and budgets<br/>[service.py]"]
end

subgraph group_domain["Domain and intelligence"]
  node_policy["Policy evaluation<br/>[engine.py]"]
  node_workflow_domain["Request state machine"]
  node_intelligence["Spend and invoice AI"]
  node_sourcing["Sourcing support"]
  node_assistant["Procurement assistant<br/>[assistant.py]"]
end

subgraph group_platform["Persistence and governance"]
  node_audit["Audit trail<br/>[service.py]"]
  node_database[("Tenant database<br/>[db.py]")]
end

node_user(("Procurement user"))

node_user -->|"uses"| node_spa
node_spa -->|"loads session"| node_auth_ui
node_spa -->|"routes to"| node_work_ui
node_work_ui -.->|"requests data"| node_api_client
node_auth_ui -->|"uses"| node_api_client
node_api_client -->|"calls API"| node_api_entry
node_api_entry -->|"registers"| node_api_routes
node_api_routes -->|"routes identity"| node_identity
node_api_routes -.->|"routes procurement"| node_proc_service
node_api_routes -->|"routes records"| node_p2p_records
node_api_routes -->|"routes vendors"| node_vendors
node_api_routes -->|"routes assistant"| node_assistant
node_identity -->|"records actions"| node_audit
node_request_context -->|"binds tenant"| node_database
node_proc_service -->|"evaluates rules"| node_policy
node_proc_service -->|"checks transitions"| node_workflow_domain
node_proc_service -->|"uses organization services"| node_org_budgets
node_proc_service -->|"records decisions"| node_audit
node_p2p_records -->|"records changes"| node_audit
node_p2p_records -->|"reads and writes"| node_database
node_vendors -->|"records changes"| node_audit
node_org_budgets -->|"records changes"| node_audit
node_sourcing -.->|"ranks vendors"| node_intelligence
node_assistant -.->|"retrieves knowledge"| node_intelligence
node_audit -->|"stores entries"| node_database
node_procurement_features -.->|"supports workflow"| node_proc_service

click node_spa "https://github.com/dracula-5/procurax/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/dracula-5/procurax/blob/main/frontend/src/lib/api.ts"
click node_auth_ui "https://github.com/dracula-5/procurax/blob/main/frontend/src/auth/AuthContext.tsx"
click node_work_ui "https://github.com/dracula-5/procurax/blob/main/frontend/src/pages/PurchaseToPay.tsx"
click node_api_entry "https://github.com/dracula-5/procurax/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/dracula-5/procurax/blob/main/backend/app/api/router.py"
click node_identity "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/identity/service.py"
click node_request_context "https://github.com/dracula-5/procurax/blob/main/backend/app/api/deps.py"
click node_proc_service "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/service.py"
click node_p2p_records "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/records_router.py"
click node_procurement_features "https://github.com/dracula-5/procurax/tree/main/backend/app/modules/procurement"
click node_vendors "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/vendors/service.py"
click node_org_budgets "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/organization/service.py"
click node_policy "https://github.com/dracula-5/procurax/blob/main/backend/app/domain/policy/engine.py"
click node_workflow_domain "https://github.com/dracula-5/procurax/blob/main/backend/app/domain/workflow/purchase_request.py"
click node_intelligence "https://github.com/dracula-5/procurax/tree/main/backend/app/ml"
click node_sourcing "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/decision_support.py"
click node_assistant "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/assistant.py"
click node_audit "https://github.com/dracula-5/procurax/blob/main/backend/app/modules/audit/service.py"
click node_database "https://github.com/dracula-5/procurax/blob/main/backend/app/core/db.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_spa,node_api_client,node_auth_ui,node_work_ui,node_user toneBlue
class node_api_entry,node_api_routes,node_identity,node_request_context toneAmber
class node_proc_service,node_p2p_records,node_procurement_features,node_vendors,node_org_budgets toneMint
class node_policy,node_workflow_domain,node_intelligence,node_sourcing,node_assistant toneRose
class node_audit,node_database toneIndigo
```

## Components

### Web application

- [React SPA](https://github.com/dracula-5/procurax/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/dracula-5/procurax/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Session context](https://github.com/dracula-5/procurax/blob/main/frontend/src/auth/AuthContext.tsx): `frontend/src/auth/AuthContext.tsx`
- [Procurement screens](https://github.com/dracula-5/procurax/blob/main/frontend/src/pages/PurchaseToPay.tsx): `frontend/src/pages/PurchaseToPay.tsx`

### API and identity

- [FastAPI entry](https://github.com/dracula-5/procurax/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/dracula-5/procurax/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Identity service](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/identity/service.py): `backend/app/modules/identity/service.py`
- [Authenticated principal](https://github.com/dracula-5/procurax/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`

### Procurement workflow

- [Request approvals](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/service.py): `backend/app/modules/procurement/service.py`
- [P2P records](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/records_router.py): `backend/app/modules/procurement/records_router.py`
- [Delegation and escalation](https://github.com/dracula-5/procurax/tree/main/backend/app/modules/procurement): `backend/app/modules/procurement`
- [Vendor master](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/vendors/service.py): `backend/app/modules/vendors/service.py`
- [Organization and budgets](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/organization/service.py): `backend/app/modules/organization/service.py`

### Domain and intelligence

- [Policy evaluation](https://github.com/dracula-5/procurax/blob/main/backend/app/domain/policy/engine.py): `backend/app/domain/policy/engine.py`
- [Request state machine](https://github.com/dracula-5/procurax/blob/main/backend/app/domain/workflow/purchase_request.py): `backend/app/domain/workflow/purchase_request.py`
- [Spend and invoice AI](https://github.com/dracula-5/procurax/tree/main/backend/app/ml): `backend/app/ml`
- [Sourcing support](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/decision_support.py): `backend/app/modules/procurement/decision_support.py`
- [Procurement assistant](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/procurement/assistant.py): `backend/app/modules/procurement/assistant.py`

### Persistence and governance

- [Audit trail](https://github.com/dracula-5/procurax/blob/main/backend/app/modules/audit/service.py): `backend/app/modules/audit/service.py`
- [Tenant database](https://github.com/dracula-5/procurax/blob/main/backend/app/core/db.py): `backend/app/core/db.py`

### Other components

- **Procurement user**

## Connections

- Procurement user → React SPA: uses (evidence: `README.md`)
- React SPA → Session context: loads session (evidence: `frontend/src/App.tsx`)
- React SPA → Procurement screens: routes to (evidence: `frontend/src/App.tsx`)
- Procurement screens → API client: requests data
- Session context → API client: uses (evidence: `frontend/src/auth/AuthContext.tsx`)
- API client → FastAPI entry: calls API (evidence: `README.md`)
- FastAPI entry → API router: registers (evidence: `backend/app/main.py`)
- API router → Identity service: routes identity (evidence: `backend/app/api/router.py`)
- API router → Request approvals: routes procurement
- API router → P2P records: routes records (evidence: `backend/app/api/router.py`)
- API router → Vendor master: routes vendors (evidence: `backend/app/api/router.py`)
- API router → Procurement assistant: routes assistant (evidence: `backend/app/api/router.py`)
- Identity service → Audit trail: records actions (evidence: `backend/app/modules/identity/service.py`)
- Authenticated principal → Tenant database: binds tenant (evidence: `backend/app/api/deps.py`)
- Request approvals → Policy evaluation: evaluates rules (evidence: `backend/app/modules/procurement/service.py`)
- Request approvals → Request state machine: checks transitions (evidence: `backend/app/modules/procurement/service.py`)
- Request approvals → Organization and budgets: uses organization services (evidence: `backend/app/modules/procurement/service.py`)
- Request approvals → Audit trail: records decisions (evidence: `backend/app/modules/procurement/service.py`)
- P2P records → Audit trail: records changes (evidence: `backend/app/modules/procurement/records_router.py`)
- P2P records → Tenant database: reads and writes (evidence: `backend/app/modules/procurement/records_router.py`)
- Vendor master → Audit trail: records changes (evidence: `backend/app/modules/vendors/service.py`)
- Organization and budgets → Audit trail: records changes (evidence: `backend/app/modules/organization/service.py`)
- Sourcing support → Spend and invoice AI: ranks vendors
- Procurement assistant → Spend and invoice AI: retrieves knowledge (evidence: `README.md`)
- Audit trail → Tenant database: stores entries (evidence: `backend/app/modules/audit/service.py`)
- Delegation and escalation → Request approvals: supports workflow (evidence: `README.md`)
