EVOLT

EV charging intelligence — with the evidence shown.

Drivers find a charger they can rely on. Charging companies see which chargers need attention first, and why.

▶ Open the live demo

Live demo · Quick start · For judges · Features · How it works · Documentation

---

🔍 The problem

Public EV chargers are often out of service or underperforming, and drivers usually find out only on arrival. Operators collect plenty of data but still struggle to decide which charger to fix first, and to justify that decision.

💡 The solution

EVOLT turns charging data into two focused experiences built on one database:

🚗 Driver	🏢 Charging company
Find compatible chargers nearby, ranked so the ones with healthy evidence come first, and see them on a map with the best match starred	See prioritised action items, each with its evidence, the rule that fired, why it matters and the next step
Compare up to four chargers side by side; click any map pin to see the chargers at that spot	A fleet map coloured by connector health; track station performance and export the station table
	A service forecast: when each connector will reach its contact-resistance limit, with a range, from temperature-corrected readings
	Repair checks: after recorded work, whether readings returned to normal and whether the fix held
Book a slot or join the queue before setting off, with a 10-minute gap kept after every booking so a late finish never runs into the next driver; book several vehicles at once; manage bookings with a code, no account
Read a plain-English reason for every recommendation	Record decisions (reviewed / resolved / dismissed); they are stored in the database

Every number is computed from stored records. Nothing is hard-coded or shown as live telemetry, and an anomaly is always a reason to investigate, never proof of a fault.

---

🌐 Live demo

https://evolt-ev.vercel.app — no install, no sign-up.

Hosting	Vercel (functions in Singapore, sin1) + Neon PostgreSQL (Singapore)
Data loaded	13 labelled demo stations (29 chargers, 1,958 readings), the 1,000-session dataset with its trained models, and all 381 Arduino bench readings (run 2)
Browsing	Every page and every read-only API is open to anyone
Editing	Token mode: recording maintenance, setting service limits, importing data and updating action items need the admin token. Unlock it on Company → Settings; ask the project owner for the token
Health check	/api/health → {"status":"ok","database":"ok",…}

Each deploy runs the migrations and loads the data before building (scripts/vercel-build.mjs). Every step is idempotent, so redeploying never duplicates records. How to set up your own → docs/deployment.md.

---

🚀 Quick start

Requirement: Node.js 20.9+ (LTS). Nothing else — no PostgreSQL install, no API keys.

Windows	macOS / Linux
Double-click run-evolt.bat	./run-evolt.sh

The browser opens at http://127.0.0.1:3000. Pick I'm a driver or I work for a charging company; each view links to the other.

1. Installs dependencies (internet needed once, a few minutes).
2. Creates .env.local and starts a private PostgreSQL 17 instance in .evolt/ (no installation).
3. Applies the database migrations.
4. Loads 13 labelled demo stations.
5. Stores the Arduino bench log unchanged, then imports the supplied session dataset through the normal import pipeline and trains the models.
6. Builds and starts the app.

Later starts take seconds and keep your data. Launcher options: --rebuild, --no-seed, --no-dataset, --no-open, --port 3001.

npm install
cp .env.example .env.local      # Windows: copy .env.example .env.local — then set DATABASE_URL
npm run db:migrate
npm run db:seed                 # optional: demo stations
npm run db:seed:dataset         # the supplied session dataset + model training
npm run build && npm start      # or: npm run dev

Variable	Purpose
DATABASE_URL	PostgreSQL connection string (required)
EVOLT_EDIT_MODE	open for local and demo use; token for any public deployment
EVOLT_ADMIN_TOKEN	Required in token mode (16+ characters)

Deployment to Vercel and a managed PostgreSQL database → docs/deployment.md.

---

🎯 A 2-minute tour for judges

Works on the live demo or a local copy.

