# mrnk2107/procurewatch architecture

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

- Interactive diagram: https://gitdiagram.com/mrnk2107/procurewatch
- Repository: https://github.com/mrnk2107/procurewatch

## Overview

**ProcureWatch** is a **simple full-stack, 3-tier web application**:
- **Frontend**: React (Vite + TypeScript + Tailwind) renders dashboards/tables and calls APIs.
- **Backend**: FastAPI serves REST endpoints and orchestrates scraping + analytics.
- **Data layer**: SQLite (`tenders.db`) persists tender records (and is created/seeded on startup).

- **User → SPA → REST API → DB**
- Plus the **data ingestion path**: backend **scrapes an external government portal**, parses/cleans, and writes to SQLite, with **sample-data fallback** when scraping fails.

##### Backend (`backend/`)
- `main.py`: FastAPI app + **API endpoints** + **startup behavior** (creates DB, scrapes, loads).
- `database.py`: SQLite connection + CRUD/query helpers (data access layer).
- `models.py`: data models (likely Pydantic + schema mapping).
- `scraper.py`: integration with **Central Public Procurement Portal** via Requests + BeautifulSoup; parsing/cleaning logic; dedupe.
- `analytics.py`: aggregation/statistics queries (ministry/category/state/type distributions).

##### Frontend (`frontend/`)
- `src/api.ts`: Axios client (defines how SPA calls backend).
- `src/pages/*`: route-level screens (Dashboard, TenderExplorer, TenderDetail, ClosingSoon, Landing).
- `src/components/*`: UI building blocks (StatCard, TenderTable, Layout, Header).
- `src/config.ts`: environment-driven API base URL (e.g., `VITE_API_URL`).

##### Top-level
- `requirements.txt`: backend dependencies.
- `start.sh`, `start.bat`: local run scripts; implies “single-machine dev” deployment.

Goal: show *what talks to what*, including the external portal.

**Nodes to include**
- **User (Browser)**
- **React SPA (Vite dev server / static hosting)**
- **FastAPI service (Uvicorn)**
- **SQLite database file (`tenders.db`)**
- **External website**: Central Public Procurement Portal (eprocure.gov.in)

- Browser → React SPA (HTTP)
- React SPA → FastAPI (REST/JSON)
- FastAPI ↔ SQLite (SQL queries)
- FastAPI → eprocure.gov.in (HTTP GET for scraping)
- (Optional) FastAPI → “Sample Data Generator” (internal fallback path when scrape fails)

Goal: show internal layering and data flow.

**Components**
- `main.py` (API layer / routing + startup lifecycle)
- `scraper.py` (ingestion + parsing)
- `database.py` (repository/data access)
- `analytics.py` (read-only aggregations)
- `models.py` (schemas/entities)

##### Startup ingestion
- `main.py` (startup event) → `scraper.py` (fetch + parse) → `database.py` (insert/skip duplicates) → SQLite

##### Tender Explorer / list
- React `/tenders` call → `main.py` endpoint → `database.py` query (filters/pagination) → SQLite → JSON response

##### Tender detail
- React `/tenders/{id}` → `main.py` → `database.py` → SQLite

##### Closing soon
- React `/tenders/closing-soon?days=N` → `main.py` → `database.py` date-filter query → SQLite

##### Analytics
- React `/analytics*` → `main.py` → `analytics.py` → `database.py`/direct SQL → SQLite → aggregated JSON

**Notable pattern to label**
- A clean **API layer → service/logic (scraper/analytics) → data access (database.py) → SQLite** separation.

Goal: show routing + API client + major UI composition.

**Components**
- `App.tsx` (routes/layout)
- Pages:
- `Dashboard.tsx` (stats + charts)
- `TenderExplorer.tsx` (search/filter/pagination table)
- `TenderDetail.tsx` (single tender view)
- `ClosingSoon.tsx` (deadline buckets/urgency)
- `Landing.tsx`
- Shared components:
- `Layout.tsx`, `Header.tsx`
- `StatCard.tsx`, `TenderTable.tsx`
- `api.ts` (Axios wrapper)
- `config.ts` (API base URL / env)

