# bhalisasodo/tenderpreneur architecture

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

- Interactive diagram: https://gitdiagram.com/bhalisasodo/tenderpreneur
- Repository: https://github.com/bhalisasodo/tenderpreneur

## Overview

BoQPro is a procurement-pricing platform for South African tender contractors and suppliers. Contractors create a BoQ, upload or enter scope, parse and correct line items, then match suppliers and broadcast quote requests; suppliers submit quotes, which contractors compare and select or override before producing audit-ready exports. The graph includes the contractor and supplier portals, API domain stages, and persistence, audit, and provider-adapter layers. Relationships not visible in excerpts are included only where documented in the README; unsampled adapter internals are not inferred.

Main entry points: [`apps/api/app/main.py`](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/main.py) (FastAPI application), [`apps/api/app/domains/parsing/router.py`](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/router.py) (Document parsing), [`apps/api/app/domains/quotes/router.py`](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/quotes/router.py) (Quote requests), [`apps/api/app/core/database.py`](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/core/database.py) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["User portals"]
  node_contractor_ui["Contractor portal"]
  node_supplier_ui["Supplier portal"]
  node_api_client["Web API client<br/>[api.ts]"]
end

subgraph group_boq["BoQ preparation"]
  node_boq_api["BoQ management<br/>[router.py]"]
  node_parsing_api["Document parsing<br/>[router.py]"]
  node_segmentation["Scope segmentation<br/>[segmentation.py]"]
  node_spreadsheet["Spreadsheet extraction<br/>[spreadsheet.py]"]
  node_llm["LLM adapters"]
end

subgraph group_sourcing["Supplier sourcing"]
  node_supplier_api["Supplier profiles<br/>[router.py]"]
  node_matching["Supplier matching<br/>[service.py]"]
  node_quotes["Quote requests<br/>[router.py]"]
  node_notifications["Notifications"]
  node_exports["Export generation<br/>[router.py]"]
  node_renderer["PDF and Excel renderer<br/>[renderer.py]"]
end

