Aerchain RFP System

The Aerchain RFP System is an intelligent Request for Proposal (RFP) management platform designed to streamline the procurement process. It uses advanced AI to generate RFP structures from natural language, manage vendor communications, and automatically analyze and compare vendor proposals to recommend the best fit.

Prerequisites

Before starting, ensure you have the following installed:

• Python 3.10+ (for the backend)
• Node.js 18+ (for the frontend)
• PostgreSQL (running locally or a connection string)
• A Google Gemini API Key (get one from Google AI Studio)

Installation

1. Clone the Repository

git clone <repository-url>
cd AerchainProject

2. Backend Setup

Navigate to the backend directory and set up the Python environment.

cd backend
python -m venv venv

# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt

Configuration:

1. Create a .env file in the backend directory (use .env.example as reference).

2. Add your configuration values:

   # Database
   DATABASE_URL=postgresql://user:password@localhost:5432/aerchain_db
   
   # Google Gemini AI
   GOOGLE_API_KEY=your_actual_api_key_here
   
   # Email Settings (for Gmail)
   EMAIL_ADDRESS=your-email@gmail.com
   EMAIL_PASSWORD=your-app-specific-password
   IMAP_SERVER=imap.gmail.com
   SMTP_SERVER=smtp.gmail.com

3. Database Setup:

   • Ensure PostgreSQL is running
   • Create the database: createdb aerchain_db
   • Tables will be auto-created on first run

4. Email Configuration:

   • For Gmail: You must use an App Password (not your regular password)
     1. Enable 2-Factor Authentication on your Google account
     2. Go to Google Account → Security → 2-Step Verification → App passwords
     3. Generate a new app password for "Mail"
     4. Use this 16-character password as EMAIL_PASSWORD
   • Alternative Providers: Update IMAP_SERVER and SMTP_SERVER accordingly
   • Note: Email sending/receiving is implemented but may be simulated in demo environments

3. Frontend Setup

Navigate to the frontend directory and install dependencies.

cd ../frontend
npm install

Running the Application

Terminal 1: Backend

cd backend
# Activate venv if not already active
python -m uvicorn main:app --reload

The API will be available at http://localhost:8000.

Terminal 2: Frontend

cd frontend
npm run dev

The UI will be available at http://localhost:5173.

Tech Stack

Frontend

• Framework: React with Vite
  • Vite provides an extremely fast development server and build tool. React is used for its component-based architecture, making the UI modular and maintainable.
• Styling: TailwindCSS & shadcn/ui
  • Tailwind allows for rapid styling directly in markup. shadcn/ui provides high-quality, accessible, and customizable components (like Tabs, Cards, Dialogs) out of the box, ensuring a premium look and feel.
• State/Data: React Hooks & Axios
  • Simple and effective state management for the current scale of the application.

Backend

• Framework: FastAPI
  • A modern, fast (high-performance) web framework for building APIs with Python 3.6+ based on standard Python type hints. It offers automatic interactive API documentation (Swagger UI).
• Database: SQLModel (PostgreSQL)
  • SQLModel combines SQLAlchemy and Pydantic. PostgreSQL is selected for robust, production-grade relational data storage, suitable for scaling complex procurement data.
• Language: Python 3.10+

AI Integration

• Provider: Google Gemini (via google-genai SDK)
• Model: gemini-2.5-flash-lite
  • A lightweight yet capable multimodal model that excels at text analysis, structured data extraction, and comparative reasoning, making it perfect for processing complex RFP documents and proposals.

Architecture

The application follows a modern client-server architecture:

graph LR
    User[User] -->|Interacts| UI[React Frontend]
    UI -->|HTTP Requests| API[FastAPI Backend]
    API -->|Queries| DB[(PostgreSQL)]
    API -->|Prompts| AI[Gemini AI]
    AI -->|Analysis/Structure| API

Loading

1. Client: The frontend handles user interactions (creating RFPs, viewing dashboards, comparing proposals).
2. Server: The backend exposes REST endpoints to manage resources (RFPs, Vendors, Proposals).
3. AI Service: A dedicated service layer interacts with the Gemini API to perform intelligence tasks.
4. Persistence: Data is stored in a PostgreSQL database (configured via DATABASE_URL).

Project Structure

