# kalradev/bid-intelligence architecture

> Architecture diagram of the GitHub repository kalradev/bid-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kalradev/bid-intelligence
- Repository: https://github.com/kalradev/bid-intelligence

## Overview

##### Project Type and Purpose
- This is a full-stack web application for intelligent RFP (Request for Proposal) management and analysis.
- Frontend: React + TypeScript SPA (bootstrapped with Vite), multiple pages (Upload, Analysis, Bid Management, etc.).
- Backend: Node.js + Express API server with controllers, middleware, and service modules (document extraction, OpenAI integration).
- Key features: file upload, document text extraction, AI-powered analysis via OpenAI, results presentation.

##### File Structure Analysis
- Top level:
- Backend/
– server.js (Express entry point)
– routes/rfpRoutes.js (defines REST endpoints)
– controllers/rfpController.js (orchestrates request handling)
– middleware/ (error handling, file upload)
– services/ (documentExtractor, openaiService)
– .env.example (configuration for DB, OpenAI keys)
- Frontend/
– public/index.html
– src/ (React components, pages, context, assets, types)
– vite.config.ts, tsconfig*.json (build and compiler configs)
– pages/ (LandingPage, UploadPage, AnalysisPage, etc.)
– context/AnalysisContext.tsx (state management)
– data/mockAnalysisData.ts (stubbed data for development)

a. Frontend Layer
- Browser / User Interface (React SPA)
- Components & Pages connect via React Router
- State & Context (AnalysisContext)
b. Backend Layer
- API Gateway (Express server)
- Authentication & Middleware (uploadMiddleware, errorHandler)
- Controller Layer (rfpController)
- Service Layer
- documentExtractor (parses uploaded files)
- openaiService (calls OpenAI API for analysis)
- Data Storage (Database for RFP records, analysis results)
- File Storage (local disk or S3 for uploaded documents)
c. External Services
- OpenAI API
- (Optional) Cloud Storage (AWS S3 or equivalent)
- (Optional) Authentication provider / OAuth

##### Relationships and Data Flow
1. User uploads document via Frontend UploadPage.
2. Frontend sends HTTP POST (/api/rfp/upload) with file payload.
3. Express uploadMiddleware stores file; routes to rfpController.upload.
4. rfpController invokes documentExtractor → extracts text/content.
5. Extracted text passed to openaiService → calls OpenAI API.
6. AI analysis result saved to Database (and/or sent back immediately).
7. Frontend polls or receives result → renders on AnalysisPage and other pages.
8. Frontend navigates through BidManagement, CostEstimation, etc., using stored analysis.

##### Architectural Patterns and Principles
- Layered architecture: separate concerns (API layer, controllers, services, data).
- Modular services: each service has single responsibility (extraction, AI call).
- Middleware pattern in Express for cross-cutting concerns (error handling, uploads).
- Component-based UI and context API in React for state management.
- Configuration via environment variables (.env).

- Annotations noting key environment variables, config files, and tech stack (Vite, React, Express, Node.js, OpenAI).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        User["User"]:::external
        ReactSPA["React SPA"]:::frontend
        UploadPage["UploadPage"]:::frontend
        AnalysisPage["AnalysisPage"]:::frontend
        BidManagementPage["BidManagementPage"]:::frontend
        CostEstimationPage["CostEstimationPage"]:::frontend
        OtherPages["Other Feature Pages"]:::frontend
        Navbar["Navbar & Header"]:::frontend
        FeatureComponents["UI Cards & Layout"]:::frontend
        AnalysisContext["AnalysisContext"]:::frontend
        MockData["mockAnalysisData"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        ExpressServer["Express API Server"]:::backend
        uploadMiddleware["uploadMiddleware"]:::backend
        errorHandler["errorHandler"]:::backend
        rfpRoutes["rfpRoutes"]:::backend
        rfpController["rfpController"]:::backend
        documentExtractor["documentExtractor Service"]:::backend
        openaiService["openaiService"]:::backend
        EnvConfig[".env.example"]:::backend
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        Database["Database"]:::storage
        FileStorage["File Storage"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAIAPI["OpenAI API"]:::external
        CloudStorage["Cloud Storage (S3)"]:::external
        AuthProvider["Auth Provider / OAuth"]:::external
    end

    %% Flow
    User -->|interacts with| ReactSPA
    ReactSPA -->|navigates to| UploadPage
    ReactSPA -->|navigates to| AnalysisPage
    ReactSPA -->|navigates to| BidManagementPage
    ReactSPA -->|navigates to| CostEstimationPage
    ReactSPA -->|navigates to| OtherPages
    ReactSPA -->|uses| Navbar
    ReactSPA -->|uses| FeatureComponents
    ReactSPA -->|uses| AnalysisContext
    ReactSPA -->|uses| MockData

    UploadPage -->|POST /api/rfp/upload| ExpressServer
    ExpressServer --> uploadMiddleware
    uploadMiddleware --> rfpController
    ExpressServer --> rfpRoutes
    rfpRoutes --> rfpController
    rfpController --> documentExtractor
    documentExtractor --> openaiService
    openaiService -->|API call| OpenAIAPI
    openaiService -->|store results| Database
    rfpController -->|save file| FileStorage
    rfpController -->|save record| Database
    rfpController -->|response| ReactSPA
    AnalysisPage -->|fetch results| ExpressServer

    %% Optional flows
    ExpressServer --> errorHandler

    %% Click Events
    click ReactSPA "https://github.com/kalradev/bid-intelligence/tree/main/Frontend/src"
    click User "https://github.com/kalradev/bid-intelligence/tree/main/Frontend/src"
    click UploadPage "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/pages/UploadPage.tsx"
    click AnalysisPage "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/pages/AnalysisPage.tsx"
    click BidManagementPage "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/pages/BidManagement.jsx"
    click CostEstimationPage "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/pages/CostEstimationPage.jsx"
    click OtherPages "https://github.com/kalradev/bid-intelligence/tree/main/Frontend/src/pages"
    click Navbar "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/components/Navbar.tsx"
    click FeatureComponents "https://github.com/kalradev/bid-intelligence/tree/main/Frontend/src/components"
    click AnalysisContext "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/context/AnalysisContext.tsx"
    click MockData "https://github.com/kalradev/bid-intelligence/blob/main/Frontend/src/data/mockAnalysisData.ts"
    click ExpressServer "https://github.com/kalradev/bid-intelligence/blob/main/Backend/server.js"
    click rfpRoutes "https://github.com/kalradev/bid-intelligence/blob/main/Backend/routes/rfpRoutes.js"
    click rfpController "https://github.com/kalradev/bid-intelligence/blob/main/Backend/controllers/rfpController.js"
    click uploadMiddleware "https://github.com/kalradev/bid-intelligence/blob/main/Backend/middleware/uploadMiddleware.js"
    click errorHandler "https://github.com/kalradev/bid-intelligence/blob/main/Backend/middleware/errorHandler.js"
    click documentExtractor "https://github.com/kalradev/bid-intelligence/blob/main/Backend/services/documentExtractor.js"
    click openaiService "https://github.com/kalradev/bid-intelligence/blob/main/Backend/services/openaiService.js"
    click EnvConfig "https://github.com/kalradev/bid-intelligence/blob/main/Backend/.env.example"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef external fill:#E1D5FF,stroke:#333,stroke-width:1px
```
