# wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform architecture

> Architecture diagram of the GitHub repository wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform
- Repository: https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform

## Overview

ProcureIQ is an expert-led procurement intelligence workspace, presented through a React demo frontend and a FastAPI backend foundation. The intended journey captures customers and purchase needs, scopes an engagement, organizes supplier research and evidence, compares options, drafts recommendations, and records human review. The frontend mostly uses browser storage and is not connected to backend authentication or most backend workflows; procurement records also do not imply real vendor delivery or purchasing. Backend relationships are included where the source index or README supports them; unsampled implementation details are not inferred.

Main entry points: [`src/app/AppRouter.tsx`](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/app/AppRouter.tsx) (App routing), [`backend/app/api/v1/router.py`](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/router.py) (Versioned API router), [`src/lib/storage.ts`](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/storage.ts) (Browser storage), [`src/lib/recommendationsStorage.ts`](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/recommendationsStorage.ts) (Recommendation storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Workspace frontend"]
  node_router["App routing<br/>[AppRouter.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_customers["Customer records<br/>[CustomersPage.tsx]"]
  node_engagements["Engagement setup"]
  node_research_ui["Research workspace"]
  node_findings_ui["Findings comparison<br/>[FindingsPage.tsx]"]
  node_recommendations_ui["Recommendation drafts"]
  node_review_ui["Customer review"]
  node_roadmap_ui["Roadmap<br/>[RoadmapPage.tsx]"]
  node_solutions["Solutions hub"]
  node_knowledge["Knowledge hub"]
  node_procureiq_ui["ProcureIQ overview<br/>[ProcureIQPage.tsx]"]
end

subgraph group_local["Demo workspace state"]
  node_browser_store[("Browser storage<br/>[storage.ts]")]
  node_customer_state["Customer storage<br/>[customerStorage.ts]"]
  node_engagement_state["Engagement storage"]
  node_finding_state["Evidence and scores<br/>[findingsStorage.ts]"]
  node_recommendation_state["Recommendation storage"]
  node_review_state["Review state<br/>[reviewStorage.ts]"]
end

subgraph group_backend["Backend API"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_api_router["Versioned API router<br/>[router.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_customer_api["Customer API<br/>[customers.py]"]
  node_engagement_api["Engagement API<br/>[engagements.py]"]
  node_research_api["Research API<br/>[research.py]"]
  node_procurement_api["Procurement APIs<br/>[procurement.py]"]
  node_recommendation_api["Recommendation API<br/>[recommendations.py]"]
  node_roadmap_api["Roadmap API<br/>[roadmaps.py]"]
  node_db_session["Database session<br/>[session.py]"]
  node_domain_models["Domain records<br/>[models.py]"]
end

subgraph group_services["Backend services"]
  node_llm["LLM provider service<br/>[llm_service.py]"]
  node_research_service["Research planning"]
  node_scoring["Weighted scoring<br/>[scoring.py]"]
end

node_user(("Procurement team"))
node_external_llm(("Configured LLM provider"))

node_user -->|"uses"| node_router
node_router -->|"routes to"| node_dashboard
node_router -->|"routes to"| node_customers
node_router -->|"routes to"| node_engagements
node_router -->|"routes to"| node_research_ui
node_router -->|"routes to"| node_findings_ui
node_router -->|"routes to"| node_recommendations_ui
node_router -->|"routes to"| node_review_ui
node_router -->|"routes to"| node_roadmap_ui
node_router -->|"routes to"| node_solutions
node_router -->|"routes to"| node_knowledge
node_router -.->|"routes to"| node_procureiq_ui
node_customers -.->|"reads and writes"| node_customer_state
node_engagements -->|"reads and writes"| node_engagement_state
node_research_ui -->|"reads and writes"| node_finding_state
node_findings_ui -->|"reads and writes"| node_finding_state
node_recommendations_ui -->|"generates drafts"| node_recommendation_state
node_recommendation_state -->|"reads findings and scores"| node_finding_state
node_review_ui -->|"reads draft"| node_recommendation_state
node_review_ui -->|"records decision"| node_review_state
node_customer_state -->|"reads and writes"| node_browser_store
node_engagement_state -->|"reads and writes"| node_browser_store
node_finding_state -->|"reads and writes"| node_browser_store
node_recommendation_state -->|"reads and writes"| node_browser_store
node_review_state -->|"reads and writes"| node_browser_store
node_backend_app -->|"mounts"| node_api_router
node_api_router -->|"registers"| node_auth_api
node_api_router -->|"registers"| node_customer_api
node_api_router -->|"registers"| node_engagement_api
node_api_router -->|"registers"| node_research_api
node_api_router -->|"registers"| node_procurement_api
node_api_router -->|"registers"| node_recommendation_api
node_api_router -->|"registers"| node_roadmap_api
node_engagement_api -->|"uses"| node_research_service
node_engagement_api -->|"uses"| node_llm
node_research_api -->|"uses"| node_research_service
node_research_service -->|"uses"| node_domain_models
node_llm -.->|"calls configured provider"| node_external_llm
node_backend_app -->|"initializes tables"| node_db_session
node_db_session -.->|"persists records"| node_domain_models
node_procurement_api -.->|"uses scoring"| node_scoring

click node_router "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/app/AppRouter.tsx"
click node_dashboard "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/dashboard/DashboardPage.tsx"
click node_customers "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/customers/CustomersPage.tsx"
click node_engagements "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/engagements/NewEngagementPage.tsx"
click node_research_ui "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/research/ResearchWorkspacePage.tsx"
click node_findings_ui "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/findings/FindingsPage.tsx"
click node_recommendations_ui "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/recommendations/RecommendationsPage.tsx"
click node_review_ui "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/approvals/CustomerReviewPage.tsx"
click node_roadmap_ui "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/roadmap/RoadmapPage.tsx"
click node_solutions "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/solutions/SolutionsHubPage.tsx"
click node_knowledge "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/knowledge/KnowledgeHubPage.tsx"
click node_procureiq_ui "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/procureiq/ProcureIQPage.tsx"
click node_browser_store "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/storage.ts"
click node_customer_state "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/customerStorage.ts"
click node_engagement_state "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/engagementStorage.ts"
click node_finding_state "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/findingsStorage.ts"
click node_recommendation_state "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/recommendationsStorage.ts"
click node_review_state "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/reviewStorage.ts"
click node_backend_app "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/main.py"
click node_api_router "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/router.py"
click node_auth_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/auth.py"
click node_customer_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/customers.py"
click node_engagement_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/engagements.py"
click node_research_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/research.py"
click node_procurement_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/procurement.py"
click node_recommendation_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/recommendations.py"
click node_roadmap_api "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/roadmaps.py"
click node_db_session "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/db/session.py"
click node_domain_models "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/models.py"
click node_llm "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/services/llm_service.py"
click node_research_service "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/services/research_service.py"
click node_scoring "https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/services/procurement/scoring.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_router,node_dashboard,node_customers,node_engagements,node_research_ui,node_findings_ui,node_recommendations_ui,node_review_ui,node_roadmap_ui,node_solutions,node_knowledge,node_procureiq_ui toneBlue
class node_browser_store,node_customer_state,node_engagement_state,node_finding_state,node_recommendation_state,node_review_state toneAmber
class node_backend_app,node_api_router,node_auth_api,node_customer_api,node_engagement_api,node_research_api,node_procurement_api,node_recommendation_api,node_roadmap_api,node_db_session,node_domain_models toneMint
class node_llm,node_research_service,node_scoring toneRose
class node_user,node_external_llm toneIndigo
```

## Components

### Workspace frontend

- [App routing](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/app/AppRouter.tsx): `src/app/AppRouter.tsx`
- [Dashboard](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/dashboard/DashboardPage.tsx): `src/features/dashboard/DashboardPage.tsx`
- [Customer records](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/customers/CustomersPage.tsx): `src/features/customers/CustomersPage.tsx`
- [Engagement setup](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/engagements/NewEngagementPage.tsx): `src/features/engagements/NewEngagementPage.tsx`
- [Research workspace](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/research/ResearchWorkspacePage.tsx): `src/features/research/ResearchWorkspacePage.tsx`
- [Findings comparison](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/findings/FindingsPage.tsx): `src/features/findings/FindingsPage.tsx`
- [Recommendation drafts](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/recommendations/RecommendationsPage.tsx): `src/features/recommendations/RecommendationsPage.tsx`
- [Customer review](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/approvals/CustomerReviewPage.tsx): `src/features/approvals/CustomerReviewPage.tsx`
- [Roadmap](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/roadmap/RoadmapPage.tsx): `src/features/roadmap/RoadmapPage.tsx`
- [Solutions hub](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/solutions/SolutionsHubPage.tsx): `src/features/solutions/SolutionsHubPage.tsx`
- [Knowledge hub](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/knowledge/KnowledgeHubPage.tsx): `src/features/knowledge/KnowledgeHubPage.tsx`
- [ProcureIQ overview](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/features/procureiq/ProcureIQPage.tsx): `src/features/procureiq/ProcureIQPage.tsx`

### Demo workspace state

- [Browser storage](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/storage.ts): `src/lib/storage.ts`
- [Customer storage](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/customerStorage.ts): `src/lib/customerStorage.ts`
- [Engagement storage](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/engagementStorage.ts): `src/lib/engagementStorage.ts`
- [Evidence and scores](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/findingsStorage.ts): `src/lib/findingsStorage.ts`
- [Recommendation storage](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/recommendationsStorage.ts): `src/lib/recommendationsStorage.ts`
- [Review state](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/src/lib/reviewStorage.ts): `src/lib/reviewStorage.ts`

### Backend API

- [FastAPI application](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/main.py): `backend/app/main.py`
- [Versioned API router](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Authentication API](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Customer API](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/customers.py): `backend/app/api/v1/endpoints/customers.py`
- [Engagement API](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/engagements.py): `backend/app/api/v1/endpoints/engagements.py`
- [Research API](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/research.py): `backend/app/api/v1/endpoints/research.py`
- [Procurement APIs](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/procurement.py): `backend/app/api/v1/endpoints/procurement.py`
- [Recommendation API](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/recommendations.py): `backend/app/api/v1/endpoints/recommendations.py`
- [Roadmap API](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/api/v1/endpoints/roadmaps.py): `backend/app/api/v1/endpoints/roadmaps.py`
- [Database session](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/db/session.py): `backend/app/db/session.py`
- [Domain records](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/models.py): `backend/app/models.py`

### Backend services

- [LLM provider service](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`
- [Research planning](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/services/research_service.py): `backend/app/services/research_service.py`
- [Weighted scoring](https://github.com/wicked-vultr/procureiq_ai-powered-procurement-intelligence-platform/blob/izwa-frontend/backend/app/services/procurement/scoring.py): `backend/app/services/procurement/scoring.py`

### Other components

- **Procurement team**
- **Configured LLM provider**

## Connections

- Procurement team → App routing: uses (evidence: `src/app/AppRouter.tsx`)
- App routing → Dashboard: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Customer records: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Engagement setup: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Research workspace: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Findings comparison: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Recommendation drafts: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Customer review: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Roadmap: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Solutions hub: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → Knowledge hub: routes to (evidence: `src/app/AppRouter.tsx`)
- App routing → ProcureIQ overview: routes to
- Customer records → Customer storage: reads and writes
- Engagement setup → Engagement storage: reads and writes (evidence: `src/features/engagements/NewEngagementPage.tsx`)
- Research workspace → Evidence and scores: reads and writes (evidence: `src/features/research/ResearchWorkspacePage.tsx`)
- Findings comparison → Evidence and scores: reads and writes (evidence: `src/features/findings/FindingsPage.tsx`)
- Recommendation drafts → Recommendation storage: generates drafts (evidence: `src/lib/recommendationsStorage.ts`)
- Recommendation storage → Evidence and scores: reads findings and scores (evidence: `src/lib/recommendationsStorage.ts`)
- Customer review → Recommendation storage: reads draft (evidence: `src/features/approvals/CustomerReviewPage.tsx`)
- Customer review → Review state: records decision (evidence: `src/features/approvals/CustomerReviewPage.tsx`)
- Customer storage → Browser storage: reads and writes (evidence: `src/lib/customerStorage.ts`)
- Engagement storage → Browser storage: reads and writes (evidence: `src/lib/engagementStorage.ts`)
- Evidence and scores → Browser storage: reads and writes (evidence: `src/lib/findingsStorage.ts`)
- Recommendation storage → Browser storage: reads and writes (evidence: `src/lib/recommendationsStorage.ts`)
- Review state → Browser storage: reads and writes (evidence: `src/lib/reviewStorage.ts`)
- FastAPI application → Versioned API router: mounts (evidence: `backend/app/main.py`)
- Versioned API router → Authentication API: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API router → Customer API: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API router → Engagement API: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API router → Research API: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API router → Procurement APIs: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API router → Recommendation API: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API router → Roadmap API: registers (evidence: `backend/app/api/v1/router.py`)
- Engagement API → Research planning: uses (evidence: `backend/app/api/v1/endpoints/engagements.py`)
- Engagement API → LLM provider service: uses (evidence: `backend/app/api/v1/endpoints/engagements.py`)
- Research API → Research planning: uses (evidence: `backend/app/api/v1/endpoints/research.py`)
- Research planning → Domain records: uses (evidence: `backend/app/services/research_service.py`)
- LLM provider service → Configured LLM provider: calls configured provider (evidence: `README.md`)
- FastAPI application → Database session: initializes tables (evidence: `backend/app/main.py`)
- Database session → Domain records: persists records
- Procurement APIs → Weighted scoring: uses scoring