AerchainProject/
├── backend/
│   ├── routers/                # API Route Handlers
│   │   ├── rfps.py             # RFP management endpoints
│   │   ├── vendors.py          # Vendor management endpoints
│   │   └── proposals.py        # Proposal submission & analysis
│   ├── services/               # Business Logic & Integrations
│   │   └── ai_service.py       # Google Gemini AI integration
│   ├── models.py               # SQLModel Database Models
│   ├── database.py             # DB Connection & Session
│   ├── main.py                 # Application Entry Point
│   ├── config.py               # Configuration Settings
│   └── requirements.txt        # Python Dependencies
├── frontend/
│   ├── src/
│   │   ├── components/         # React UI Components
│   │   │   ├── rfp-dashboard.tsx   # Main dashboard view
│   │   │   ├── rfp-form.tsx        # RFP creation wizard
│   │   │   ├── proposal-comparison.tsx # AI comparison view
│   │   │   └── ui/             # Reusable UI components (shadcn/ui)
│   │   ├── lib/                # Utilities & Helpers
│   │   ├── App.tsx             # Main App Component
│   │   └── main.tsx            # Frontend Entry Point
│   └── package.json            # Node.js Dependencies
└── README.md                   # Project Documentation

Application Flow

1. RFP Generation:

   • User enters a rough description (e.g., "Need 50 laptops for engineering").
   • AI analyzes this text and extracts structured data (Title, Budget, Requirements).
   • User reviews, edits, and saves the RFP.

2. Vendor Communication:

   • User selects vendors to invite.
   • System "sends" emails (simulated in logs/files) to vendors.

3. Proposal Submission:

   • Vendors (or the user acting as a vendor) submit proposals.
   • AI Analysis: Upon submission, the AI immediately analyzes the proposal text against the RFP requirements, scoring it (0-100) and extracting pros/cons.

4. Comparison & Decision:

   • User selects an RFP to compare proposals.
   • AI Comparison: The AI reviews all proposals side-by-side and produces a comparison matrix and a final recommendation.

API Documentation

All API endpoints are accessible at http://localhost:8000. Interactive documentation is available at http://localhost:8000/docs (Swagger UI).

RFPs

POST /rfps/generate

Generates a structured RFP from natural language input using AI.

Request Body:

{
  "natural_language_input": "I need 20 laptops with 16GB RAM and 15 monitors for $50,000. Delivery in 30 days."
}

Response (200):

{
  "title": "Laptop and Monitor Procurement",
  "description": "Purchase of laptops and monitors for new office setup",
  "budget": 50000,
  "currency": "USD",
  "requirements": ["20x Laptops with 16GB RAM", "15x 27-inch Monitors", "Delivery within 30 days"]
}

POST /rfps/

Creates a new RFP in the database.

Request Body:

{
  "title": "Laptop Procurement",
  "description": "Need high-performance laptops for engineering team",
  "budget": 50000,
  "currency": "USD",
  "status": "DRAFT"
}

Response (200):

{
  "id": 1,
  "title": "Laptop Procurement",
  "description": "Need high-performance laptops for engineering team",
  "budget": 50000.0,
  "currency": "USD",
  "status": "DRAFT",
  "created_at": "2024-01-15T10:30:00"
}

GET /rfps/

Retrieves all RFPs.

Response (200):

[
  {
    "id": 1,
    "title": "Laptop Procurement",
    "status": "OPEN",
    "budget": 50000.0
  }
]

POST /rfps/{rfp_id}/send

Sends RFP to selected vendors via email.

Request Body:

{
  "vendor_ids": [1, 2, 3]
}

Response (200):

{
  "message": "RFP sent to 3 vendors",
  "status": "success"
}

Vendors

POST /vendors/

Registers a new vendor.

Request Body:

{
  "name": "TechSupply Co.",
  "email": "vendor@techsupply.com",
  "contact_person": "John Doe",
  "phone": "+1-555-0123"
}

Response (200):

{
  "id": 1,
  "name": "TechSupply Co.",
  "email": "vendor@techsupply.com",
  "contact_person": "John Doe",
  "phone": "+1-555-0123"
}

GET /vendors/

Lists all registered vendors.

Response (200):

[
  {
    "id": 1,
    "name": "TechSupply Co.",
    "email": "vendor@techsupply.com"
  }
]

Proposals

POST /proposals/

Submits a vendor proposal. Automatically triggers AI analysis.

Request Body:

