Deploy Bolt Run backend (Express + Firestore) as Docker Space

.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+npm-debug.log
+.env
+.env.local
+firebase-service-account.json
+*.log
+.git
+.gitignore
+.DS_Store

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.env
+.env.local
+firebase-service-account.json
+*.log
+.DS_Store

Dockerfile

@@ -0,0 +1,21 @@
+# Bolt Run backend — Hugging Face Docker Space
+FROM node:20-slim
+
+WORKDIR /app
+
+# Install production deps first (better layer caching)
+COPY package.json package-lock.json* ./
+RUN npm install --omit=dev
+
+# App source
+COPY src ./src
+
+ENV NODE_ENV=production
+# Hugging Face Spaces route to port 7860 by default (see app_port in README.md)
+ENV PORT=7860
+EXPOSE 7860
+
+# HF Spaces run the container as uid 1000 — node:20 ships a matching `node` user
+USER node
+
+CMD ["node", "src/server.js"]

README.md

@@ -1,10 +1,25 @@
 ---
-title: Bolt
-emoji: 🚀
-colorFrom: red
-colorTo: red
+title: Bolt Run Backend
+emoji: 🏃
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Bolt Run Backend
+
+Express + Cloud Firestore API for the Bolt Run app, deployed as a Hugging Face Docker Space.
+
+## Required Space secrets
+
+Set these under **Settings → Variables and secrets** (as **Secrets**):
+
+| Name | Value |
+|------|-------|
+| `FIREBASE_SERVICE_ACCOUNT_JSON` | The full contents of your `firebase-service-account.json` file (paste the whole JSON). |
+| `JWT_SECRET` | Your JWT signing secret. |
+| `JWT_EXPIRES_IN` | e.g. `7d`. |
+
+The container listens on port `7860`. Health check: `GET /health`. API base: `/api`.

package.json

@@ -0,0 +1,26 @@
+{
+  "name": "bolt-run-backend",
+  "version": "1.0.0",
+  "description": "BOLT Running App Backend API (Firestore)",
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js",
+    "db:migrate": "node src/db/migrate.js",
+    "db:seed": "node src/db/seed.js"
+  },
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "express-validator": "^7.2.0",
+    "firebase-admin": "^12.6.0",
+    "h3-js": "^4.4.0",
+    "jsonwebtoken": "^9.0.2",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.4"
+  }
+}

src/db/cleanup-demo.js

@@ -0,0 +1,49 @@
+// One-off cleanup: remove fake/test accounts that pollute the leaderboard,
+// along with their runs and any territory cells they captured.
+// Keeps the seeded "Demo Runner" (an active login) and all real users.
+const { collections, db } = require('./firestore');
+
+// Emails of the accounts to purge. Edit this list to change what gets removed.
+const FAKE_EMAILS = [
+  'alice+8075@bolt.run',
+  'bob+12638@bolt.run',
+  'terr+21395@bolt.run',  // Territory Test
+  'test4251@bolt.dev',    // Test User
+  'smoke+17074@bolt.run', // Smoke Test
+];
+
+async function deleteInBatches(refs) {
+  for (let i = 0; i < refs.length; i += 450) {
+    const batch = db.batch();
+    for (const ref of refs.slice(i, i + 450)) batch.delete(ref);
+    await batch.commit();
+  }
+}
+
+(async () => {
+  try {
+    for (const email of FAKE_EMAILS) {
+      const snap = await collections.users.where('email', '==', email).limit(1).get();
+      if (snap.empty) {
+        console.log(`  · no user for ${email} (already gone)`);
+        continue;
+      }
+      const userDoc = snap.docs[0];
+      const userId = userDoc.id;
+
+      const runsSnap = await collections.runs.where('userId', '==', userId).get();
+      await deleteInBatches(runsSnap.docs.map((d) => d.ref));
+
+      const cellsSnap = await collections.territoryCells.where('ownerUserId', '==', userId).get();
+      await deleteInBatches(cellsSnap.docs.map((d) => d.ref));
+
+      await userDoc.ref.delete();
+      console.log(`  - removed ${userDoc.data().name} <${email}> — ${runsSnap.size} run(s), ${cellsSnap.size} cell(s)`);
+    }
+    console.log('Cleanup complete.');
+    process.exit(0);
+  } catch (err) {
+    console.error('Cleanup failed:', err);
+    process.exit(1);
+  }
+})();

src/db/demo-run.js

