LocaScore — System Documentation¶

Internal wiki for the LocaScore codebase. Start here, then drill into whichever area you need.

What is LocaScore?¶

A paid neighborhood analysis product for Geneva, Switzerland. Users enter an address, see a free teaser (letter grades + headlines), and can buy a full interactive report covering transport, schools, environment, taxes, amenities, and more.

Domain: locascore.ch
Repo: github.com/daderidd/localscore
Status: Late beta — functional end to end, iterating on scoring + conversion

Table of contents¶

Section	What's inside
Architecture	System diagram, main components, request flows, hosting
Stack reference	Every library, framework, and service — what + why
Data pipeline	Python pipeline: inputs, KPIs, how to run, outputs
Scoring	The 3 composite scores: components, weights, tricky decisions
Backend	Cloudflare Worker API: routes, auth, rate limits, Supabase
Frontend	React app: routing, key pages, state, analytics
Service setup	How Cloudflare, Supabase, Stripe, Mapbox are configured
Deployment & ops	Runbooks for pipeline runs, KV uploads, deploys, admin views
Changelog & fixes	Beta tester feedback, bugs fixed, decisions made

Quick facts¶

Data: 17,097 H3 hexagonal cells (resolution 10 ~150m) covering Geneva canton
Columns: ~170 KPIs per cell (scores, distances, counts, percentiles, POI metadata)
Pipeline runtime: ~1.5 minutes without transit (r5py), ~39 min with transit
Free hosting: Cloudflare Pages + Workers + KV ($0), + Workers Paid ($5/mo for higher KV write limits)
Paid services: Supabase (free tier), Stripe (transaction fees), Mapbox (maps), Cloudflare domain
Languages: French + English from day one

Product overview¶

The product is anchored on three proprietary composite scores — the paywall value.

Daily Life Score — How easy is everyday life here? Transit + errands + environment + health + dining
Family Score — How good is this for raising kids? Schools + safety/quiet + playgrounds + green space + services
Smart Living Score — Hidden advantages of this location? Taxes + connectivity + environment + amenity access + development

Each score is percentile-ranked across the canton (A/B/C/D/F grade). Free teaser shows grades + one headline per score. Paid report shows the full numeric score, sub-breakdowns, charts, maps, and POI details.

See scoring.md for the full methodology.

Key files to know¶

Path	Purpose
`CLAUDE.md`	Project instructions for AI assistants
`ROADMAP.md`	High-level roadmap + completed phases
`code/pipeline.py`	Main data pipeline entry point
`code/config.py`	All constants, weights, URLs, thresholds
`code/scores.py`	Composite score computation (single file!)
`frontend/src/pages/`	React pages
`frontend/src/components/ui/`	Reusable UI components
`worker/src/routes/`	Cloudflare Worker API handlers
`supabase/migration_*.sql`	Database schema (run in order)

This wiki is designed to be read in order for a first pass, but each page stands alone. Page headers link back here. Code references use the file:line format so they're clickable in most editors.