🏷️ Project Title

AI-Driven Quotation Microservice (FastAPI + Decimal Finance Engine + Bilingual AI Email Generator)

🧩 Project Overview

This project is a production-grade quotation computation and communication microservice designed for B2B sales, procurement, and CRM automation systems. It accepts structured quotation requests via a REST API, performs precise financial calculations using decimal-safe arithmetic, and generates professional bilingual (English & Arabic) quotation emails through a controlled AI abstraction layer.

The service is built using FastAPI and Pydantic, making it fully OpenAPI compliant, strongly typed, and enterprise-ready for integration with CRMs, ERP systems, and sales automation pipelines.

📑 Table of Contents

• 🏷️ Project Title
• 🧾 Executive Summary
• 📑 Table of Contents
• 🧩 Project Overview
• 🎯 Objectives & Goals
• ✅ Acceptance Criteria
• 💻 Prerequisites
• ⚙️ Installation & Setup
• 🔗 API Documentation
• 🖥️ UI / Frontend
• 🔢 Status Codes
• 🚀 Features
• 🧱 Tech Stack & Architecture
• 🛠️ Workflow & Implementation
• 🧪 Testing & Validation
• 🔍 Validation Summary
• 🧰 Verification Testing Tools
• 🧯 Troubleshooting & Debugging
• 🔒 Security & Secrets
• ☁️ Deployment
• ⚡ Quick-Start Cheat Sheet
• 🧾 Usage Notes
• 🧠 Performance & Optimization
• 🌟 Enhancements & Features
• 🧩 Maintenance & Future Work
• 🏆 Key Achievements
• 🧮 High-Level Architecture
• 🗂️ Project Structure
• 🧭 How to Demonstrate Live
• 💡 Summary, Closure & Compliance

🧩 Project Overview

This system exposes a REST API endpoint POST /quote that accepts a structured quotation request containing customer details and line items. It performs decimal-safe pricing calculations, applies taxes, computes totals, and generates bilingual professional email drafts using a deterministic mock AI layer.

🎯 Objectives & Goals

• Provide accurate financial calculations using decimal arithmetic
• Generate professional quotation emails in English and Arabic
• Expose a clean OpenAPI-compliant REST interface
• Ensure validation, testing, and containerized deployment
• Enable enterprise-ready extensibility for real LLM integration

✅ Acceptance Criteria

Criteria	Description
API Validity	POST /quote must accept and validate structured JSON
Accuracy	All totals must be decimal-safe and reproducible
Emails	Both English and Arabic drafts must be generated
Testing	All pytest tests must pass
Docs	Swagger docs must be available at /docs

💻 Prerequisites

• Python 3.11+
• pip
• Docker (optional)
• Postman or curl

⚙️ Installation & Setup

• Create virtual environment
• Install dependencies from requirements.txt
• Run uvicorn app.main:app
• Access http://127.0.0.1:8000/docs

🔗 API Documentation

Method	Endpoint	Description
POST	/quote	Accepts quotation JSON, returns totals and bilingual email drafts

🖥️ UI / Frontend

This microservice is API-first and UI-agnostic. The interactive Swagger UI at /docs serves as the reference interface for clients and testers.

🔢 Status Codes

Code	Meaning
200	Quotation generated successfully
422	Invalid input schema
500	Internal processing error

🚀 Features

• Decimal-Safe Financial Engine – Eliminates floating-point rounding errors for real-world pricing and taxation.
• Multi-Item Quotation Processing – Supports unlimited line items with quantity, unit price, and tax.
• Bilingual AI Communication Layer – Generates English and Arabic quotation emails using a deterministic AI engine.
• Enterprise-Grade API Validation – Uses Pydantic schemas to enforce strict data integrity.
• OpenAPI / Swagger Interface – Automatically generated interactive API documentation.
• Mock LLM Abstraction – Allows safe offline testing while keeping architecture ready for real OpenAI or Claude.
• Dockerized Microservice – Portable deployment across cloud, on-premise, or CI/CD pipelines.
• Automated Testing Suite – Financial correctness verified using Pytest.

🧱 Tech Stack & Architecture

Layer	Technology	Purpose
API Layer	FastAPI	High-performance REST API and OpenAPI generation
Validation	Pydantic	Strong typing, schema enforcement, email validation
Finance Engine	Decimal	Accurate currency and tax calculations
AI Layer	Mock LLM	Bilingual email generation engine
Testing	Pytest	Business logic verification
Deployment	Docker	Containerized execution

Client
  |
  | POST /quote
  v
FastAPI Gateway
  |
  v
Pydantic Validation
  |
  v
Financial Engine (Decimal)
  |
  v
AI Draft Generator (Mock LLM)
  |
  v
Structured JSON Response

🛠️ Workflow & Implementation

1. Client submits a quotation request with customer data and line items.
2. FastAPI validates all inputs using Pydantic models.
3. Each line item is processed using Decimal arithmetic to compute taxed totals.
4. The grand total is calculated from all validated line totals.
5. The Mock LLM engine generates professional quotation emails in English and Arabic.
6. The API returns a structured JSON response containing totals and both email drafts.

🧪 Testing & Validation