@@ -0,0 +1,99 @@
+// Push a demo run for the Demo Runner so captured territory is visible on the
+// map. Builds a route that walks through a contiguous k-ring of H3 cells near
+// a center point, then saves it through the real /api/runs capture pipeline.
+const h3 = require('h3-js');
+
+const API = process.env.API_BASE || 'http://localhost:5000/api';
+const DEMO = { email: 'demo@bolt.run', password: 'password123' };
+
+// Center of the territory blob — Mehdipatnam, Hyderabad (matches the map view).
+const CENTER = { lat: 17.3955, lng: 78.4400 };
+const RES = 9;   // must match backend DEFAULT_RES
+const K = 2;     // ring size: k=2 -> 19 cells
+
+function haversineKm(a, b) {
+  const R = 6371, toRad = (d) => (d * Math.PI) / 180;
+  const dLat = toRad(b.lat - a.lat), dLng = toRad(b.lng - a.lng);
+  const s = Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(a.lat)) * Math.cos(toRad(b.lat)) * Math.sin(dLng / 2) ** 2;
+  return R * 2 * Math.atan2(Math.sqrt(s), Math.sqrt(1 - s));
+}
+
+(async () => {
+  try {
+    // 1. Log in as demo
+    const loginRes = await fetch(`${API}/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(DEMO),
+    });
+    if (!loginRes.ok) throw new Error(`login failed: ${loginRes.status}`);
+    const { token } = await loginRes.json();
+
+    // 1b. Idempotency — remove any prior demo run so re-runs don't stack distance.
+    const listRes = await fetch(`${API}/runs?limit=50`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const { runs = [] } = await listRes.json();
+    for (const r of runs.filter((x) => x.title === 'Demo territory run')) {
+      await fetch(`${API}/runs/${r.id}`, {
+        method: 'DELETE', headers: { Authorization: `Bearer ${token}` },
+      });
+    }
+
+    // 2. Build a route from the centers of a k-ring of H3 cells, ordered as a
+    //    nearest-neighbor tour so the path (and distance) reads like a real run.
+    const centerCell = h3.latLngToCell(CENTER.lat, CENTER.lng, RES);
+    const cells = h3.gridDisk(centerCell, K);
+    const all = cells.map((c) => { const [lat, lng] = h3.cellToLatLng(c); return { lat, lng }; });
+
+    const points = [all.shift()];
+    while (all.length) {
+      const last = points[points.length - 1];
+      let bi = 0, bd = Infinity;
+      all.forEach((p, i) => { const d = haversineKm(last, p); if (d < bd) { bd = d; bi = i; } });
+      points.push(all.splice(bi, 1)[0]);
+    }
+
+    const route = points.map((p) => ({ latitude: p.lat, longitude: p.lng }));
+
+    // 3. Distance + timing from the path
+    let distanceKm = 0;
+    for (let i = 1; i < points.length; i++) distanceKm += haversineKm(points[i - 1], points[i]);
+    const durationSec = Math.round((distanceKm / 10) * 3600); // ~10 km/h pace
+    const endedAt = new Date();
+    const startedAt = new Date(endedAt.getTime() - durationSec * 1000);
+
+    // 4. Save via the real capture pipeline
+    const runRes = await fetch(`${API}/runs`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        title: 'Demo territory run',
+        started_at: startedAt.toISOString(),
+        ended_at: endedAt.toISOString(),
+        duration_sec: durationSec,
+        distance_km: parseFloat(distanceKm.toFixed(3)),
+        avg_pace_sec_per_km: Math.round(durationSec / distanceKm),
+        calories: Math.round(70 * distanceKm * 1.036),
+        route,
+        start_lat: route[0].latitude,
+        start_lng: route[0].longitude,
+        end_lat: route[route.length - 1].latitude,
+        end_lng: route[route.length - 1].longitude,
+      }),
+    });
+    const body = await runRes.json();
+    if (!runRes.ok) throw new Error(`run save failed: ${runRes.status} ${JSON.stringify(body)}`);
+
+    console.log(`Saved demo run near ${CENTER.lat},${CENTER.lng}`);
+    console.log(`  route points: ${route.length}`);
+    console.log(`  distance_km : ${distanceKm.toFixed(3)}`);
+    console.log(`  cellsCaptured: ${body.cellsCaptured}`);
+    console.log('Open the World Map on the demo login to see the painted territory.');
+    process.exit(0);
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+})();

src/db/firestore.js

@@ -0,0 +1,50 @@
+const path = require('path');
+const admin = require('firebase-admin');
+require('dotenv').config();
+
+// On hosted platforms (e.g. Hugging Face Spaces) the whole service-account JSON
+// is injected as a secret env var instead of a committed file. Fall back to the
+// local file for development.
+let serviceAccount;
+if (process.env.FIREBASE_SERVICE_ACCOUNT_JSON) {
+  serviceAccount = JSON.parse(process.env.FIREBASE_SERVICE_ACCOUNT_JSON);
+} else {
+  const credPath =
+    process.env.FIREBASE_SERVICE_ACCOUNT ||
+    path.join(__dirname, '..', '..', 'firebase-service-account.json');
+  serviceAccount = require(credPath);
+}
+
+if (!admin.apps.length) {
+  admin.initializeApp({
+    credential: admin.credential.cert(serviceAccount),
+    projectId: serviceAccount.project_id,
+  });
+}
+
+const db = admin.firestore();
+db.settings({ ignoreUndefinedProperties: true });
+
+const { FieldValue, Timestamp } = admin.firestore;
+
+const collections = {
+  users: db.collection('users'),
+  runs: db.collection('runs'),
+  programs: db.collection('programs'),
+  userPrograms: db.collection('userPrograms'),
+  clubs: db.collection('clubs'),
+  clubMembers: db.collection('clubMembers'),
+  clubActivities: db.collection('clubActivities'),
+  territoryCells: db.collection('territoryCells'),
+};
+
+function docToObject(doc) {
+  if (!doc.exists) return null;
+  const data = doc.data();
+  for (const k of Object.keys(data)) {
+    if (data[k] instanceof Timestamp) data[k] = data[k].toDate().toISOString();
+  }
+  return { id: doc.id, ...data };
+}
+
+module.exports = { admin, db, FieldValue, Timestamp, collections, docToObject };

src/db/migrate.js

@@ -0,0 +1,22 @@
+// Firestore is schemaless — no DDL to run.
+// Composite indexes are defined in firestore.indexes.json (deploy with the Firebase CLI:
+//   firebase deploy --only firestore:indexes
+// ). For local dev the missing-index errors include a console URL you can click to
+// auto-create the index.
+//
+// This script exists so `npm run db:migrate` still resolves; it just smoke-tests
+// that the service account can reach Firestore.
+
+const { db } = require('./firestore');
+
+(async () => {
+  try {
+    await db.collection('__healthcheck').doc('ping').set({ at: new Date() });
+    await db.collection('__healthcheck').doc('ping').delete();
+    console.log('Firestore reachable. No schema migration needed.');
+    process.exit(0);
+  } catch (err) {
+    console.error('Firestore connection failed:', err.message);
+    process.exit(1);
+  }
+})();

src/db/overlap-test.js

@@ -0,0 +1,87 @@
+// Demonstrate territory takeover: a second runner runs through PART of the
+// Demo Runner's territory; those cells should flip to the new owner while the
+// rest stay with Demo. Prints a before/after ownership summary.
+const h3 = require('h3-js');
+
+const API = 'http://localhost:5000/api';
+const CENTER = { lat: 17.3955, lng: 78.4400 };
+const RES = 9;
+const BBOX = { sw_lat: 17.388, sw_lng: 78.432, ne_lat: 17.403, ne_lng: 78.448 };
+
+const jget = async (path, token) =>
+  (await fetch(`${API}${path}`, { headers: { Authorization: `Bearer ${token}` } })).json();
+
+async function login(email, password) {
+  const r = await fetch(`${API}/auth/login`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+  if (!r.ok) return null;
+  return (await r.json()).token;
+}
+
+async function ownersInBbox(token) {
+  const q = `?sw_lat=${BBOX.sw_lat}&sw_lng=${BBOX.sw_lng}&ne_lat=${BBOX.ne_lat}&ne_lng=${BBOX.ne_lng}`;
+  const { cells } = await jget(`/territory${q}`, token);
+  const by = {};
+  for (const c of cells) by[c.id] = c.ownerName || c.ownerUserId;
+  return by;
+}
+
+(async () => {
+  try {
+    // 1. Demo owns the territory
+    const demoToken = await login('demo@bolt.run', 'password123');
+    const before = await ownersInBbox(demoToken);
+    console.log(`\nBEFORE: ${Object.keys(before).length} cells in view`);
+    const beforeCounts = {};
+    Object.values(before).forEach((o) => { beforeCounts[o] = (beforeCounts[o] || 0) + 1; });
+    console.log('  owners:', beforeCounts);
+
+    // 2. Create a rival runner (fresh account)
+    const rivalEmail = `rival+${Math.floor(Math.random() * 100000)}@bolt.run`;
+    const regRes = await fetch(`${API}/auth/register`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Rival Runner', email: rivalEmail, password: 'password123' }),
+    });
+    const rivalToken = (await regRes.json()).token;
+
+    // 3. Rival runs through the center cell + its immediate ring (7 cells) —
+    //    a partial incursion into Demo's ~20-cell territory.
+    const centerCell = h3.latLngToCell(CENTER.lat, CENTER.lng, RES);
+    const incursion = h3.gridDisk(centerCell, 1); // 7 cells
+    const route = incursion.map((c) => { const [lat, lng] = h3.cellToLatLng(c); return { latitude: lat, longitude: lng }; });
+
+    const runRes = await fetch(`${API}/runs`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${rivalToken}` },
+      body: JSON.stringify({
+        title: 'Rival incursion',
+        started_at: new Date(Date.now() - 600000).toISOString(),
+        ended_at: new Date().toISOString(),
+        duration_sec: 600,
+        distance_km: 1.5,
+        route,
+        start_lat: route[0].latitude, start_lng: route[0].longitude,
+        end_lat: route[route.length - 1].latitude, end_lng: route[route.length - 1].longitude,
+      }),
+    });
+    const runBody = await runRes.json();
+    console.log(`\nRival ran through ${incursion.length} cells — cellsCaptured: ${runBody.cellsCaptured}`);
+
+    // 4. After
+    const after = await ownersInBbox(rivalToken);
+    const afterCounts = {};
+    Object.values(after).forEach((o) => { afterCounts[o] = (afterCounts[o] || 0) + 1; });
+    console.log(`\nAFTER: ${Object.keys(after).length} cells in view`);
+    console.log('  owners:', afterCounts);
+
+    const flipped = Object.keys(before).filter((id) => before[id] !== after[id]);
+    console.log(`\nFlipped ${flipped.length} cells from Demo Runner -> Rival Runner. The rest stayed Demo's.`);
+    console.log('Takeover on overlap: WORKS ✅');
+    process.exit(0);
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+})();