#	Go to	What to notice
1	I'm a driver → start from a city → Chennai	The map stars the best match; click any pin to see that station's chargers. Each result card gives a reason built only from facts in the record
2	Set Your connector, tick Compare on two results	Hard filters apply instantly; the side-by-side table highlights only objective bests
3	Company workspace → Overview → Fleet map	Opens with Needs attention first; the map shows where, coloured by health
4	Action items → open any item	Evidence, triggering rule, why it matters, next step; mark it reviewed and it persists
5	Performance	Station table with uncertainty intervals and CSV export; the takeaways say when a difference is just noise
6	Learned model → type 4.2 → Classify	A live prediction from the stored model, with its rule and tested accuracy
7	Service forecast → open DEMO-13-C2	Likely service date with its range and the limit line; readings restated at 20 °C. DEMO-13-C3 rose only because it was measured hot, and is not flagged
8	Repair checks	One cleaning held, one relapsed after about a month; record new work on a charger page and set your own service limit
9	Arduino bench	C1, C2 and C3 side by side, each with its own healthy level; the chart shows why the model uses relative voltage; pick a charger and a degradation level to see each quantity scaled (Arduino reading → method → estimate → published reference); type 1.7 V on C1 and C2 in the estimator and compare
10	I'm a driver → open a demo station → Book a slot	Join the queue (next free start, sessions ahead) or pick a time; the day bar shows each booking and its 10-minute gap. Then My bookings to view or cancel. Book several vehicles plans a fleet across the station's chargers

---

✨ What it does

• Location, three ways: browser location (with permission), a city in the data, or typed coordinates. A denied permission or invalid input gets a clear message, never a guessed location.
• Hard requirements vs preferences:
  • Must meet: within radius, not offline, your connector, minimum power, optionally available only.
  • Ranked by: health evidence → availability → distance → power.
• Honest wording:
  • Availability unknown is never shown as available.
  • Status times are shown when they were recorded.
  • Distances are straight-line.
• Map: your location and search radius. The best match is starred, other matches are numbered by rank, and non-matching stations are faint. Click a pin to see a popup of every charger at that station, or click empty map to search from that point. Each result card has Show on map.
• Compare up to four chargers, and open a station page with chargers, a mini map of nearby stations, a coordinate copy button and its session history. No turn-by-turn directions are claimed.
• Empty results offer search a larger radius or remove optional filters, and say what was excluded and why.

Page	Answers
Overview	What needs attention first · where it is (map) · fleet connector health · session KPIs with definitions · trends with computed takeaways
Fleet map	Every located station coloured by its most concerning charger, with health filters, a needs-attention list, and popups showing chargers, alerts and open items
Action items	What is happening · why it matters · what to do next · which rule fired · priority · confidence
Performance	How each station performed, with intervals; filter, sort, export CSV
Service forecast	Which connector reaches its service limit next, the likely date and an 80% range; no date unless the rise is statistically clear
Repair checks	Each recorded job checked against later readings (held, relapsed, partly improved, no effect) and the held rate per kind of work
Chargers / Health alerts	Per-charger evidence charts; acknowledge, resolve or dismiss alerts
Learned model	What the model can and cannot predict, plus a live classifier and the degradation study
Arduino bench	The three bench connectors side by side, the relative-voltage model and how it was tested, the parameter-by-parameter scaling table at a chosen degradation level, heat and loss-share charts, real-wear physics, and the estimator
Data import	Drag-and-drop CSV/JSON with auto-detection, column mapping, validation and data-quality findings

Priority follows explicit rules:

• High: a connector-health analysis recommends inspection.
• Medium: a statistically clear station-level excess, or significant data inconsistencies.
• Low: data gaps, or a pattern that is no longer detected.

“Marked resolved” records a decision; it never claims a charger was repaired.

Our small experimental circuit logs three connectors (C1–C3), each with its own load, every 0.5 s for about a minute (run 2: 127 time steps, 381 readings). Each connector is swept repeatedly from near-healthy to an open circuit and back. EVOLT stores the readings unchanged, measures each connector's circuit from them, and scales each quantity by its own law — voltage × k_V, current × k_I, resistance × k_V/k_I, power × k_V·k_I; ratios unchanged; temperature only with a calibrated thermal resistance.

	C1	C2	C3
