# physics0070/autonomous-procurement-assistant- architecture

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

- Interactive diagram: https://gitdiagram.com/physics0070/autonomous-procurement-assistant-
- Repository: https://github.com/physics0070/autonomous-procurement-assistant-

## Overview

Autonomous Procurement Assistant is a web platform for collecting supplier quotations, turning varied documents into auditable normalized data, comparing suppliers, and supporting approval-gated procurement actions. The main workflow runs from the browser through API routes and shared ingestion into staged document processing, then validation, normalization, matching, and comparison. Separate branches cover Gmail collection, agent-assisted decisions, communications and purchase orders, and analytics/ML. Edges follow README-described flows or indexed source references; several route and service implementations were not sampled, so those links are documented rather than inferred from names.

Main entry points: [`backend/app/api/routes`](https://github.com/physics0070/autonomous-procurement-assistant-/tree/main/backend/app/api/routes) (API routes), [`backend/app/services/documents/pipeline.py`](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/pipeline.py) (Processing pipeline), [`backend/app/services/agents/supervisor.py`](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/agents/supervisor.py) (Agent orchestration), [`backend/app/services/documents/ingestion.py`](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/ingestion.py) (Document intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Web application<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api_routes["API routes"]
  node_auth_context["Tenant access<br/>[deps.py]"]
  node_quotation_store[("Quotation repository<br/>[quotations.py]")]
end

subgraph group_documents["Quotation processing"]
  node_ingestion["Document intake<br/>[ingestion.py]"]
  node_gmail["Gmail collection<br/>[gmail_sync.py]"]
  node_processing["Processing pipeline<br/>[pipeline.py]"]
  node_extractors["File extraction<br/>[processor.py]"]
  node_ai_extraction["AI extraction<br/>[ai_extraction.py]"]
  node_ai_provider["AI provider routing<br/>[factory.py]"]
  node_validation["Extraction validation<br/>[validation.py]"]
  node_normalization["Canonical normalization"]
end

subgraph group_decisions["Procurement decisions"]
  node_matching["Product matching<br/>[matching.py]"]
  node_comparison["Supplier comparison<br/>[comparison.py]"]
  node_agents["Agent orchestration<br/>[supervisor.py]"]
  node_assistant["Record assistant<br/>[assistant.py]"]
end

subgraph group_operations["Actions and intelligence"]
  node_communications["Draft communications<br/>[communications.py]"]
  node_purchase_orders["Purchase orders<br/>[purchase_orders.py]"]
  node_analytics["Spend analytics<br/>[spend.py]"]
  node_risk_ml["Supplier risk ML<br/>[reliability_ml.py]"]
  node_ml_models["Forecast and anomaly models"]
end

node_user(("Procurement user"))
node_mongodb[("MongoDB")]

node_user -->|"uses"| node_web
node_web -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api_routes
node_api_routes -->|"checks access"| node_auth_context
node_api_routes -->|"submits uploads"| node_ingestion
node_gmail -->|"submits messages"| node_ingestion
node_ingestion -->|"creates record"| node_quotation_store
node_processing -->|"extracts content"| node_extractors
node_processing -->|"structures data"| node_ai_extraction
node_ai_extraction -->|"requests model"| node_ai_provider
node_processing -->|"validates extraction"| node_validation
node_processing -->|"normalizes data"| node_normalization
node_processing -->|"matches items"| node_matching
node_matching -.->|"feeds comparison"| node_comparison
node_agents -->|"routes specialists"| node_comparison
node_agents -.->|"coordinates drafting"| node_communications
node_agents -.->|"coordinates ordering"| node_purchase_orders
node_assistant -->|"serves questions"| node_api_routes
node_api_routes -->|"requests drafts"| node_communications
node_api_routes -->|"manages orders"| node_purchase_orders
node_api_routes -->|"serves analytics"| node_analytics
node_api_routes -->|"serves risk"| node_risk_ml
node_analytics -->|"uses models"| node_ml_models
node_risk_ml -.->|"scores risk"| node_ml_models
node_quotation_store -->|"reads and writes"| node_mongodb

click node_web "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/frontend/src/lib/api.ts"
click node_api_routes "https://github.com/physics0070/autonomous-procurement-assistant-/tree/main/backend/app/api/routes"
click node_auth_context "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/api/deps.py"
click node_ingestion "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/ingestion.py"
click node_gmail "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/channels/gmail_sync.py"
click node_processing "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/pipeline.py"
click node_extractors "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/processor.py"
click node_ai_extraction "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/ai_extraction.py"
click node_ai_provider "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/integrations/ai/factory.py"
click node_validation "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/validation.py"
click node_normalization "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/normalizer_service.py"
click node_matching "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/matching.py"
click node_comparison "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/comparison.py"
click node_agents "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/agents/supervisor.py"
click node_assistant "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/agents/assistant.py"
click node_communications "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/automation/communications.py"
click node_purchase_orders "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/automation/purchase_orders.py"
click node_analytics "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/analytics/spend.py"
click node_risk_ml "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/analytics/reliability_ml.py"
click node_ml_models "https://github.com/physics0070/autonomous-procurement-assistant-/tree/main/backend/ml"
click node_quotation_store "https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/repositories/quotations.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_web,node_api_client,node_user toneBlue
class node_api_routes,node_auth_context,node_quotation_store,node_mongodb toneAmber
class node_ingestion,node_gmail,node_processing,node_extractors,node_ai_extraction,node_ai_provider,node_validation,node_normalization toneMint
class node_matching,node_comparison,node_agents,node_assistant toneRose
class node_communications,node_purchase_orders,node_analytics,node_risk_ml,node_ml_models toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and access

- [API routes](https://github.com/physics0070/autonomous-procurement-assistant-/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Tenant access](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Quotation repository](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/repositories/quotations.py): `backend/app/repositories/quotations.py`

### Quotation processing

- [Document intake](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/ingestion.py): `backend/app/services/documents/ingestion.py`
- [Gmail collection](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/channels/gmail_sync.py): `backend/app/services/channels/gmail_sync.py`
- [Processing pipeline](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/pipeline.py): `backend/app/services/documents/pipeline.py`
- [File extraction](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/processor.py): `backend/app/services/documents/processor.py`
- [AI extraction](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/documents/ai_extraction.py): `backend/app/services/documents/ai_extraction.py`
- [AI provider routing](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/integrations/ai/factory.py): `backend/app/integrations/ai/factory.py`
- [Extraction validation](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/validation.py): `backend/app/services/procurement/validation.py`
- [Canonical normalization](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/normalizer_service.py): `backend/app/services/procurement/normalizer_service.py`

### Procurement decisions

- [Product matching](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/matching.py): `backend/app/services/procurement/matching.py`
- [Supplier comparison](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/procurement/comparison.py): `backend/app/services/procurement/comparison.py`
- [Agent orchestration](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/agents/supervisor.py): `backend/app/services/agents/supervisor.py`
- [Record assistant](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/agents/assistant.py): `backend/app/services/agents/assistant.py`

### Actions and intelligence

- [Draft communications](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/automation/communications.py): `backend/app/services/automation/communications.py`
- [Purchase orders](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/automation/purchase_orders.py): `backend/app/services/automation/purchase_orders.py`
- [Spend analytics](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/analytics/spend.py): `backend/app/services/analytics/spend.py`
- [Supplier risk ML](https://github.com/physics0070/autonomous-procurement-assistant-/blob/main/backend/app/services/analytics/reliability_ml.py): `backend/app/services/analytics/reliability_ml.py`
- [Forecast and anomaly models](https://github.com/physics0070/autonomous-procurement-assistant-/tree/main/backend/ml): `backend/ml`

### Other components

- **Procurement user**
- **MongoDB**

## Connections

- Procurement user → Web application: uses
- Web application → API client: requests data
- API client → API routes: calls API
- API routes → Tenant access: checks access (evidence: `backend/app/api/deps.py`)
- API routes → Document intake: submits uploads
- Gmail collection → Document intake: submits messages
- Document intake → Quotation repository: creates record (evidence: `backend/app/services/documents/ingestion.py`)
- Processing pipeline → File extraction: extracts content (evidence: `backend/app/services/documents/pipeline.py`)
- Processing pipeline → AI extraction: structures data (evidence: `backend/app/services/documents/pipeline.py`)
- AI extraction → AI provider routing: requests model (evidence: `backend/app/services/documents/ai_extraction.py`)
- Processing pipeline → Extraction validation: validates extraction (evidence: `backend/app/services/documents/pipeline.py`)
- Processing pipeline → Canonical normalization: normalizes data (evidence: `backend/app/services/documents/pipeline.py`)
- Processing pipeline → Product matching: matches items (evidence: `backend/app/services/documents/pipeline.py`)
- Product matching → Supplier comparison: feeds comparison
- Agent orchestration → Supplier comparison: routes specialists
- Agent orchestration → Draft communications: coordinates drafting
- Agent orchestration → Purchase orders: coordinates ordering
- Record assistant → API routes: serves questions (evidence: `backend/app/api/routes/agents.py`)
- API routes → Draft communications: requests drafts (evidence: `backend/app/api/routes/automation.py`)
- API routes → Purchase orders: manages orders (evidence: `backend/app/api/routes/automation.py`)
- API routes → Spend analytics: serves analytics (evidence: `backend/app/api/routes/analytics.py`)
- API routes → Supplier risk ML: serves risk (evidence: `backend/app/api/routes/analytics.py`)
- Spend analytics → Forecast and anomaly models: uses models (evidence: `backend/app/api/routes/analytics.py`)
- Supplier risk ML → Forecast and anomaly models: scores risk
- Quotation repository → MongoDB: reads and writes