src/db/seed.js

@@ -0,0 +1,91 @@
+const bcrypt = require('bcryptjs');
+const { collections, FieldValue } = require('./firestore');
+
+function slug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+async function seed() {
+  try {
+    // Demo user
+    const demoEmail = 'demo@bolt.run';
+    const existing = await collections.users.where('email', '==', demoEmail).limit(1).get();
+    if (existing.empty) {
+      const hash = await bcrypt.hash('password123', 10);
+      const ref = collections.users.doc();
+      await ref.set({
+        name: 'Demo Runner',
+        email: demoEmail,
+        password_hash: hash,
+        avatar_url: null,
+        weight_kg: 70,
+        height_cm: 175,
+        date_of_birth: null,
+        total_runs: 0,
+        total_distance_km: 0,
+        total_duration_sec: 0,
+        total_calories: 0,
+        created_at: FieldValue.serverTimestamp(),
+        updated_at: FieldValue.serverTimestamp(),
+      });
+      console.log('  + demo user created');
+    } else {
+      console.log('  · demo user exists');
+    }
+
+    // Programs (deterministic doc IDs from title slug for idempotent seed)
+    const programs = [
+      { title: '5K Beginner Plan', description: 'Go from couch to 5K in 8 weeks', coach_name: 'Eliud Kipchoge', duration_weeks: 8, sessions_per_week: 3, difficulty: 'beginner', category: '5K', is_featured: true },
+      { title: '10K Speed Builder', description: 'Build speed and endurance for 10K', coach_name: 'Joshua Cheptegei', duration_weeks: 10, sessions_per_week: 4, difficulty: 'intermediate', category: '10K', is_featured: true },
+      { title: 'Half Marathon Prep', description: 'Complete your first half marathon', coach_name: 'Brigid Kosgei', duration_weeks: 12, sessions_per_week: 5, difficulty: 'intermediate', category: 'Half Marathon', is_featured: false },
+      { title: 'Marathon Masters', description: 'Advanced marathon training plan', coach_name: 'Kenenisa Bekele', duration_weeks: 16, sessions_per_week: 6, difficulty: 'advanced', category: 'Marathon', is_featured: false },
+    ];
+    for (const p of programs) {
+      const id = slug(p.title);
+      const ref = collections.programs.doc(id);
+      const snap = await ref.get();
+      if (!snap.exists) {
+        await ref.set({
+          ...p,
+          coach_avatar_url: null,
+          image_url: null,
+          total_enrolled: 0,
+          created_at: FieldValue.serverTimestamp(),
+        });
+        console.log(`  + program "${p.title}"`);
+      }
+    }
+
+    // Clubs
+    const clubs = [
+      { name: 'Morning Milers', description: 'Early birds who love the sunrise run', location: 'New York, NY', member_count: 124 },
+      { name: 'Trail Blazers', description: 'Off-road and trail running enthusiasts', location: 'Denver, CO', member_count: 89 },
+      { name: 'Speed Demons', description: 'Track and interval training focus', location: 'Los Angeles, CA', member_count: 203 },
+      { name: 'Weekend Warriors', description: 'Casual runners, serious fun', location: 'Chicago, IL', member_count: 156 },
+    ];
+    for (const c of clubs) {
+      const id = slug(c.name);
+      const ref = collections.clubs.doc(id);
+      const snap = await ref.get();
+      if (!snap.exists) {
+        await ref.set({
+          ...c,
+          avatar_url: null,
+          cover_url: null,
+          is_public: true,
+          created_by: null,
+          created_at: FieldValue.serverTimestamp(),
+        });
+        console.log(`  + club "${c.name}"`);
+      }
+    }
+
+    console.log('Seed complete.');
+    process.exit(0);
+  } catch (err) {
+    console.error('Seed failed:', err);
+    process.exit(1);
+  }
+}
+
+seed();

src/lib/territory.js

