{"id":48348199,"url":"https://github.com/sandesh-s-hegde/b2b-fleet-aggregator-api","last_synced_at":"2026-04-05T08:03:40.918Z","repository":{"id":342873275,"uuid":"1174484109","full_name":"sandesh-s-hegde/b2b-fleet-aggregator-api","owner":"sandesh-s-hegde","description":"Headless FastAPI micro-tactical execution engine for Logistics Service Providers. Dynamically allocates warehouse floor tasks between human workers and AGVs based on physical fatigue and battery constraints.","archived":false,"fork":false,"pushed_at":"2026-03-17T11:35:35.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-18T01:40:54.553Z","etag":null,"topics":["agv","dispatch-system","fastapi","logistics","microservice","postgresql","python","rest-api","sqlalchemy","supply-chain","warehouse-management"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandesh-s-hegde.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T13:51:33.000Z","updated_at":"2026-03-17T11:35:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sandesh-s-hegde/b2b-fleet-aggregator-api","commit_stats":null,"previous_names":["sandesh-s-hegde/lsp-workforce-api","sandesh-s-hegde/b2b-fleet-aggregator-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sandesh-s-hegde/b2b-fleet-aggregator-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandesh-s-hegde%2Fb2b-fleet-aggregator-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandesh-s-hegde%2Fb2b-fleet-aggregator-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandesh-s-hegde%2Fb2b-fleet-aggregator-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandesh-s-hegde%2Fb2b-fleet-aggregator-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandesh-s-hegde","download_url":"https://codeload.github.com/sandesh-s-hegde/b2b-fleet-aggregator-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandesh-s-hegde%2Fb2b-fleet-aggregator-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31428645,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agv","dispatch-system","fastapi","logistics","microservice","postgresql","python","rest-api","sqlalchemy","supply-chain","warehouse-management"],"created_at":"2026-04-05T08:03:40.811Z","updated_at":"2026-04-05T08:03:40.896Z","avatar_url":"https://github.com/sandesh-s-hegde.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 B2B Fleet Aggregator API\n\n**Author:** Sandesh Hegde\n\n**Architecture:** Headless FastAPI Microservice (B2B Aggregator)\n\n**Status:** 🟢 Live in Production / Active Development\n\n**Live API Documentation:** [Interactive Swagger UI](https://b2b-fleet-api.onrender.com/docs) *(Note: Hosted on Render Free Tier. Please allow 30s for cold start.)*\n\n## 🎯 The Purpose: What is this?\n\nThe **B2B Fleet Aggregator API** is a high-performance middleware designed to bridge the gap between demand-side strategic planning and supply-side physical assets.\n\nWhile the [LSP Digital Capacity Twin](https://github.com/sandesh-s-hegde/digital_capacity_optimizer) serves as the **Macro-Strategic Layer** (forecasting shortfalls and volume surges), this API acts as the **Tactical Execution Engine**. It aggregates commercial vehicle availability from multiple third-party suppliers (e.g., Enterprise, Ryder, Hertz) into a unified, searchable interface for seamless capacity fulfillment.\n\n## 🧠 The Motivation: Why are we doing this?\n\nIn the travel and logistics tech sectors, the \"Integration Gap\" is a multi-million dollar problem. A strategic model might identify a need for additional vans in Europe, but the execution fails if:\n\n1. **Fragmentation:** Suppliers use different API standards, making real-time comparison impossible.\n2. **Static Data:** Availability is often outdated, leading to failed bookings and lost revenue.\n3. **Environment Impact:** Legacy systems fail to prioritize low-emission or EV options during the search phase.\n\n**This API solves the \"Macro-Micro Gap.\"** By providing a standardized, stateful microservice that tracks supplier inventory, calculates dynamic surge pricing, sorts by carbon telemetry, and manages the complete booking lifecycle, we transform theoretical capacity needs into real-world, executable bookings.\n\n## 🔮 Planned Outcomes: Where is this going?\n\nThe ultimate goal is a **Bidirectional, Closed-Loop Ecosystem**:\n\n1. **Standardized Aggregation:** Creating a single source of truth for commercial fleet inventory across multiple global suppliers.\n2. **Algorithmic Selection:** Utilizing weighted optimization (Price vs. CO2 emissions) to present the most valuable fleet options to the partner.\n3. **Real-Time Telemetry:** Once a booking is completed, the API feeds actual cost, utilization rates, and performance data back to the Digital Twin to refine future forecasting models.\n\n---\n\n## 🏗️ System Architecture\n\nThe project follows a \"Clean Architecture\" pattern to ensure high scalability and ease of integration:\n\n* `main.py`: RESTful Routing, Exception Handling, Business Logic, and OpenAPI documentation.\n* `database.py`: PostgreSQL engine management with SQLAlchemy Session Pooling.\n* `models.py`: Relational schema definitions for Vehicles, Suppliers, and Bookings.\n* `schemas.py`: Pydantic v2 data contracts for strict request/response validation.\n* `docker-compose.yml`: Infrastructure-as-Code (IaC) for rapid local database orchestration.\n* `postman_collection.json`: Automated Behavior-Driven Development (BDD) test suite.\n* `start.bat` / `stop.bat`: Windows automation scripts for one-click environment orchestration.\n\n### 📍 Core Endpoints\n\n**System \u0026 Analytics**\n* `GET /api/v1/health` - Deep system health check (API + Database Ping). *Used for automated Uptime telemetry.*\n* `GET /api/v1/fleet/utilization` - Real-time fleet utilization metrics.\n* `GET /api/v1/fleet/revenue` - Aggregates financial telemetry from confirmed B2B bookings.\n\n**Fleet Management \u0026 Aggregation**\n* `GET /api/v1/vehicles` - Live Supplier Catalog retrieval.\n* `POST /api/v1/vehicles` - Register new supplier inventory.\n* `POST /api/v1/vehicles/batch` - Ingest bulk payloads for high-volume supplier syncs.\n* `DELETE /api/v1/vehicles/{vehicle_id}` - Safely retire inventory (validates active bookings).\n* `POST /api/v1/fleet/search` - Multi-criteria search engine (Filters availability, sorts by lowest CO2 emissions and daily rate).\n\n**Stateful Booking Engine** *(Secured via API Key)*\n* `POST /api/v1/bookings` - Execute secure B2B booking with dynamic surge pricing.\n* `GET /api/v1/bookings/{partner_id}` - Retrieve active partner itineraries.\n* `PATCH /api/v1/bookings/{booking_reference}/cancel` - Cancel booking and dynamically release inventory back to the market.\n\n---\n\n## 🚀 Local Installation \u0026 Setup\n\n### 1. Clone \u0026 Environment\n\n```bash\ngit clone https://github.com/sandesh-s-hegde/b2b-fleet-aggregator-api.git\ncd b2b-fleet-aggregator-api\npython -m venv venv\n\n# Activate (Windows):\n.\\venv\\Scripts\\activate\n```\n\n### 2. Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n### 3. Environment Variables\nCopy the provided template to configure your local secure credentials:\n\n```bash\ncp .env.example .env\n```\n\n### 4. Automated Boot Sequence (Windows)\nThe project includes Developer Experience (DX) scripts to automatically orchestrate the Docker database and FastAPI server.\n\nTo boot the entire environment:\n```bash\n.\\start.bat\n```\n*Access the interactive Swagger UI at: `http://localhost:8000/docs`*\n\nTo safely spin down the infrastructure when finished:\n```bash\n.\\stop.bat\n```\n\n---\n\n## 🗺️ Development Roadmap\n\n* [x] **Phase 1: API Core.** Bootstrapped FastAPI framework with OpenAPI 3.1 docs and health telemetry.\n* [x] **Phase 2: Data Persistence.** Designed PostgreSQL schema and SQLAlchemy ORM for complex supplier relationships.\n* [x] **Phase 3: Booking Engine.** Implemented stateful lifecycle management (Search -\u003e Book -\u003e Cancel) with inventory locking.\n* [x] **Phase 4: Search Algorithm.** Engineered multi-criteria aggregation sorting by emission KPIs and pricing.\n* [x] **Phase 5: Advanced Logic.** Shipped API Key auth, dynamic surge pricing, and financial revenue endpoints.\n* [x] **Phase 6: DevOps \u0026 Governance.** Established Docker orchestration, CI/CD pipelines, Postman BDD test suites, and strict repository governance (Security \u0026 Contributor policies).\n* [ ] **Phase 7: Ecosystem Integration (EGA Loop).** Upgrading the API to act as the automated execution layer for the **Digital Capacity Optimizer**. Will ingest stochastic capacity shortfalls to trigger zero-touch fleet procurement based on visual volatility.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandesh-s-hegde%2Fb2b-fleet-aggregator-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandesh-s-hegde%2Fb2b-fleet-aggregator-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandesh-s-hegde%2Fb2b-fleet-aggregator-api/lists"}