ID	Area	Command	Expected Output	Explanation
T1	Math	pytest	Pass	Verifies line and grand totals
T2	API	POST /quote	200	Validates full pipeline

🔍 Validation Summary

All inputs are validated using Pydantic and all arithmetic uses Decimal to prevent rounding errors.

🧰 Verification Testing Tools & Command Examples

• pytest
• curl
• FastAPI Swagger UI

🧯 Troubleshooting & Debugging

• 422 Unprocessable Entity – Input JSON does not match Pydantic schema (email format, missing fields, wrong types).
• 500 Internal Server Error – Logic or AI layer failure; check Uvicorn logs.
• Incorrect totals – Indicates Decimal conversion issue or invalid numeric input.
• Swagger not loading – Ensure FastAPI is running on port 8000 and no firewall is blocking it.

🔒 Security & Secrets

No API keys are required. The Mock LLM ensures zero data leakage and full offline execution.

☁️ Deployment

The microservice is containerized using Docker and can be deployed to any cloud or on-premise infrastructure including AWS ECS, Azure Container Apps, GCP Cloud Run, or a private VPS.

• Stateless microservice – horizontally scalable
• No external API dependencies in Mock LLM mode
• Ready for CI/CD pipelines

⚡ Quick-Start Cheat Sheet

• Install → Run → Open /docs → Send POST /quote

🧾 Usage Notes

Clients must submit valid email addresses and numeric prices. Currency precision is preserved via Decimal.

🧠 Performance & Optimization

• FastAPI provides asynchronous request handling.
• Decimal ensures correctness over raw float performance.
• Stateless design allows horizontal scaling.
• Docker image is lightweight (Python slim base).

🌟 Enhancements & Features

• Replace Mock LLM with OpenAI or Claude
• Add PDF quotation generation
• CRM integration

🧩 Maintenance & Future Work

• Add database persistence
• Add authentication
• Add async LLM support

🏆 Key Achievements

• Built a finance-grade pricing engine using Decimal.
• Implemented bilingual AI-driven business communication.
• Delivered a fully documented OpenAPI microservice.
• Packaged the entire system for cloud deployment.

🧮 High-Level Architecture

The Quotation Microservice is designed as a clean, stateless, API-driven financial and AI communication engine. It follows a layered microservice architecture that separates input validation, business logic, and AI-based content generation, ensuring scalability, security, and auditability.

🔹 Architectural Layers

Layer	Responsibility	Key Components
Client Layer	Submits quotation requests	Postman, CRM, Web App, Swagger UI
API Gateway	Request routing & validation	FastAPI
Validation Layer	Schema & data integrity enforcement	Pydantic Models
Business Logic Layer	Financial computation engine	logic.py (Decimal pricing)
AI Communication Layer	Bilingual email generation	mock_llm.py
Response Layer	Structured JSON output	FastAPI Serializer

🔹 High-Level System Flow

┌──────────────────────┐
│  Client Applications │
│ (CRM, Swagger, API)  │
└───────────┬──────────┘
            │  POST /quote (JSON)
            ▼
┌───────────────────────────┐
│       FastAPI API          │
│   app.main : /quote        │
└───────────┬───────────────┘
            │
            ▼
┌───────────────────────────┐
│     Pydantic Validation   │
│  Email, Items, Price, Tax │
└───────────┬───────────────┘
            │ Validated Data
            ▼
┌───────────────────────────┐
│  Financial Engine         │
│  logic.py (Decimal Math)  │
│  - Line Totals            │
│  - Tax Calculation        │
│  - Grand Total            │
└───────────┬───────────────┘
            │ Calculated Quote
            ▼
┌───────────────────────────┐
│   AI Communication Layer  │
│  mock_llm.py              │
│  - English Email          │
│  - Arabic Email           │
└───────────┬───────────────┘
            │
            ▼
┌───────────────────────────┐
│   Structured API Response │
│  Totals + Email Drafts    │
└───────────┬───────────────┘
            │
            ▼
┌──────────────────────┐
│     Client Receives  │
│   Final Quotation    │
└──────────────────────┘

🔹 Why This Architecture Is Enterprise-Grade

• Stateless microservice – horizontally scalable
• Strict data validation before any computation
• Financial-grade decimal arithmetic
• AI layer isolated for safe testing and future LLM integration
• API-first design for CRM, ERP, and SaaS integrations
• Container-ready for cloud deployment

🗂️ Project Structure

Quotation Microservice/
│
├─ app/
│   ├─ main.py
│   ├─ models.py
│   ├─ logic.py
│   └─ mock_llm.py
│
├─ tests/
│   └─ test_quote.py
│
├─ Dockerfile
├─ requirements.txt
├─ README.md
└─ technical_project_detail.pdf

🧭 How to Demonstrate Live

• Run uvicorn
• Open /docs
• Submit POST /quote
• Show totals + bilingual email output

💡 Summary, Closure & Compliance

This project demonstrates enterprise-grade API engineering, financial computation accuracy, and AI-assisted business communication in a single microservice. It is compliant with modern backend standards including OpenAPI, containerization, test automation, and clean architecture, making it suitable for production, SaaS platforms, and CRM-driven sales automation.