Load (median V ÷ I)	493 Ω	350 Ω	388 Ω
Healthy level V_ref (0 %)	3.455 V	3.067 V	3.193 V
Sweep to open circuit	every 15 s	every 20 s	every 22.5 s

Finding	Evidence
Each connector needs its own calibration	healthy levels differ by 12 %; one shared level would misstate degradation by ≈ 1.7 points
The model improved: relative voltage V ÷ V_ref	0.09 points error on held-out sweeps (one shared voltage line: 2.28); on an unseen connector, given one commissioning sweep, 0.09–0.12 (shared line: 1.05–4.52)
A 50 % bench state is a fault at charger scale	115 V lost and ≈ 1.8 kW of heat in one connector at 7.4 kW AC; 200 V and 12.5 kW at 50 kW DC (Method A)
Early real wear is below the bench's resolution	a new CCS2 contact is ≤ 0.5 mΩ (datasheet); at 50 kW DC wear reaches one 4.88 mV ADC step only at 10–20 × that (Method B)
The sweeps are a controlled pattern	they calibrate the voltage–degradation curve well but give no rate of wear over time

Every value is tagged Experimental circuit, Real-world estimate or Commercial reference (IEC 62196-1, MIDA and HARTING datasheets, ADAC tests). Details → docs/scaling.md and docs/machine-learning.md.

Charging-management platforms typically alert when a threshold is crossed. EVOLT follows the connector's contact resistance over time and answers three further questions:

Question	How
Is this rise real, or just a hot day?	Readings that record the contact temperature are restated at 20 °C (copper, 0.393 %/°C). Correction is all-or-nothing per metric, so it never creates jumps.
When will it need service?	Theil–Sen rate since the last recorded maintenance, with Sen's 80 % interval → likely date and range to the operator's limit (default: baseline + 50 %). No date unless the rise is statistically clear.
Did the repair work, and did it last?	Readings after each recorded job are compared with the connector's own normal range → held, relapsed, partly improved or no measurable effect, plus a held rate per kind of work.

Details and every threshold → docs/analytics.md.

The supplied file holds 1,000 sessions from 19 stations (1–11 Jan 2024). EVOLT reports what it supports, and also what it does not:

Finding	What EVOLT does
Every station appears as urban, suburban and rural	No station can be located; these stations are listed separately for drivers
No availability, downtime or outcome fields	Utilisation, downtime and failure rate are not shown, and the app says why
35 sessions lose more power than they consume	Raised as data-quality action items
30 % of sessions deliver more energy than the battery holds	Medium-priority item: check the units with the data provider
“Fast” and other charging types deliver the same power	Low-priority item: the labels look wrong
Station loss rates range from 16 % to 35 %	None is outside chance once 19 comparisons are accounted for, and the app says so

All figures were checked independently with pandas → docs/analytics.md.

Stratified 5-fold cross-validation. Each label is tested against a guessing baseline, an explainable threshold model and logistic regression. A label counts as predictable only if a model clearly beats guessing.

Question	Result	Guessing	Verdict
Power-loss category	91.7 %	37.4 %	✅ Predictable — rule: ≤ 1.88 kW Low · ≤ 3.67 kW Medium · else High
…without the power-loss reading	37.0 %	37.4 %	❌ Loss must be measured
Voltage-stability category	41.5 %	40.4 %	❌ Unrelated to every column — no prediction offered

The 91.7 % recovers the dataset's labelling rule: it is useful for consistent categorisation, not for forecasting. Predictions are served from the stored, evaluated model, and inputs outside the training range are flagged. Details → docs/machine-learning.md.

---

⚙️ How it works

flowchart LR
    A[CSV / JSON] --> B[Validate & import]
    B --> C[(PostgreSQL)]
    C --> D[Connector-health analysis]
    C --> E[Model training]
    C --> F[Action-item rules]
    C --> G[Driver ranking]
    D & E & F --> H[🏢 Company workspace]
    G --> I[🚗 Driver experience]

Stack: Next.js 16 · React 19 · TypeScript · Tailwind CSS 4 · PostgreSQL + Drizzle · Zod · Recharts · Vitest · Playwright.