@@ -0,0 +1,34 @@
+const h3 = require('h3-js');
+
+const DEFAULT_RES = 9; // ~150m hex edge — good for foot-traffic granularity
+
+function cellsForRoute(route, resolution = DEFAULT_RES) {
+  if (!Array.isArray(route) || route.length === 0) return [];
+  const set = new Set();
+  for (const pt of route) {
+    const lat = Number(pt?.latitude);
+    const lng = Number(pt?.longitude);
+    if (!isFinite(lat) || !isFinite(lng)) continue;
+    set.add(h3.latLngToCell(lat, lng, resolution));
+  }
+  return [...set];
+}
+
+function cellsForBbox(sw, ne, resolution = DEFAULT_RES) {
+  if (!sw || !ne) return [];
+  const polygon = [[
+    [sw.lat, sw.lng],
+    [sw.lat, ne.lng],
+    [ne.lat, ne.lng],
+    [ne.lat, sw.lng],
+    [sw.lat, sw.lng],
+  ]];
+  return h3.polygonToCells(polygon, resolution);
+}
+
+function boundary(cellId) {
+  // returns array of [lat, lng] vertices
+  return h3.cellToBoundary(cellId);
+}
+
+module.exports = { DEFAULT_RES, cellsForRoute, cellsForBbox, boundary };

src/middleware/auth.js

@@ -0,0 +1,18 @@
+const jwt = require('jsonwebtoken');
+
+function authMiddleware(req, res, next) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({ message: 'No token provided' });
+  }
+  const token = authHeader.split(' ')[1];
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.userId = decoded.userId;
+    next();
+  } catch {
+    return res.status(401).json({ message: 'Invalid or expired token' });
+  }
+}
+
+module.exports = authMiddleware;

src/routes/auth.js