{
  "rfp_id": 1,
  "vendor_id": 1,
  "raw_response": "We can provide 20 Dell XPS laptops at $1200 each and 15 Dell monitors at $300 each. Total: $28,500. Delivery in 21 days with 2-year warranty."
}

Response (200):

{
  "id": 1,
  "rfp_id": 1,
  "vendor_id": 1,
  "raw_response": "We can provide...",
  "ai_score": 85,
  "ai_rationale": "Meets requirements with competitive pricing and faster delivery",
  "extracted_data": "{\"pros\": [\"Competitive price\", \"Fast delivery\"], \"cons\": []}"
}

POST /proposals/compare/{rfp_id}

Compares all proposals for an RFP using AI analysis.

Response (200):

{
  "recommendation": "Vendor TechSupply Co. offers the best value with competitive pricing and reliable delivery timeline.",
  "best_vendor_id": 1,
  "comparison_matrix": [
    {
      "vendor_name": "TechSupply Co.",
      "score": 85,
      "key_strengths": "Best price, fast delivery",
      "key_weaknesses": "None significant",
      "price_ranking": "Lowest"
    }
  ]
}

Error Responses:

All endpoints may return:

• 404 Not Found: Resource doesn't exist
• 400 Bad Request: Invalid input data
• 500 Internal Server Error: Server-side issues

Verification & Testing

Testing Strategy

We utilized a combination of manual verification and end-to-end flow testing:

