# ramesh1248ai-sys/firebid-sg architecture

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

- Interactive diagram: https://gitdiagram.com/ramesh1248ai-sys/firebid-sg
- Repository: https://github.com/ramesh1248ai-sys/firebid-sg

## Overview

FireBid is a tender/bid preparation and review platform. Its principal workflow takes uploaded tender documents through parsing and drawing analysis into quantity takeoff (QTO), then supports human review and downstream commercial work such as pricing, clarifications, risk, and submission. The graph also preserves API, job processing, AI, audit, and persistent storage layers. Evidence is limited to the supplied excerpts and SOURCE INDEX; README content was not provided, so some capability links are omitted rather than inferred.

Main entry points: [`backend/src/firebid/api/app.py`](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/api/app.py) (HTTP API), [`backend/src/firebid/services/parse_pipeline.py`](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/parse_pipeline.py) (Staged parsing), [`backend/src/firebid/jobs/tasks.py`](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/jobs/tasks.py) (Background jobs), [`backend/src/firebid/services/review.py`](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/review.py) (Review decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_users["User experience"]
  node_web["Web application<br/>[main.tsx]"]
  node_review_ui["Review workbench<br/>[ReviewPage.tsx]"]
end

subgraph group_intake["Document intake"]
  node_ingestion["Document ingestion<br/>[ingestion.py]"]
  node_documents[("Document records<br/>[documents.py]")]
  node_parse["Staged parsing<br/>[parse_pipeline.py]"]
end

subgraph group_analysis["Drawing analysis"]
  node_drawing["Drawing analysis"]
  node_symbols["Symbol mapping<br/>[symbols.py]"]
  node_qto["Quantity takeoff<br/>[qto.py]"]
  node_takeoff_data[("Takeoff records<br/>[takeoff.py]")]
end

subgraph group_commercial["Tender work"]
  node_review["Review decisions<br/>[review.py]"]
  node_boq["BOQ processing<br/>[boq.py]"]
  node_pricing["Pricing and costing<br/>[pricing.py]"]
  node_clarifications["Clarifications<br/>[clarifications.py]"]
  node_submission["Bid submission<br/>[submission.py]"]
end

subgraph group_platform["Platform services"]
  node_api["HTTP API<br/>[app.py]"]
  node_object_store[("Original files<br/>[object_store.py]")]
  node_jobs["Background jobs<br/>[tasks.py]"]
  node_sandbox["Sandbox runner<br/>[runner.py]"]
  node_state["Workflow rules<br/>[state_machines.py]"]
  node_audit[("Audit trail<br/>[audit.py]")]
  node_ai["AI gateway<br/>[router.py]"]
end

node_estimator(("Tender team"))

node_estimator -.->|"uses"| node_web
node_web -.->|"requests"| node_api
node_api -.->|"routes intake"| node_ingestion
node_ingestion -->|"stores originals"| node_object_store
node_ingestion -->|"records documents"| node_documents
node_jobs -->|"runs parsing"| node_parse
node_parse -->|"reads files"| node_object_store
node_parse -->|"runs isolated work"| node_sandbox
node_parse -->|"queues tasks"| node_jobs
node_parse -->|"invokes symbol work"| node_symbols
node_jobs -->|"opens stored files"| node_object_store
node_jobs -->|"invokes takeoff"| node_qto
node_api -.->|"routes analysis"| node_drawing
node_api -->|"routes mappings"| node_symbols
node_api -->|"routes takeoff"| node_qto
node_qto -->|"persists items"| node_takeoff_data
node_api -->|"routes review"| node_review
node_review_ui -.->|"loads review data"| node_api
node_review -->|"checks transitions"| node_state
node_review -->|"uses takeoff state"| node_qto
node_api -.->|"routes BOQ"| node_boq
node_api -.->|"routes pricing"| node_pricing
node_api -.->|"routes clarifications"| node_clarifications
node_api -.->|"routes submission"| node_submission
node_jobs -->|"classifies documents"| node_ai
node_api -->|"routes audit access"| node_audit
node_review -.->|"records actions"| node_audit

click node_web "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/frontend/src/main.tsx"
click node_review_ui "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/frontend/src/pages/ReviewPage.tsx"
click node_api "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/api/app.py"
click node_ingestion "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/ingestion.py"
click node_documents "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/db/models/documents.py"
click node_object_store "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/storage/object_store.py"
click node_jobs "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/jobs/tasks.py"
click node_parse "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/parse_pipeline.py"
click node_sandbox "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/sandbox/runner.py"
click node_drawing "https://github.com/ramesh1248ai-sys/firebid-sg/tree/main/backend/src/firebid/drawings"
click node_symbols "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/symbols.py"
click node_qto "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/qto.py"
click node_takeoff_data "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/db/models/takeoff.py"
click node_review "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/review.py"
click node_state "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/domain/state_machines.py"
click node_audit "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/db/audit.py"
click node_boq "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/boq.py"
click node_pricing "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/pricing.py"
click node_clarifications "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/clarifications.py"
click node_submission "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/submission.py"
click node_ai "https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/ai_gateway/router.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_review_ui toneBlue
class node_ingestion,node_documents,node_parse toneAmber
class node_drawing,node_symbols,node_qto,node_takeoff_data toneMint
class node_review,node_boq,node_pricing,node_clarifications,node_submission toneRose
class node_api,node_object_store,node_jobs,node_sandbox,node_state,node_audit,node_ai,node_estimator toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Review workbench](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/frontend/src/pages/ReviewPage.tsx): `frontend/src/pages/ReviewPage.tsx`