subgraph group_platform["API and platform"]
  node_auth["Authentication<br/>[router.py]"]
  node_audit["Audit trail<br/>[service.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("Database<br/>[database.py]")]
  node_api["FastAPI application<br/>[main.py]"]
end

node_contractor(("Contractor"))
node_supplier(("Supplier"))

node_contractor -->|"uses"| node_contractor_ui
node_supplier -->|"uses"| node_supplier_ui
node_contractor_ui -->|"requests via"| node_api_client
node_supplier_ui -->|"requests via"| node_api_client
node_api_client -->|"calls API"| node_api
node_api -->|"registers route"| node_boq_api
node_api -->|"registers route"| node_parsing_api
node_api -->|"registers route"| node_supplier_api
node_api -->|"registers route"| node_quotes
node_api -->|"registers route"| node_exports
node_api -->|"registers route"| node_auth
node_boq_api -->|"starts parsing"| node_parsing_api
node_parsing_api -->|"structures scope"| node_segmentation
node_parsing_api -->|"extracts spreadsheets"| node_spreadsheet
node_parsing_api -->|"uses provider"| node_llm
node_quotes -->|"matches suppliers"| node_matching
node_supplier_api -->|"supplies profiles"| node_matching
node_quotes -->|"notifies suppliers"| node_notifications
node_supplier_ui -->|"submits quotes via"| node_quotes
node_contractor_ui -->|"compares quotes via"| node_quotes
node_contractor_ui -->|"requests exports via"| node_exports
node_exports -->|"renders files"| node_renderer
node_boq_api -->|"records changes"| node_audit
node_parsing_api -->|"records parse"| node_audit
node_quotes -->|"records quote actions"| node_audit
node_exports -->|"reads history"| node_audit
node_boq_api -->|"reads and writes"| node_database
node_parsing_api -->|"reads and writes"| node_database
node_quotes -->|"reads and writes"| node_database
node_matching -->|"reads profiles"| node_database
node_audit -->|"persists events"| node_database
node_database -->|"maps entities"| node_models
node_auth -->|"authenticates against"| node_database

click node_contractor_ui "https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/web/app/contractor"
click node_supplier_ui "https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/web/app/supplier"
click node_api_client "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/web/lib/api.ts"
click node_boq_api "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/boq/router.py"
click node_parsing_api "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/router.py"
click node_segmentation "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/segmentation.py"
click node_spreadsheet "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/spreadsheet.py"
click node_llm "https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/api/app/integrations/llm"
click node_supplier_api "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/suppliers/router.py"
click node_matching "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/matching/service.py"
click node_quotes "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/quotes/router.py"
click node_notifications "https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/api/app/integrations/notifications"
click node_exports "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/exports/router.py"
click node_renderer "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/integrations/exports/renderer.py"
click node_auth "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/auth/router.py"
click node_audit "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/audit/service.py"
click node_models "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/core/models.py"
click node_database "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/core/database.py"
click node_api "https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/main.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_contractor_ui,node_supplier_ui,node_api_client toneBlue
class node_boq_api,node_parsing_api,node_segmentation,node_spreadsheet,node_llm toneAmber
class node_supplier_api,node_matching,node_quotes,node_notifications,node_exports,node_renderer toneMint
class node_auth,node_audit,node_models,node_database,node_api toneRose
class node_contractor,node_supplier toneIndigo
```

## Components

### User portals

- [Contractor portal](https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/web/app/contractor): `apps/web/app/contractor`
- [Supplier portal](https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/web/app/supplier): `apps/web/app/supplier`
- [Web API client](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### BoQ preparation

- [BoQ management](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/boq/router.py): `apps/api/app/domains/boq/router.py`
- [Document parsing](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/router.py): `apps/api/app/domains/parsing/router.py`
- [Scope segmentation](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/segmentation.py): `apps/api/app/domains/parsing/segmentation.py`
- [Spreadsheet extraction](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/parsing/spreadsheet.py): `apps/api/app/domains/parsing/spreadsheet.py`
- [LLM adapters](https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/api/app/integrations/llm): `apps/api/app/integrations/llm`

### Supplier sourcing

- [Supplier profiles](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/suppliers/router.py): `apps/api/app/domains/suppliers/router.py`
- [Supplier matching](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/matching/service.py): `apps/api/app/domains/matching/service.py`
- [Quote requests](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/quotes/router.py): `apps/api/app/domains/quotes/router.py`
- [Notifications](https://github.com/bhalisasodo/tenderpreneur/tree/main/apps/api/app/integrations/notifications): `apps/api/app/integrations/notifications`
- [Export generation](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/exports/router.py): `apps/api/app/domains/exports/router.py`
- [PDF and Excel renderer](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/integrations/exports/renderer.py): `apps/api/app/integrations/exports/renderer.py`

### API and platform

- [Authentication](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/auth/router.py): `apps/api/app/domains/auth/router.py`
- [Audit trail](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/domains/audit/service.py): `apps/api/app/domains/audit/service.py`
- [Domain models](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/core/models.py): `apps/api/app/core/models.py`
- [Database](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/core/database.py): `apps/api/app/core/database.py`
- [FastAPI application](https://github.com/bhalisasodo/tenderpreneur/blob/main/apps/api/app/main.py): `apps/api/app/main.py`

### Other components

- **Contractor**
- **Supplier**

## Connections

- Contractor → Contractor portal: uses (evidence: `README.md`)
- Supplier → Supplier portal: uses (evidence: `README.md`)
- Contractor portal → Web API client: requests via (evidence: `apps/web/app/contractor/boqs/new/page.tsx`)
- Supplier portal → Web API client: requests via (evidence: `apps/web/app/supplier/page.tsx`)
- Web API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → BoQ management: registers route (evidence: `apps/api/app/main.py`)
- FastAPI application → Document parsing: registers route (evidence: `apps/api/app/main.py`)
- FastAPI application → Supplier profiles: registers route (evidence: `apps/api/app/main.py`)
- FastAPI application → Quote requests: registers route (evidence: `apps/api/app/main.py`)
- FastAPI application → Export generation: registers route (evidence: `apps/api/app/main.py`)
- FastAPI application → Authentication: registers route (evidence: `apps/api/app/main.py`)
- BoQ management → Document parsing: starts parsing (evidence: `README.md`)
- Document parsing → Scope segmentation: structures scope (evidence: `README.md`)
- Document parsing → Spreadsheet extraction: extracts spreadsheets (evidence: `README.md`)
- Document parsing → LLM adapters: uses provider (evidence: `apps/api/app/domains/parsing/router.py`)
- Quote requests → Supplier matching: matches suppliers (evidence: `apps/api/app/domains/quotes/router.py`)
- Supplier profiles → Supplier matching: supplies profiles (evidence: `apps/api/app/domains/suppliers/router.py`)
- Quote requests → Notifications: notifies suppliers (evidence: `README.md`)
- Supplier portal → Quote requests: submits quotes via (evidence: `README.md`)
- Contractor portal → Quote requests: compares quotes via (evidence: `README.md`)
- Contractor portal → Export generation: requests exports via (evidence: `README.md`)
- Export generation → PDF and Excel renderer: renders files (evidence: `apps/api/app/domains/exports/router.py`)
- BoQ management → Audit trail: records changes (evidence: `apps/api/app/domains/boq/router.py`)
- Document parsing → Audit trail: records parse (evidence: `apps/api/app/domains/parsing/router.py`)
- Quote requests → Audit trail: records quote actions (evidence: `apps/api/app/domains/quotes/router.py`)
- Export generation → Audit trail: reads history (evidence: `apps/api/app/domains/exports/router.py`)
- BoQ management → Database: reads and writes (evidence: `apps/api/app/domains/boq/router.py`)
- Document parsing → Database: reads and writes (evidence: `apps/api/app/domains/parsing/router.py`)
- Quote requests → Database: reads and writes (evidence: `apps/api/app/domains/quotes/router.py`)
- Supplier matching → Database: reads profiles (evidence: `apps/api/app/domains/matching/service.py`)
- Audit trail → Database: persists events (evidence: `apps/api/app/domains/audit/service.py`)
- Database → Domain models: maps entities (evidence: `apps/api/app/core/models.py`)
- Authentication → Database: authenticates against (evidence: `apps/api/app/domains/auth/router.py`)