**Edges**
- Pages → `api.ts` (fetch data)
- `api.ts` → FastAPI endpoints (REST)
- Pages → Components (composition)

##### Runtime (user-driven)
- Browser → React (UI navigation)
- React → FastAPI (`GET /tenders`, `/tenders/{id}`, `/tenders/closing-soon`, `/analytics*`, `/distinct/*`)
- FastAPI → SQLite (read-heavy queries)

##### Ingestion (backend-driven)
- FastAPI (startup) → External portal (HTTP scrape)
- FastAPI → SQLite (insert/update)
- If scrape fails: FastAPI → Sample data → SQLite

- “HTTP/JSON”
- “SQL”
- “HTTP GET + HTML parsing”

##### Important architectural patterns / principles present here
- **3-tier architecture** (SPA ↔ API ↔ DB).
- **Backend “ETL-lite”**: scrape → parse/clean → persist.
- **Read-optimized analytics**: aggregation endpoints built on DB queries.
- **Hackathon-ready single-node deployment**: everything runs locally without orchestration.

##### Technologies to label on components (keep it factual & visible)
- React 18, TypeScript, Vite
- TailwindCSS
- Axios (API client)
- Recharts (visualization)
- React Router (page routing)

- Python 3.9+
- FastAPI + Uvicorn
- Requests + BeautifulSoup4 (scraping)
- SQLite (file DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram A: Context / Container (3-tier + ingestion)
%% =========================
subgraph A["A) System Context / Containers (3-tier + ingestion)"]
direction TB

U["User (Browser)"]:::external

subgraph FE["Frontend: React SPA (Vite + TS + Tailwind)"]
direction TB
FE_App["Routing Shell (React Router)\nApp.tsx"]:::frontend
FE_Main["Bootstrap / Mount\nmain.tsx"]:::frontend
FE_Pages["Pages\n(Dashboard, Explorer, Detail, ClosingSoon, Landing)"]:::frontend
FE_Components["Shared UI Components\n(Layout, Header, StatCard, TenderTable)"]:::frontend
FE_Api["API Client (Axios)\napi.ts"]:::frontend
FE_Config["Env Config\nconfig.ts (VITE_API_URL)"]:::config
end

subgraph BE["Backend: FastAPI Service (Uvicorn)"]
direction TB
BE_Main["FastAPI App\nAPI + Startup Lifecycle\nmain.py"]:::backend
BE_OpenAPI["OpenAPI / Swagger UI\n/docs"]:::backend
end

DB[("SQLite Database\n`tenders.db`")]:::db
EXT["Central Public Procurement Portal\n(eprocure.gov.in)"]:::external
SAMPLE["Sample Data Fallback\n(internal generator)"]:::internal

U -->|"HTTP: UI navigation"| FE_App
FE_Main -->|"mounts"| FE_App
FE_App -->|"routes"| FE_Pages
FE_Pages -->|"composes"| FE_Components
FE_Pages -->|"HTTP/JSON (REST)"| FE_Api
FE_Config -->|"baseURL"| FE_Api
FE_Api -->|"GET /tenders\nGET /tenders/{id}\nGET /tenders/closing-soon\nGET /analytics*\nGET /distinct/*"| BE_Main
BE_Main -->|"serves"| BE_OpenAPI

BE_Main <-->|"SQL (read/write)"| DB

BE_Main -->|"startup: HTTP GET + HTML parsing"| EXT
BE_Main -->|"startup: persist tenders"| DB
BE_Main -.->|"if scrape fails"| SAMPLE
SAMPLE -.->|"seed sample tenders"| DB
end

%% =========================
%% Diagram B: Backend Component Diagram (inside FastAPI)
%% =========================
subgraph B["B) Backend Components (FastAPI internals)"]
direction TB

BE2_Main["API Layer + Startup\nmain.py"]:::backend
BE2_Models["Schemas / Entities\nmodels.py"]:::model

subgraph BE2_Logic["Service / Logic Layer"]
direction TB
BE2_Scraper["Scraper Subsystem\nRequests + BeautifulSoup\nscraper.py"]:::logic
BE2_Analytics["Analytics Subsystem\nAggregations / Stats\nanalytics.py"]:::logic
BE2_Sample["Sample Data Fallback\n(seed path)"]:::internal
end

BE2_DAL["Data Access Layer\nSQLite connection + CRUD\n(database.py)"]:::dal
DB2[("SQLite File DB\n`tenders.db`")]:::db
EXT2["eprocure.gov.in\n(HTML pages)"]:::external

subgraph BE2_Tests["Dev/Validation (optional runtime)"]
direction TB
T1["test_scrape.py"]:::test
T2["test_soup.py"]:::test
end

%% Startup ingestion flow
BE2_Main -->|"startup event"| BE2_Scraper
BE2_Scraper -->|"HTTP GET + parse/clean/dedupe"| EXT2
BE2_Scraper -->|"normalized tender records"| BE2_DAL
BE2_DAL -->|"INSERT/UPSERT + dedupe"| DB2
BE2_Scraper -.->|"on error"| BE2_Sample
BE2_Sample -.->|"seed records"| BE2_DAL

%% Runtime API flows
BE2_Main -->|"GET /tenders\nfilters + pagination"| BE2_DAL
BE2_Main -->|"GET /tenders/{id}"| BE2_DAL
BE2_Main -->|"GET /tenders/closing-soon?days=N"| BE2_DAL
BE2_Main -->|"GET /analytics* (aggregations)"| BE2_Analytics
BE2_Analytics -->|"read queries"| BE2_DAL
BE2_DAL -->|"SELECT/WHERE/ORDER BY"| DB2

%% Models usage
BE2_Main -->|"request/response schemas"| BE2_Models
BE2_Scraper -->|"record shaping"| BE2_Models
BE2_Analytics -->|"output schema"| BE2_Models
BE2_DAL -->|"row mapping"| BE2_Models

%% Tests validate scraper/parsing
T1 -->|"validates ingestion"| BE2_Scraper
T2 -->|"validates soup parsing"| BE2_Scraper
end

%% =========================
%% Diagram C: Frontend Component Diagram (inside React SPA)
%% =========================
subgraph C["C) Frontend Components (React SPA internals)"]
direction TB

FE3_Main["Bootstrap\nmain.tsx"]:::frontend
FE3_App["App Shell + Routes\nApp.tsx"]:::frontend

subgraph FE3_Pages["Pages (React Router routes)"]
direction TB
P_Landing["Landing.tsx"]:::frontend
P_Dash["Dashboard.tsx\nCharts: Recharts"]:::frontend
P_Explore["TenderExplorer.tsx\nSearch/Filter/Paginate"]:::frontend
P_Detail["TenderDetail.tsx\nSingle tender view"]:::frontend
P_Closing["ClosingSoon.tsx\nDeadline buckets"]:::frontend
end

subgraph FE3_Components["Shared Components"]
direction TB
C_Layout["Layout.tsx"]:::frontend
C_Header["Header.tsx"]:::frontend
C_Stat["StatCard.tsx"]:::frontend
C_Table["TenderTable.tsx"]:::frontend
end

FE3_Api["Axios Wrapper\napi.ts"]:::frontend
FE3_Config["Env Config\nconfig.ts (VITE_API_URL)"]:::config

BE3["FastAPI REST API"]:::backend

%% Composition / routing
FE3_Main -->|"mounts"| FE3_App
FE3_App -->|"route: /"| P_Landing
FE3_App -->|"route: /dashboard"| P_Dash
FE3_App -->|"route: /tenders"| P_Explore
FE3_App -->|"route: /tenders/:id"| P_Detail
FE3_App -->|"route: /closing-soon"| P_Closing

%% UI composition
FE3_App -->|"wraps"| C_Layout
C_Layout -->|"includes"| C_Header
P_Dash -->|"uses"| C_Stat
P_Dash -->|"uses"| C_Table
P_Explore -->|"uses"| C_Table
P_Detail -->|"uses"| C_Layout
P_Closing -->|"uses"| C_Table

%% Data fetching
FE3_Config -->|"baseURL"| FE3_Api
P_Dash -->|"fetch stats"| FE3_Api
P_Explore -->|"fetch tenders"| FE3_Api
P_Detail -->|"fetch tender"| FE3_Api
P_Closing -->|"fetch closing soon"| FE3_Api
FE3_Api -->|"HTTP/JSON\nGET /tenders\nGET /tenders/{id}\nGET /tenders/closing-soon\nGET /analytics*"| BE3
end

%% =========================
%% Legend (colors + arrow styles)
%% =========================
subgraph L["Legend"]
direction TB
L1["Blue: Runtime services (Frontend/Backend)"]:::frontend
L2["Purple: Internal backend modules"]:::logic
L3["Teal: Data access layer"]:::dal
L4["Gray cylinder: Database"]:::db
L5["Orange: External dependency"]:::external
L6["Dashed: Fallback / optional path"]:::internal
L7["Light: Tests (dev)"]:::test
end

%% =========================
%% Click events (component mapping)
%% =========================
click BE_Main "https://github.com/mrnk2107/procurewatch/blob/main/backend/main.py"
click BE2_Main "https://github.com/mrnk2107/procurewatch/blob/main/backend/main.py"
click BE2_DAL "https://github.com/mrnk2107/procurewatch/blob/main/backend/database.py"
click BE2_Models "https://github.com/mrnk2107/procurewatch/blob/main/backend/models.py"
click BE2_Scraper "https://github.com/mrnk2107/procurewatch/blob/main/backend/scraper.py"
click BE2_Analytics "https://github.com/mrnk2107/procurewatch/blob/main/backend/analytics.py"
click T1 "https://github.com/mrnk2107/procurewatch/blob/main/backend/test_scrape.py"
click T2 "https://github.com/mrnk2107/procurewatch/blob/main/backend/test_soup.py"

click FE_App "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/App.tsx"
click FE3_App "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/App.tsx"
click FE_Main "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/main.tsx"
click FE3_Main "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/main.tsx"
click FE_Api "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/api.ts"
click FE3_Api "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/api.ts"
click FE_Config "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/config.ts"
click FE3_Config "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/config.ts"

click FE_Pages "https://github.com/mrnk2107/procurewatch/tree/main/frontend/src/pages/"
click FE3_Pages "https://github.com/mrnk2107/procurewatch/tree/main/frontend/src/pages/"
click P_Dash "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/pages/Dashboard.tsx"
click P_Explore "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/pages/TenderExplorer.tsx"
click P_Detail "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/pages/TenderDetail.tsx"
click P_Closing "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/pages/ClosingSoon.tsx"
click P_Landing "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/pages/Landing.tsx"

click FE_Components "https://github.com/mrnk2107/procurewatch/tree/main/frontend/src/components/"
click FE3_Components "https://github.com/mrnk2107/procurewatch/tree/main/frontend/src/components/"
click C_Layout "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/components/Layout.tsx"
click C_Header "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/components/Header.tsx"
click C_Stat "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/components/StatCard.tsx"
click C_Table "https://github.com/mrnk2107/procurewatch/blob/main/frontend/src/components/TenderTable.tsx"

click L2 "https://github.com/mrnk2107/procurewatch/blob/main/requirements.txt"
click L6 "https://github.com/mrnk2107/procurewatch/blob/main/start.sh"
click L7 "https://github.com/mrnk2107/procurewatch/blob/main/start.bat"

%% =========================
%% Styles
%% =========================
classDef frontend fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0f172a
classDef backend fill:#bfdbfe,stroke:#1e3a8a,stroke-width:1.5px,color:#0f172a
classDef logic fill:#f3e8ff,stroke:#7c3aed,stroke-width:1.5px,color:#0f172a
classDef dal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#0f172a
classDef db fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
classDef external fill:#ffedd5,stroke:#c2410c,stroke-width:1.5px,color:#111827
classDef config fill:#dcfce7,stroke:#15803d,stroke-width:1.5px,color:#052e16
classDef internal fill:#fde2e2,stroke:#b91c1c,stroke-width:1.5px,color:#111827,stroke-dasharray: 5 3
classDef test fill:#f1f5f9,stroke:#64748b,stroke-width:1.2px,color:#0f172a,stroke-dasharray: 3 3
```
