Beckn EV Charging Aggregator

A Beckn-compatible EV charging aggregator (BAP).

It focuses on a real, understandable foundation instead of speculative complexity:

• FastAPI backend for booking orchestration
• Beckn-style protocol endpoints for search, select, init, and confirm
• split discovery and transactional adapters for real charger data integration
• SQLite-backed session and transaction persistence for local development
• React web client scaffold for the first customer-facing flow
• project documentation, status logs, and GitHub collaboration assets

Product Goal

Build one focused product:

Web App
  -> BAP Backend
  -> Beckn / Provider Adapter Layer
  -> EV Charging Providers

The backend is the core product. The frontend demonstrates the flow and provides a clean operator and customer starting point.

Current MVP Scope

• Search EV chargers by location
• Ask for browser location in the web app
• Discover nearby chargers from configured live data sources
• Sort by nearest or cheapest
• Label chargers as Bookable or Discovery only
• Select a bookable charger and get a price estimate
• Initialize a booking session
• Confirm the booking with a simple UPI-intent style payment flow
• View booking history per user
• Expose Beckn-style endpoints for protocol-aligned flows

Repository Layout

.
├── .github/                  # CI and collaboration templates
├── apps/
│   ├── backend/              # FastAPI BAP server
│   └── web/                  # React web client
├── docs/                     # Architecture, roadmap, status updates
├── CHANGELOG.md
├── CONTRIBUTING.md
└── README.md

Quick Start

Backend

cd apps/backend
python -m venv .venv
.venv\Scripts\activate
pip install -e .
uvicorn app.main:app --reload

Frontend

cd apps/web
npm install
npm run dev

The frontend expects the backend at http://127.0.0.1:8000 by default.

Live Data Configuration

Add one or more of these variables in apps/backend/.env:

• EV_BAP_OPEN_CHARGE_MAP_API_KEY
• EV_BAP_GOOGLE_PLACES_API_KEY
• EV_BAP_MAPPLS_ACCESS_TOKEN

Optional:

• EV_BAP_ENABLE_DEMO_TRANSACTIONAL_PROVIDER=true

If no transactional provider is enabled, the app can still discover nearby chargers but marks them as Discovery only.

Documentation Map

• Architecture
• API Contracts
• Roadmap
• Integrations
• Status Process
• Status Log: Bootstrap
• Contribution Guide

Delivery Principles

• Keep provider integrations behind a stable adapter contract
• Keep frontend APIs simple and app-facing
• Persist protocol correlation data for debugging and supportability
• Prefer small, shippable increments with visible status updates
• Treat documentation as part of the product, not an afterthought

What Comes Next

1. Add a real Beckn gateway client instead of the local transactional demo path.
2. Add callback handling for on_search, on_select, on_init, and on_confirm.
3. Replace the demo transactional provider with a live UEI / BPP or direct network integration.
4. Add map rendering with Mapbox or Google Maps.
5. Add deployment automation and environment-specific configuration.