### Document intake

- [Document ingestion](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/ingestion.py): `backend/src/firebid/services/ingestion.py`
- [Document records](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/db/models/documents.py): `backend/src/firebid/db/models/documents.py`
- [Staged parsing](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/parse_pipeline.py): `backend/src/firebid/services/parse_pipeline.py`

### Drawing analysis

- [Drawing analysis](https://github.com/ramesh1248ai-sys/firebid-sg/tree/main/backend/src/firebid/drawings): `backend/src/firebid/drawings`
- [Symbol mapping](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/symbols.py): `backend/src/firebid/services/symbols.py`
- [Quantity takeoff](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/qto.py): `backend/src/firebid/services/qto.py`
- [Takeoff records](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/db/models/takeoff.py): `backend/src/firebid/db/models/takeoff.py`

### Tender work

- [Review decisions](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/review.py): `backend/src/firebid/services/review.py`
- [BOQ processing](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/boq.py): `backend/src/firebid/services/boq.py`
- [Pricing and costing](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/pricing.py): `backend/src/firebid/services/pricing.py`
- [Clarifications](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/clarifications.py): `backend/src/firebid/services/clarifications.py`
- [Bid submission](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/services/submission.py): `backend/src/firebid/services/submission.py`

### Platform services

- [HTTP API](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/api/app.py): `backend/src/firebid/api/app.py`
- [Original files](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/storage/object_store.py): `backend/src/firebid/storage/object_store.py`
- [Background jobs](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/jobs/tasks.py): `backend/src/firebid/jobs/tasks.py`
- [Sandbox runner](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/sandbox/runner.py): `backend/src/firebid/sandbox/runner.py`
- [Workflow rules](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/domain/state_machines.py): `backend/src/firebid/domain/state_machines.py`
- [Audit trail](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/db/audit.py): `backend/src/firebid/db/audit.py`
- [AI gateway](https://github.com/ramesh1248ai-sys/firebid-sg/blob/main/backend/src/firebid/ai_gateway/router.py): `backend/src/firebid/ai_gateway/router.py`

### Other components

- **Tender team**

## Connections

- Tender team → Web application: uses
- Web application → HTTP API: requests
- HTTP API → Document ingestion: routes intake
- Document ingestion → Original files: stores originals (evidence: `backend/src/firebid/services/ingestion.py`)
- Document ingestion → Document records: records documents (evidence: `backend/src/firebid/services/ingestion.py`)
- Background jobs → Staged parsing: runs parsing (evidence: `backend/src/firebid/jobs/tasks.py`)
- Staged parsing → Original files: reads files (evidence: `backend/src/firebid/services/parse_pipeline.py`)
- Staged parsing → Sandbox runner: runs isolated work (evidence: `backend/src/firebid/services/parse_pipeline.py`)
- Staged parsing → Background jobs: queues tasks (evidence: `backend/src/firebid/services/parse_pipeline.py`)
- Staged parsing → Symbol mapping: invokes symbol work (evidence: `backend/src/firebid/services/parse_pipeline.py`)
- Background jobs → Original files: opens stored files (evidence: `backend/src/firebid/jobs/tasks.py`)
- Background jobs → Quantity takeoff: invokes takeoff (evidence: `backend/src/firebid/jobs/tasks.py`)
- HTTP API → Drawing analysis: routes analysis
- HTTP API → Symbol mapping: routes mappings (evidence: `backend/src/firebid/api/app.py`)
- HTTP API → Quantity takeoff: routes takeoff (evidence: `backend/src/firebid/api/app.py`)
- Quantity takeoff → Takeoff records: persists items (evidence: `backend/src/firebid/services/qto.py`)
- HTTP API → Review decisions: routes review (evidence: `backend/src/firebid/api/app.py`)
- Review workbench → HTTP API: loads review data
- Review decisions → Workflow rules: checks transitions (evidence: `backend/src/firebid/api/review.py`)
- Review decisions → Quantity takeoff: uses takeoff state (evidence: `backend/src/firebid/api/review.py`)
- HTTP API → BOQ processing: routes BOQ
- HTTP API → Pricing and costing: routes pricing
- HTTP API → Clarifications: routes clarifications
- HTTP API → Bid submission: routes submission
- Background jobs → AI gateway: classifies documents (evidence: `backend/src/firebid/jobs/tasks.py`)
- HTTP API → Audit trail: routes audit access (evidence: `backend/src/firebid/api/app.py`)
- Review decisions → Audit trail: records actions