@@ -0,0 +1,141 @@
+const express = require('express');
+const bcrypt = require('bcryptjs');
+const jwt = require('jsonwebtoken');
+const { body, validationResult } = require('express-validator');
+const { collections, FieldValue, docToObject } = require('../db/firestore');
+const authMiddleware = require('../middleware/auth');
+
+const router = express.Router();
+
+function signToken(userId) {
+  return jwt.sign({ userId }, process.env.JWT_SECRET, {
+    expiresIn: process.env.JWT_EXPIRES_IN || '30d',
+  });
+}
+
+function publicUser(user) {
+  if (!user) return null;
+  const { password_hash, ...safe } = user;
+  return safe;
+}
+
+// POST /api/auth/register
+router.post(
+  '/register',
+  [
+    body('name').trim().notEmpty().withMessage('Name is required'),
+    body('email').isEmail().normalizeEmail().withMessage('Valid email required'),
+    body('password').isLength({ min: 6 }).withMessage('Password min 6 chars'),
+  ],
+  async (req, res) => {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+
+    const { name, email, password, weight_kg, height_cm, date_of_birth } = req.body;
+    try {
+      const existing = await collections.users.where('email', '==', email).limit(1).get();
+      if (!existing.empty)
+        return res.status(409).json({ message: 'Email already registered' });
+
+      const hash = await bcrypt.hash(password, 10);
+      const now = FieldValue.serverTimestamp();
+      const ref = collections.users.doc();
+      await ref.set({
+        name,
+        email,
+        password_hash: hash,
+        avatar_url: null,
+        display_name: null,
+        map_color: null,
+        weight_kg: weight_kg ?? null,
+        height_cm: height_cm ?? null,
+        date_of_birth: date_of_birth ?? null,
+        total_runs: 0,
+        total_distance_km: 0,
+        total_duration_sec: 0,
+        total_calories: 0,
+        created_at: now,
+        updated_at: now,
+      });
+
+      const snap = await ref.get();
+      const user = publicUser(docToObject(snap));
+      const token = signToken(ref.id);
+      res.status(201).json({ token, user });
+    } catch (err) {
+      console.error(err);
+      res.status(500).json({ message: 'Server error' });
+    }
+  }
+);
+
+// POST /api/auth/login
+router.post(
+  '/login',
+  [body('email').isEmail().normalizeEmail(), body('password').notEmpty()],
+  async (req, res) => {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+
+    const { email, password } = req.body;
+    try {
+      const snap = await collections.users.where('email', '==', email).limit(1).get();
+      if (snap.empty) return res.status(401).json({ message: 'Invalid credentials' });
+
+      const doc = snap.docs[0];
+      const user = docToObject(doc);
+      const valid = await bcrypt.compare(password, user.password_hash);
+      if (!valid) return res.status(401).json({ message: 'Invalid credentials' });
+
+      const token = signToken(doc.id);
+      res.json({ token, user: publicUser(user) });
+    } catch (err) {
+      console.error(err);
+      res.status(500).json({ message: 'Server error' });
+    }
+  }
+);
+
+// GET /api/auth/me
+router.get('/me', authMiddleware, async (req, res) => {
+  try {
+    const snap = await collections.users.doc(req.userId).get();
+    if (!snap.exists) return res.status(404).json({ message: 'User not found' });
+    res.json({ user: publicUser(docToObject(snap)) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// PATCH /api/auth/profile
+router.patch('/profile', authMiddleware, async (req, res) => {
+  const { name, weight_kg, height_cm, date_of_birth, avatar_url, display_name, map_color } = req.body;
+  try {
+    const ref = collections.users.doc(req.userId);
+    const update = { updated_at: FieldValue.serverTimestamp() };
+    if (name !== undefined) update.name = name;
+    if (weight_kg !== undefined) update.weight_kg = weight_kg;
+    if (height_cm !== undefined) update.height_cm = height_cm;
+    if (date_of_birth !== undefined) update.date_of_birth = date_of_birth;
+    if (avatar_url !== undefined) update.avatar_url = avatar_url;
+    // Display name shown on the world map (falls back to `name` when empty).
+    if (display_name !== undefined) update.display_name = display_name || null;
+    // Hex color (e.g. "#7C5CFF") this runner's territory is painted with.
+    if (map_color !== undefined) {
+      if (map_color !== null && !/^#[0-9A-Fa-f]{6}$/.test(map_color)) {
+        return res.status(400).json({ message: 'map_color must be a #RRGGBB hex string' });
+      }
+      update.map_color = map_color;
+    }
+
+    await ref.update(update);
+    const snap = await ref.get();
+    res.json({ user: publicUser(docToObject(snap)) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+module.exports = router;

src/routes/clubs.js

@@ -0,0 +1,244 @@
+const express = require('express');
+const { db, collections, FieldValue, docToObject } = require('../db/firestore');
+const authMiddleware = require('../middleware/auth');
+
+const router = express.Router();
+router.use(authMiddleware);
+
+function membershipDocId(clubId, userId) {
+  return `${clubId}_${userId}`;
+}
+
+async function annotateMembership(clubDocs, userId) {
+  if (clubDocs.length === 0) return [];
+  const memberSnaps = await Promise.all(
+    clubDocs.map((d) =>
+      collections.clubMembers.doc(membershipDocId(d.id, userId)).get()
+    )
+  );
+  return clubDocs.map((doc, i) => {
+    const club = docToObject(doc);
+    const m = memberSnaps[i];
+    club.is_member = m.exists;
+    club.my_role = m.exists ? m.data().role : null;
+    return club;
+  });
+}
+
+// GET /api/clubs/me — clubs user has joined (must come before /:id)
+router.get('/me', async (req, res) => {
+  try {
+    const memberSnap = await collections.clubMembers
+      .where('userId', '==', req.userId)
+      .get();
+
+    if (memberSnap.empty) return res.json({ clubs: [] });
+
+    const memberDocs = memberSnap.docs.sort(
+      (a, b) => (b.data().joinedAt?.toMillis?.() ?? 0) - (a.data().joinedAt?.toMillis?.() ?? 0)
+    );
+
+    const clubs = await Promise.all(
+      memberDocs.map(async (m) => {
+        const data = m.data();
+        const clubSnap = await collections.clubs.doc(data.clubId).get();
+        if (!clubSnap.exists) return null;
+        const club = docToObject(clubSnap);
+        club.my_role = data.role;
+        club.joined_at = data.joinedAt?.toDate?.().toISOString() ?? null;
+        return club;
+      })
+    );
+
+    res.json({ clubs: clubs.filter(Boolean) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/clubs — discover public clubs
+router.get('/', async (req, res) => {
+  try {
+    const snap = await collections.clubs
+      .where('is_public', '==', true)
+      .get();
+    const clubs = await annotateMembership(snap.docs, req.userId);
+    clubs.sort((a, b) => (b.member_count || 0) - (a.member_count || 0));
+    res.json({ clubs });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/clubs/:id
+router.get('/:id', async (req, res) => {
+  try {
+    const clubSnap = await collections.clubs.doc(req.params.id).get();
+    if (!clubSnap.exists) return res.status(404).json({ message: 'Club not found' });
+
+    const [annotated] = await annotateMembership([clubSnap], req.userId);
+
+    const memberSnap = await collections.clubMembers
+      .where('clubId', '==', req.params.id)
+      .get();
+
+    const memberDocs = memberSnap.docs
+      .sort((a, b) => (a.data().joinedAt?.toMillis?.() ?? 0) - (b.data().joinedAt?.toMillis?.() ?? 0))
+      .slice(0, 20);
+
+    const members = await Promise.all(
+      memberDocs.map(async (m) => {
+        const md = m.data();
+        const u = await collections.users.doc(md.userId).get();
+        if (!u.exists) return null;
+        const ud = u.data();
+        return {
+          id: u.id,
+          name: ud.name,
+          avatar_url: ud.avatar_url,
+          total_runs: ud.total_runs,
+          total_distance_km: ud.total_distance_km,
+          role: md.role,
+          joined_at: md.joinedAt?.toDate?.().toISOString() ?? null,
+        };
+      })
+    );
+
+    res.json({ club: annotated, members: members.filter(Boolean) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// POST /api/clubs/:id/join
+router.post('/:id/join', async (req, res) => {
+  try {
+    const clubRef = collections.clubs.doc(req.params.id);
+    const memberRef = collections.clubMembers.doc(membershipDocId(req.params.id, req.userId));
+
+    await db.runTransaction(async (tx) => {
+      const clubSnap = await tx.get(clubRef);
+      if (!clubSnap.exists) throw Object.assign(new Error('Club not found'), { code: 404 });
+      const memberSnap = await tx.get(memberRef);
+      if (memberSnap.exists) return;
+      tx.set(memberRef, {
+        clubId: req.params.id,
+        userId: req.userId,
+        role: 'member',
+        joinedAt: FieldValue.serverTimestamp(),
+      });
+      tx.update(clubRef, { member_count: FieldValue.increment(1) });
+    });
+
+    res.json({ message: 'Joined club' });
+  } catch (err) {
+    if (err.code === 404) return res.status(404).json({ message: err.message });
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// DELETE /api/clubs/:id/join — leave club
+router.delete('/:id/join', async (req, res) => {
+  try {
+    const clubRef = collections.clubs.doc(req.params.id);
+    const memberRef = collections.clubMembers.doc(membershipDocId(req.params.id, req.userId));
+
+    await db.runTransaction(async (tx) => {
+      const memberSnap = await tx.get(memberRef);
+      if (!memberSnap.exists) return;
+      tx.delete(memberRef);
+      tx.update(clubRef, { member_count: FieldValue.increment(-1) });
+    });
+
+    res.json({ message: 'Left club' });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// POST /api/clubs — create a club
+router.post('/', async (req, res) => {
+  const { name, description, location, is_public } = req.body;
+  if (!name) return res.status(400).json({ message: 'Club name is required' });
+  try {
+    const clubRef = collections.clubs.doc();
+    const memberRef = collections.clubMembers.doc(membershipDocId(clubRef.id, req.userId));
+    const now = FieldValue.serverTimestamp();
+
+    const batch = db.batch();
+    batch.set(clubRef, {
+      name,
+      description: description ?? null,
+      location: location ?? null,
+      avatar_url: null,
+      cover_url: null,
+      member_count: 1,
+      is_public: is_public !== false,
+      created_by: req.userId,
+      created_at: now,
+    });
+    batch.set(memberRef, {
+      clubId: clubRef.id,
+      userId: req.userId,
+      role: 'owner',
+      joinedAt: now,
+    });
+    await batch.commit();
+
+    const snap = await clubRef.get();
+    res.status(201).json({ club: docToObject(snap) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/clubs/:id/feed
+router.get('/:id/feed', async (req, res) => {
+  try {
+    const snap = await collections.clubActivities
+      .where('clubId', '==', req.params.id)
+      .get();
+
+    const activityDocs = snap.docs
+      .sort((a, b) => (b.data().createdAt?.toMillis?.() ?? 0) - (a.data().createdAt?.toMillis?.() ?? 0))
+      .slice(0, 30);
+
+    const activities = await Promise.all(
+      activityDocs.map(async (a) => {
+        const data = a.data();
+        const [userSnap, runSnap] = await Promise.all([
+          collections.users.doc(data.userId).get(),
+          data.runId ? collections.runs.doc(data.runId).get() : Promise.resolve(null),
+        ]);
+        const userData = userSnap.exists ? userSnap.data() : {};
+        const runData = runSnap?.exists ? runSnap.data() : null;
+        return {
+          id: a.id,
+          club_id: data.clubId,
+          user_id: data.userId,
+          run_id: data.runId ?? null,
+          message: data.message ?? null,
+          created_at: data.createdAt?.toDate?.().toISOString() ?? null,
+          user_name: userData.name ?? null,
+          avatar_url: userData.avatar_url ?? null,
+          distance_km: runData?.distance_km ?? null,
+          duration_sec: runData?.duration_sec ?? null,
+          avg_pace_sec_per_km: runData?.avg_pace_sec_per_km ?? null,
+        };
+      })
+    );
+
+    res.json({ activities });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+module.exports = router;

src/routes/programs.js

@@ -0,0 +1,147 @@
+const express = require('express');
+const { collections, FieldValue, docToObject } = require('../db/firestore');
+const authMiddleware = require('../middleware/auth');
+
+const router = express.Router();
+router.use(authMiddleware);
+
+function enrollmentDocId(userId, programId) {
+  return `${userId}_${programId}`;
+}
+
+async function annotateEnrollment(programDocs, userId) {
+  if (programDocs.length === 0) return [];
+  const enrollSnaps = await Promise.all(
+    programDocs.map((d) =>
+      collections.userPrograms.doc(enrollmentDocId(userId, d.id)).get()
+    )
+  );
+  return programDocs.map((doc, i) => {
+    const program = docToObject(doc);
+    const e = enrollSnaps[i];
+    program.is_enrolled = e.exists;
+    if (e.exists) {
+      const ed = e.data();
+      program.current_week = ed.current_week ?? 1;
+      program.is_active = ed.is_active ?? true;
+      program.enrolled_at = ed.enrolled_at?.toDate?.().toISOString() ?? null;
+    } else {
+      program.current_week = null;
+      program.is_active = null;
+    }
+    return program;
+  });
+}
+
+// GET /api/programs/me/active — must come before /:id
+router.get('/me/active', async (req, res) => {
+  try {
+    const enrollSnap = await collections.userPrograms
+      .where('userId', '==', req.userId)
+      .where('is_active', '==', true)
+      .get();
+
+    const programs = await Promise.all(
+      enrollSnap.docs.map(async (e) => {
+        const ed = e.data();
+        const p = await collections.programs.doc(ed.programId).get();
+        if (!p.exists) return null;
+        const program = docToObject(p);
+        program.current_week = ed.current_week ?? 1;
+        program.enrolled_at = ed.enrolled_at?.toDate?.().toISOString() ?? null;
+        return program;
+      })
+    );
+
+    res.json({ programs: programs.filter(Boolean) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/programs
+router.get('/', async (req, res) => {
+  const { difficulty, category } = req.query;
+  try {
+    let query = collections.programs;
+    if (difficulty) query = query.where('difficulty', '==', difficulty);
+    // Firestore can't do case-insensitive substring; for category we filter exact match.
+    if (category) query = query.where('category', '==', category);
+
+    const snap = await query.get();
+    const sorted = snap.docs.slice().sort((a, b) => {
+      const ad = a.data(), bd = b.data();
+      if ((bd.is_featured ? 1 : 0) !== (ad.is_featured ? 1 : 0))
+        return (bd.is_featured ? 1 : 0) - (ad.is_featured ? 1 : 0);
+      const at = ad.created_at?.toMillis?.() ?? 0;
+      const bt = bd.created_at?.toMillis?.() ?? 0;
+      return bt - at;
+    });
+
+    const programs = await annotateEnrollment(sorted, req.userId);
+    res.json({ programs });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/programs/:id
+router.get('/:id', async (req, res) => {
+  try {
+    const snap = await collections.programs.doc(req.params.id).get();
+    if (!snap.exists) return res.status(404).json({ message: 'Program not found' });
+    const [program] = await annotateEnrollment([snap], req.userId);
+    res.json({ program });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// POST /api/programs/:id/enroll
+router.post('/:id/enroll', async (req, res) => {
+  try {
+    const enrollRef = collections.userPrograms.doc(enrollmentDocId(req.userId, req.params.id));
+    const programRef = collections.programs.doc(req.params.id);
+
+    const enrollSnap = await enrollRef.get();
+    const wasEnrolled = enrollSnap.exists;
+
+    await enrollRef.set(
+      {
+        userId: req.userId,
+        programId: req.params.id,
+        enrolled_at: enrollSnap.exists ? enrollSnap.data().enrolled_at : FieldValue.serverTimestamp(),
+        current_week: 1,
+        is_active: true,
+        completed_at: null,
+      },
+      { merge: true }
+    );
+
+    if (!wasEnrolled) {
+      await programRef.update({ total_enrolled: FieldValue.increment(1) });
+    }
+
+    res.json({ message: 'Enrolled successfully' });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// DELETE /api/programs/:id/enroll
+router.delete('/:id/enroll', async (req, res) => {
+  try {
+    const enrollRef = collections.userPrograms.doc(enrollmentDocId(req.userId, req.params.id));
+    await enrollRef.set({ is_active: false }, { merge: true });
+    res.json({ message: 'Unenrolled' });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+module.exports = router;

src/routes/runs.js

@@ -0,0 +1,237 @@
+const express = require('express');
+const { db, collections, FieldValue, Timestamp, docToObject } = require('../db/firestore');
+const { cellsForRoute } = require('../lib/territory');
+const authMiddleware = require('../middleware/auth');
+
+// Firestore batches cap at 500 writes
+const BATCH_SIZE = 450;
+
+async function captureCells(cellIds, userId, runId) {
+  if (cellIds.length === 0) return 0;
+  const now = FieldValue.serverTimestamp();
+  let captured = 0;
+  for (let i = 0; i < cellIds.length; i += BATCH_SIZE) {
+    const slice = cellIds.slice(i, i + BATCH_SIZE);
+    const batch = db.batch();
+    for (const cellId of slice) {
+      batch.set(
+        collections.territoryCells.doc(cellId),
+        {
+          ownerUserId: userId,
+          ownerClubId: null,
+          capturedAt: now,
+          runId,
+          captureCount: FieldValue.increment(1),
+        },
+        { merge: true }
+      );
+    }
+    await batch.commit();
+    captured += slice.length;
+  }
+  return captured;
+}
+
+const router = express.Router();
+router.use(authMiddleware);
+
+function toTimestamp(value) {
+  if (!value) return null;
+  const d = value instanceof Date ? value : new Date(value);
+  return isNaN(d.getTime()) ? null : Timestamp.fromDate(d);
+}
+
+// POST /api/runs — save a completed run
+router.post('/', async (req, res) => {
+  const {
+    title, started_at, ended_at, duration_sec, distance_km,
+    avg_pace_sec_per_km, max_pace_sec_per_km, calories,
+    avg_heart_rate, max_heart_rate, elevation_gain_m,
+    route, start_lat, start_lng, end_lat, end_lng,
+    map_snapshot_url, notes, weather,
+  } = req.body;
+
+  if (!started_at || !duration_sec || distance_km === undefined)
+    return res.status(400).json({ message: 'started_at, duration_sec and distance_km are required' });
+
+  const startedAtTs = toTimestamp(started_at);
+  if (!startedAtTs) return res.status(400).json({ message: 'started_at must be a valid date' });
+
+  try {
+    const userRef = collections.users.doc(req.userId);
+    const runRef = collections.runs.doc();
+
+    await db.runTransaction(async (tx) => {
+      const userSnap = await tx.get(userRef);
+      if (!userSnap.exists) throw new Error('User not found');
+
+      tx.set(runRef, {
+        userId: req.userId,
+        title: title ?? null,
+        started_at: startedAtTs,
+        ended_at: toTimestamp(ended_at),
+        duration_sec,
+        distance_km,
+        avg_pace_sec_per_km: avg_pace_sec_per_km ?? null,
+        max_pace_sec_per_km: max_pace_sec_per_km ?? null,
+        calories: calories ?? 0,
+        avg_heart_rate: avg_heart_rate ?? null,
+        max_heart_rate: max_heart_rate ?? null,
+        elevation_gain_m: elevation_gain_m ?? 0,
+        route: route ?? null,
+        start_lat: start_lat ?? null,
+        start_lng: start_lng ?? null,
+        end_lat: end_lat ?? null,
+        end_lng: end_lng ?? null,
+        map_snapshot_url: map_snapshot_url ?? null,
+        notes: notes ?? null,
+        weather: weather ?? null,
+        created_at: FieldValue.serverTimestamp(),
+      });
+
+      tx.update(userRef, {
+        total_runs: FieldValue.increment(1),
+        total_distance_km: FieldValue.increment(Number(distance_km) || 0),
+        total_duration_sec: FieldValue.increment(Number(duration_sec) || 0),
+        total_calories: FieldValue.increment(Number(calories) || 0),
+        updated_at: FieldValue.serverTimestamp(),
+      });
+    });
+
+    let cellsCaptured = 0;
+    try {
+      const cellIds = cellsForRoute(route);
+      cellsCaptured = await captureCells(cellIds, req.userId, runRef.id);
+    } catch (capErr) {
+      console.error('territory capture failed:', capErr.message);
+    }
+
+    const saved = await runRef.get();
+    res.status(201).json({ run: docToObject(saved), cellsCaptured });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/runs — list user's runs with pagination
+router.get('/', async (req, res) => {
+  const page = Math.max(1, parseInt(req.query.page) || 1);
+  const limit = Math.min(50, parseInt(req.query.limit) || 20);
+  const offset = (page - 1) * limit;
+
+  try {
+    // Query by userId only (single-field, auto-indexed — no composite index
+    // required); sort by start time and paginate in JS.
+    const snap = await collections.runs.where('userId', '==', req.userId).get();
+    const all = snap.docs
+      .map(docToObject)
+      .sort((a, b) => new Date(b.started_at) - new Date(a.started_at));
+
+    res.json({
+      runs: all.slice(offset, offset + limit),
+      total: all.length,
+      page,
+      limit,
+    });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/runs/stats/weekly — must come before /:id
+router.get('/stats/weekly', async (req, res) => {
+  try {
+    const cutoffMs = Date.now() - 12 * 7 * 24 * 60 * 60 * 1000;
+    // Query by userId only (no composite index); apply the date cutoff in JS.
+    const snap = await collections.runs
+      .where('userId', '==', req.userId)
+      .get();
+
+    const buckets = new Map();
+    for (const doc of snap.docs) {
+      const data = doc.data();
+      const startedAt = data.started_at instanceof Timestamp
+        ? data.started_at.toDate()
+        : new Date(data.started_at);
+      if (startedAt.getTime() < cutoffMs) continue;
+      const weekStart = new Date(startedAt);
+      const day = weekStart.getUTCDay();
+      const diff = (day === 0 ? -6 : 1 - day);
+      weekStart.setUTCDate(weekStart.getUTCDate() + diff);
+      weekStart.setUTCHours(0, 0, 0, 0);
+      const key = weekStart.toISOString();
+
+      const acc = buckets.get(key) || {
+        week: key, run_count: 0, total_km: 0, total_sec: 0, total_calories: 0, _paceSum: 0, _paceN: 0,
+      };
+      acc.run_count += 1;
+      acc.total_km += Number(data.distance_km) || 0;
+      acc.total_sec += Number(data.duration_sec) || 0;
+      acc.total_calories += Number(data.calories) || 0;
+      if (data.avg_pace_sec_per_km != null) {
+        acc._paceSum += Number(data.avg_pace_sec_per_km);
+        acc._paceN += 1;
+      }
+      buckets.set(key, acc);
+    }
+
+    const weekly = Array.from(buckets.values())
+      .map(({ _paceSum, _paceN, ...rest }) => ({
+        ...rest,
+        avg_pace: _paceN ? _paceSum / _paceN : null,
+      }))
+      .sort((a, b) => b.week.localeCompare(a.week));
+
+    res.json({ weekly });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/runs/:id — single run detail
+router.get('/:id', async (req, res) => {
+  try {
+    const snap = await collections.runs.doc(req.params.id).get();
+    if (!snap.exists || snap.data().userId !== req.userId)
+      return res.status(404).json({ message: 'Run not found' });
+    res.json({ run: docToObject(snap) });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// DELETE /api/runs/:id
+router.delete('/:id', async (req, res) => {
+  try {
+    const runRef = collections.runs.doc(req.params.id);
+    const userRef = collections.users.doc(req.userId);
+
+    await db.runTransaction(async (tx) => {
+      const runSnap = await tx.get(runRef);
+      if (!runSnap.exists || runSnap.data().userId !== req.userId) {
+        throw Object.assign(new Error('Run not found'), { code: 404 });
+      }
+      const { distance_km = 0, duration_sec = 0, calories = 0 } = runSnap.data();
+      tx.delete(runRef);
+      tx.update(userRef, {
+        total_runs: FieldValue.increment(-1),
+        total_distance_km: FieldValue.increment(-Number(distance_km)),
+        total_duration_sec: FieldValue.increment(-Number(duration_sec)),
+        total_calories: FieldValue.increment(-Number(calories)),
+        updated_at: FieldValue.serverTimestamp(),
+      });
+    });
+
+    res.json({ message: 'Run deleted' });
+  } catch (err) {
+    if (err.code === 404) return res.status(404).json({ message: err.message });
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+module.exports = router;

src/routes/territory.js

@@ -0,0 +1,154 @@
+const express = require('express');
+const { db, collections, FieldValue, Timestamp } = require('../db/firestore');
+const { cellsForBbox, boundary } = require('../lib/territory');
+const authMiddleware = require('../middleware/auth');
+
+const router = express.Router();
+router.use(authMiddleware);
+
+const MAX_BBOX_CELLS = 4000;
+const FIRESTORE_GET_ALL_CHUNK = 300;
+
+// GET /api/territory?sw_lat=&sw_lng=&ne_lat=&ne_lng=
+// Returns captured cells within the bounding box.
+router.get('/', async (req, res) => {
+  const sw = { lat: parseFloat(req.query.sw_lat), lng: parseFloat(req.query.sw_lng) };
+  const ne = { lat: parseFloat(req.query.ne_lat), lng: parseFloat(req.query.ne_lng) };
+  if ([sw.lat, sw.lng, ne.lat, ne.lng].some((v) => !isFinite(v))) {
+    return res.status(400).json({ message: 'sw_lat, sw_lng, ne_lat, ne_lng required' });
+  }
+
+  try {
+    const cellIds = cellsForBbox(sw, ne);
+    if (cellIds.length === 0) return res.json({ cells: [] });
+    if (cellIds.length > MAX_BBOX_CELLS) {
+      return res.status(413).json({
+        message: `bbox covers ${cellIds.length} cells (max ${MAX_BBOX_CELLS}); zoom in.`,
+      });
+    }
+
+    const refs = cellIds.map((id) => collections.territoryCells.doc(id));
+    const rawCells = [];
+    for (let i = 0; i < refs.length; i += FIRESTORE_GET_ALL_CHUNK) {
+      const chunk = refs.slice(i, i + FIRESTORE_GET_ALL_CHUNK);
+      const snaps = await db.getAll(...chunk);
+      for (const snap of snaps) {
+        if (!snap.exists) continue;
+        rawCells.push({ id: snap.id, data: snap.data() });
+      }
+    }
+
+    // Enrich with owner name (one batched user fetch per unique owner)
+    const ownerIds = [...new Set(rawCells.map((c) => c.data.ownerUserId).filter(Boolean))];
+    const ownerById = {};
+    if (ownerIds.length > 0) {
+      const userRefs = ownerIds.map((id) => collections.users.doc(id));
+      const userSnaps = await db.getAll(...userRefs);
+      for (const u of userSnaps) {
+        if (!u.exists) continue;
+        const ud = u.data();
+        ownerById[u.id] = {
+          // Prefer the map display name; fall back to the account name.
+          name: ud.display_name || ud.name || null,
+          avatar_url: ud.avatar_url ?? null,
+          map_color: ud.map_color ?? null,
+        };
+      }
+    }
+
+    const cells = rawCells.map(({ id, data }) => ({
+      id,
+      ownerUserId: data.ownerUserId ?? null,
+      ownerClubId: data.ownerClubId ?? null,
+      ownerName: data.ownerUserId ? ownerById[data.ownerUserId]?.name ?? null : null,
+      ownerColor: data.ownerUserId ? ownerById[data.ownerUserId]?.map_color ?? null : null,
+      ownerAvatar: data.ownerUserId ? ownerById[data.ownerUserId]?.avatar_url ?? null : null,
+      isMine: data.ownerUserId === req.userId,
+      capturedAt: data.capturedAt instanceof Timestamp ? data.capturedAt.toDate().toISOString() : null,
+      boundary: boundary(id),
+    }));
+
+    res.json({ cells });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/territory/leaderboard?limit=20
+router.get('/leaderboard', async (req, res) => {
+  const limit = Math.min(50, Math.max(1, parseInt(req.query.limit) || 20));
+  try {
+    // Pull a candidate pool of users (sorted by total_distance_km as a cheap proxy
+    // for "active runners"), then count their owned cells in parallel.
+    const candidatePoolSize = Math.min(100, limit * 3);
+    const userSnap = await collections.users
+      .orderBy('total_distance_km', 'desc')
+      .limit(candidatePoolSize)
+      .get();
+
+    const users = userSnap.docs.map((d) => ({
+      id: d.id,
+      name: d.data().display_name || d.data().name || null,
+      avatar_url: d.data().avatar_url ?? null,
+      map_color: d.data().map_color ?? null,
+      total_distance_km: d.data().total_distance_km ?? 0,
+    }));
+
+    const counts = await Promise.all(
+      users.map(async (u) => {
+        const c = await collections.territoryCells.where('ownerUserId', '==', u.id).count().get();
+        return c.data().count;
+      })
+    );
+
+    const ranked = users
+      .map((u, i) => ({ ...u, cells_owned: counts[i] }))
+      .filter((u) => u.cells_owned > 0)
+      .sort((a, b) => b.cells_owned - a.cells_owned)
+      .slice(0, limit)
+      .map((u, i) => ({ ...u, rank: i + 1, isMe: u.id === req.userId }));
+
+    res.json({ leaderboard: ranked });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/territory/me/stats — quick numeric overview
+router.get('/me/stats', async (req, res) => {
+  try {
+    const snap = await collections.territoryCells
+      .where('ownerUserId', '==', req.userId)
+      .count()
+      .get();
+    res.json({ cells_owned: snap.data().count });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+// GET /api/territory/me/cells — all cells the user owns (ungeometric — for stats/export)
+router.get('/me/cells', async (req, res) => {
+  try {
+    const snap = await collections.territoryCells
+      .where('ownerUserId', '==', req.userId)
+      .limit(2000)
+      .get();
+    const cells = snap.docs.map((d) => ({
+      id: d.id,
+      boundary: boundary(d.id),
+      capturedAt: d.data().capturedAt instanceof Timestamp
+        ? d.data().capturedAt.toDate().toISOString()
+        : null,
+    }));
+    res.json({ cells });
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ message: 'Server error' });
+  }
+});
+
+module.exports = router;

src/server.js

@@ -0,0 +1,33 @@
+require('dotenv').config();
+const express = require('express');
+const cors = require('cors');
+
+const authRoutes = require('./routes/auth');
+const runsRoutes = require('./routes/runs');
+const programsRoutes = require('./routes/programs');
+const clubsRoutes = require('./routes/clubs');
+const territoryRoutes = require('./routes/territory');
+
+const app = express();
+const PORT = process.env.PORT || 5000;
+
+app.use(cors());
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true }));
+
+app.get('/health', (_, res) => res.json({ status: 'ok', time: new Date().toISOString() }));
+
+app.use('/api/auth', authRoutes);
+app.use('/api/runs', runsRoutes);
+app.use('/api/programs', programsRoutes);
+app.use('/api/clubs', clubsRoutes);
+app.use('/api/territory', territoryRoutes);
+
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.status(500).json({ message: 'Internal server error' });
+});
+
+app.listen(PORT, () => {
+  console.log(`🚀 BOLT API running on http://localhost:${PORT}`);
+});