1. Component Testing: Checked individual API endpoints using the auto-generated Swagger UI (http://localhost:8000/docs). This ensured that request/response schemas were correct.
2. Integration Testing: Verified the interaction between the Backend and the AI Service by inspecting logs and checking the quality of AI responses.
3. End-to-End Flow:
   • Created an RFP via the Frontend UI.
   • Simulated vendor proposals.
   • Triggered the comparison view to verify that the AI correctly synthesized the data into a recommendation.

AI Model Details

• Model: gemini-2.5-flash-lite
• Capabilities Used:
  • Entity Extraction: Parsing unstructured text into JSON.
  • Scoring: Evaluating text against criteria to assign numerical scores.
  • Summarization: Condensing long proposals into pros/cons.
  • Reasoning: Comparing multiple complex documents to find the "best" option.

Design Decisions & Assumptions

Technology Choices

FastAPI over Node.js/Express

• Chosen for superior type safety with Pydantic models and automatic API documentation
• Built-in async support perfectly suited for AI API calls and email operations
• SQLModel integration provides seamless ORM with type checking

React + Vite over Other Frameworks

• Vite offers significantly faster development experience compared to Create React App
• React's ecosystem maturity and component reusability accelerate development
• TypeScript integration ensures type safety across the full stack

PostgreSQL over SQLite/MongoDB

• Relational model fits procurement workflows (RFPs → Vendors → Proposals relationships)
• ACID compliance ensures data integrity for financial/contractual data
• Production-ready scalability for enterprise adoption

Google Gemini over OpenAI/Anthropic

• gemini-2.5-flash-lite provides excellent cost-performance ratio
• Strong structured output capabilities via response_mime_type='application/json'
• Multimodal capabilities enable future expansion (PDF/image proposal handling)

Architecture Decisions

Single-Page Application (SPA) Design

• Client-side routing eliminates page reloads, providing fluid UX
• State management kept simple with React hooks (no Redux) for single-user context
• API-first design enables future mobile client development

AI Service Layer Pattern

• Isolated in services/ai_service.py for maintainability and testability
• Retry logic with exponential backoff handles rate limits gracefully
• Prompt engineering centralized for easy iteration and improvement

Email Integration Approach

• SMTP for outbound (RFP distribution)
• IMAP for inbound (proposal collection) - simulated in demo to avoid inbox complexity
• Production deployment would use webhook-based email API (SendGrid, Mailgun) for reliability

Key Assumptions

Vendor Response Format

• Assumed vendors reply via email with free-form text (no structured templates)
• AI extraction handles variability in formatting, units, and terminology
• Edge case: Attachments (PDFs, Excel) are out of scope but mentioned in limitations

Scoring & Comparison Logic

• AI-generated scores (0-100) based on requirement matching, not absolute metrics
• Comparison considers: price competitiveness, delivery timeline, warranty terms, completeness
• Final recommendation is AI-assisted but user makes ultimate decision

Single-User Context

• No authentication or multi-tenancy (simplified for MVP)
• Database can support multiple users but UI assumes single procurement manager
• Production would add role-based access control (RBAC)

RFP Lifecycle

• Statuses: DRAFT → OPEN (sent) → EVALUATING → AWARDED
• No approval workflows or versioning (single-user can create and send immediately)
• Email tracking (opens/clicks) considered nice-to-have, not implemented

Data Privacy

• Vendor emails and proposal data sent to Gemini API
• Assumes compliance with Google's data usage policies
• Production deployment requires data residency/encryption review

AI Tools & Development Approach

Tools Used

GitHub Copilot

• Usage: Code completion, boilerplate generation, and SQL query assistance
• Impact: Accelerated development of CRUD operations and API endpoints by ~30%
• Example: Generated initial SQLModel schemas and FastAPI route structures

ChatGPT/Claude

• Usage: Architecture brainstorming, prompt engineering, and debugging
• Key Prompts:
  • "Design a prompt to extract structured RFP data from natural language"
  • "How to handle rate limiting with async retry in Python?"
  • "Best practices for PostgreSQL connection pooling in FastAPI"
• Impact: Refined AI prompts to improve extraction accuracy from 60% to 90%+

Cursor (AI-Powered IDE)

• Usage: Refactoring and test case generation
• Example: Converted print statements to structured logging across codebase
• Benefit: Maintained code quality while iterating rapidly

Prompt Engineering Insights

RFP Structure Extraction

You are an expert procurement assistant. Extract a structured RFP from: "{user_input}"
Return ONLY raw JSON (no markdown) with: title, description, budget, currency, requirements.

• Key learning: Specifying "raw JSON" prevents markdown code block wrappers
• Retry logic essential due to occasional JSON parsing failures

Proposal Comparison

Compare these proposals for RFP: {rfp_context}
Proposals: {vendor_proposals}
Return JSON with: recommendation, best_vendor_id, comparison_matrix (vendor_name, score, strengths, weaknesses, price_ranking)

• Multi-document reasoning required clear structure to avoid hallucinations
• Explicit schema enforcement via response_mime_type improved consistency

What AI Tools Changed

1. Faster Iteration: Reduced boilerplate time, more focus on business logic
2. Better Error Handling: AI suggestions improved async exception handling patterns
3. Prompt Quality: Iterative refinement with AI assistance improved extraction accuracy
4. Code Quality: AI-assisted refactoring maintained consistency across modules

Known Limitations & Future Enhancements

Current Limitations

Email Handling

• IMAP integration implemented but may require manual simulation for demos
• No support for email attachments (PDFs, Excel files)
• Email thread tracking not implemented

AI Accuracy

• Extraction quality depends on vendor response clarity (typos, ambiguous wording reduce accuracy)
• No confidence scores for extracted data fields
• Comparison assumes all proposals address the same RFP scope

Scalability

• Single-threaded email processing (no background workers)
• No caching for AI responses (repeated queries re-invoke API)
• Database queries not optimized for large datasets (no pagination on list endpoints)

User Experience

• No real-time notifications (email arrival, AI processing complete)
• Limited error feedback (generic messages, no suggested remediation)
• Mobile responsiveness not optimized

Future Enhancements

Short-Term (1-2 Sprints)

1. Attachment Support: Parse PDF/Excel proposals using document AI
2. Confidence Scoring: Show extraction confidence to flag manual review needs
3. Email Templates: Pre-fill RFP emails with customizable templates
4. Audit Trail: Log all AI decisions for compliance/transparency

Medium-Term (3-6 Months) 5. Multi-User Support: Add authentication, RBAC, and team collaboration 6. Advanced Comparison: Custom weighting for criteria (price 40%, delivery 30%, etc.) 7. Vendor Portal: Self-service interface for vendors to submit proposals 8. Approval Workflows: Multi-stage RFP approval before sending

Long-Term (6+ Months) 9. Predictive Analytics: Historical data to predict vendor performance 10. Integration Hub: Connect with ERPs (SAP, Oracle), e-procurement platforms 11. Compliance Automation: Auto-check proposals against regulatory requirements 12. Mobile App: Native iOS/Android apps for on-the-go approvals

Scalability Considerations

• Database: Partition by date/region for large orgs; consider read replicas
• AI Costs: Batch processing, caching, and model fine-tuning to reduce API calls
• Email: Migrate to webhook-based providers (SendGrid, Mailgun) for reliability
• Background Jobs: Implement Celery/RQ for async email/AI processing