Maps without a map provider: EVOLT draws its own map (Web Mercator, SVG) over a 268 KB background file bundled with the app, built from public-domain Natural Earth data with India's official boundaries. There are no tiles, API keys or network calls, and distances use the Haversine formula on stored coordinates.

src/app/            Entry page · /driver · /company · /api route handlers
src/features/       recommendations · insights · sessions · anomaly-detection ·
                    connector-health · learning · data-ingestion · bench  (pure, tested logic)
src/config/         analysis thresholds · scaling assumptions and references
src/components/     UI: driver, insights, charts, primitives
database/           SQL migrations · demo seed · dataset and bench loaders · data/ (raw files)
models/             saved model reports (session classifiers, degradation study + bench model)
scripts/            One-click launcher · offline model training
tests/              unit · integration · e2e
docs/               Detailed documentation (below)

Full breakdown and design decisions → docs/architecture.md.

Suite	Count	Covers
Unit	165	Slot, queue, buffer and fleet scheduling, charge-time estimates, IST calendar; metrics against pandas/SciPy, map projection and scale, every action-item rule, ranking, training, import, security, temperature correction, forecasts, repair outcomes, bench log (run 2) parsing and per-connector circuit values checked against pandas, scaling laws at every level, contact physics, degradation study, the relative-voltage model against simpler models on held-out sweeps and connectors, model reproducibility
Integration	37	Real API handlers + PostgreSQL: bookings without an admin token, overlap and buffer refusals, simultaneous requests for one slot, queue order, codes, cancellation, fleet plans; imports, reviews, CSV export, predictions, access control, service limits, maintenance and repair verification, raw bench storage (run 2, value for value), removal of earlier bench runs, and the bench APIs per connector and level
End-to-end	34	Booking a slot, joining the queue, finding a booking on another device, fleet booking and cancelling (desktop and phone); both user journeys in Chromium (desktop + mobile), maps and popups, forecasts and repair checks, the Arduino bench page (level selector, per-connector and new-connector estimates), regressions, wording checks

npm run lint && npm run typecheck && npm run test:unit

Last full run: 27 Oct 2026 — lint, type check and production build clean; 165 unit, 37 integration and 34 end-to-end passed.

Checked on the live demo (26 Oct 2026): the health endpoint, all 13 pages, and the recommendation, station, action-item, maintenance and bench-estimate APIs return real data; no runtime errors in the Vercel logs. Not yet checked on the live demo: saving changes with the admin token from a browser, and browser geolocation on a phone. Both are covered by the local integration and end-to-end tests.

What was and was not verified → docs/testing.md · docs/VERIFICATION.md.

---

⚖️ Scope and limitations

• Unverified data. The supplied dataset's origin is unverified and it is internally inconsistent, so its findings describe the file, not a real network.
• Demo stations. They are labelled Demo everywhere and are not real sites. One click removes them.
• No live data. There is no live availability, price or opening hours, so none is shown.
• Mapped stations. Only stations with recorded coordinates appear on maps; the 19 dataset stations have none and are listed separately.
• No user accounts. The driver/company switch is a view choice, not a sign-in. Changes are protected by a single admin token (token mode), which the live demo uses.
• Not a safety certification. Health categories summarise recorded evidence.

---

📚 Documentation

Guide	Contents
Architecture	System design, data flow, repository layout, security model
Data & analytics	Dataset findings, metric definitions, action-item rules, ranking logic
Machine learning	Pipeline, evaluation protocol, results and how to read them
API reference	Every endpoint, with examples
Data dictionary	Import formats, fields, units, database tables
Testing	Test suites, last verified run, what is not verified
Deployment	Vercel + Neon PostgreSQL, automatic migrations and data loading, the live setup
Hardware bench	Optional Arduino low-voltage demo
Slot and queue booking	Driver bookings: the gap between drivers, queue, fleet plans, charge-time estimate, booking codes, limits
Bench scaling	Arduino → real-world scaling formulas, assumptions, references and calibration needs