`README.md`

51 lines
# Charge & Explore  ·  _(codename: tesla)_

An EV **charging-stop experience finder**. Not another route planner — a decision
engine that answers one question:

> **"Which reachable charging stop gives me the best experience during the time my
> car is charging?"**

It combines charger quality, route detour, walking access, restrooms, opening
hours, family/pet suitability, weather, and activities that fit a *conservative*
charging window — and explains every recommendation.

> ⚠️ **Branding:** ships as the neutral **Charge & Explore**, never "Tesla"-branded.
> "tesla" is only the internal repo codename. Tesla Fleet API is an *optional,
> read-only* personalization layer, not the product's spine. See
> [`docs/legal-and-appstore.md`](docs/legal-and-appstore.md).

## What's built so far (v0.1 — the recommendation core)

The dependency-free, fully-tested decision logic — the crown jewels that don't
need any license or secret to build:

| Module | File | What it does |
|---|---|---|
| Charging-time estimator | `backend/src/core/charge-estimate.ts` | Integrates the nonlinear charge curve band-by-band; blends Tesla telemetry when stable; returns a confidence **range**. |
| Stop score | `backend/src/core/stop-score.ts` | Transparent, decomposable 0–100 score + confidence label. No black-box "safety score". |
| Activity matcher | `backend/src/core/activity-match.ts` | Ranks nearby activities that safely fit the window using the *pessimistic* charge estimate + a return buffer. |
| Provider seam | `backend/src/providers/provider.ts` | Interfaces so NREL→HERE, Apple→Google swap without a rewrite. Every record keeps provenance. |

### Run the tests

```bash
npm test          # node --test — 27 tests, no npm install required (Node >= 22)
```

## What's next

The gated / dependency-bearing layers (Tesla OAuth + telemetry ingress, licensed
station DB, PostGIS backend, the SwiftUI iOS app) are scoped in
[`PLAN.md`](PLAN.md) and [`docs/architecture.md`](docs/architecture.md). None of
them block the core above.

## Layout

```
backend/   TypeScript service layer (core logic today; API + adapters next)
ios/       SwiftUI native-app module map (see ios/README.md)
docs/      architecture, legal + App Store gates
PLAN.md    the full product plan, roadmap, and decisions
```