feat: rebrand to Lumbre and harden startup/api flows

Author: VORTEX

README.md

@@ -1,35 +1,61 @@
-# HablaFlow (spanish-open-source)
+# Lumbre
 
-Open-source Spaanse leerapp met Duolingo-achtige mechanics, gebouwd met Next.js App Router + TypeScript + Tailwind + Drizzle + PostgreSQL + Docker.
+Lumbre is an open-source Spanish learning platform (Next.js + TypeScript + Drizzle + PostgreSQL) with a curriculum-first exercise engine, SM-2 SRS, XP/streak progression, and Docker support.
 
-## Features
-- 120 lessen (A1/A2)
-- 2640 zinnen (offline seedbaar)
-- 10 exercise types
-- XP + streak + SM-2 SRS
-- Admin panel (`/admin`)
-- Vocabulary browser (`/vocab`)
-- API endpoints voor progress en admin
+## Why the name?
+**Lumbre** means flame/glow. The product focus is steady mastery and momentum, not gamified noise.
 
-## Local run
+## Core capabilities
+- 120 lessons (A1/A2)
+- 2640 seeded sentences
+- 10 supported exercise types
+- XP + streak + SM-2 SRS progression
+- Admin panel (`/admin`) and vocabulary browser (`/vocab`)
+- Resilient API surface (`/api/health`, `/api/progress`, `/api/streak`, `/api/srs/review`, `/api/lesson/[slug]`)
+
+## Local development
 ```bash
+cp .env.example .env
 npm install
 npm run lint
 npm run test
 npm run build
-docker build -t spanish-open-source .
+npm run dev
+```
+
+## Production-like run (with DB migrate + seed on startup)
+```bash
 docker compose up --build
 ```
 
-## Database
+This starts:
+- `lumbre-db` (PostgreSQL 16)
+- `lumbre-app` (Next.js app)
+
+The app startup path automatically runs:
+1. `npm run db:migrate` (with DB readiness retries)
+2. `npm run db:seed`
+3. `next start`
+
+## API quick checks
 ```bash
-cp .env.example .env
-npm run db:generate
-npm run db:migrate
-npm run db:seed
+curl http://localhost:3000/api/health
+curl -X POST http://localhost:3000/api/progress -H 'content-type: application/json' -d '{"correct":8,"total":10,"quality":4,"streak":3}'
+curl -X POST http://localhost:3000/api/streak -H 'content-type: application/json' -d '{"streak":4,"lastActiveAt":"2026-03-01T00:00:00.000Z"}'
 ```
 
-## Offline curriculum artifact
+## Known limits
+- Current curriculum text is synthetic and not CEFR-reviewed by native teachers yet.
+- Startup migrates/seeds each container boot by design (safe via conflict handling, but slower cold starts).
+- No auth layer yet; admin APIs/pages are currently open in local/dev setups.
+
+## Useful scripts
 ```bash
+npm run lint
+npm run test
+npm run build
+npm run db:generate
+npm run db:migrate
+npm run db:seed
 npm run seed:offline
 ```

docker-compose.yml

@@ -1,17 +1,26 @@
 services:
-  db:
+  lumbre-db:
     image: postgres:16-alpine
     environment:
       POSTGRES_DB: spanish
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
     ports: ["5432:5432"]
-    volumes: ["pgdata:/var/lib/postgresql/data"]
-  app:
+    volumes: ["lumbre_pgdata:/var/lib/postgresql/data"]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d spanish"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  lumbre-app:
     build: .
     environment:
-      DATABASE_URL: postgres://postgres:postgres@db:5432/spanish
+      DATABASE_URL: postgres://postgres:postgres@lumbre-db:5432/spanish
     ports: ["3000:3000"]
-    depends_on: [db]
+    depends_on:
+      lumbre-db:
+        condition: service_healthy
+
 volumes:
-  pgdata:
+  lumbre_pgdata:

package-lock.json

@@ -1,18 +1,19 @@
 {
-  "name": "spanish-open-source",
+  "name": "lumbre-spanish",
   "version": "1.0.0",
   "private": true,
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start",
+    "start": "tsx scripts/startup.ts",
     "lint": "eslint",
     "test": "vitest run",
     "test:watch": "vitest",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
     "db:seed": "tsx scripts/seed.ts",
-    "seed:offline": "tsx scripts/generate-curriculum.ts"
+    "seed:offline": "tsx scripts/generate-curriculum.ts",
+    "start:next": "next start"
   },
   "dependencies": {
     "clsx": "^2.1.1",

package.json

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+
+function run(command: string, args: string[]) {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "inherit", env: process.env });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${command} ${args.join(" ")} failed with code ${code ?? "unknown"}`));
+      }
+    });
+  });
+}
+
+async function waitForPostgres(maxAttempts = 20, delayMs = 1500) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      await run("npm", ["run", "db:migrate"]);
+      return;
+    } catch (error) {
+      if (attempt === maxAttempts) {
+        throw error;
+      }
+      console.log(`[startup] postgres not ready (attempt ${attempt}/${maxAttempts}), retrying...`);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+}
+
+async function main() {
+  console.log("[startup] Ensuring database schema and seed...");
+  await waitForPostgres();
+  await run("npm", ["run", "db:seed"]);
+
+  console.log("[startup] Starting application...");
+  await run("npm", ["run", "start:next"]);
+}
+
+main().catch((error) => {
+  console.error("[startup] fatal error", error);
+  process.exit(1);
+});

scripts/startup.ts

@@ -1,2 +1,31 @@
+import { BRAND_NAME } from "@/lib/branding";
 import { curriculum } from "@/lib/curriculum";
-export default function AdminPage() { return (<main className="p-8 max-w-5xl mx-auto space-y-4"><h1 className="text-3xl font-bold">Admin Panel</h1><p className="text-gray-600">Manage lessons/content snapshots.</p><div className="overflow-auto border rounded"><table className="w-full text-sm"><thead><tr className="bg-gray-100"><th className="p-2 text-left">Slug</th><th className="p-2">Level</th><th className="p-2">Sentences</th></tr></thead><tbody>{curriculum.lessons.slice(0, 20).map((l) => (<tr key={l.slug} className="border-t"><td className="p-2">{l.slug}</td><td className="p-2 text-center">{l.level}</td><td className="p-2 text-center">{l.sentences.length}</td></tr>))}</tbody></table></div></main>); }
+
+export default function AdminPage() {
+  return (
+    <main className="p-8 max-w-5xl mx-auto space-y-4">
+      <h1 className="text-3xl font-bold">{BRAND_NAME} Admin</h1>
+      <p className="text-gray-600">Manage lessons/content snapshots.</p>
+      <div className="overflow-auto border rounded">
+        <table className="w-full text-sm">
+          <thead>
+            <tr className="bg-gray-100">
+              <th className="p-2 text-left">Slug</th>
+              <th className="p-2">Level</th>
+              <th className="p-2">Sentences</th>
+            </tr>
+          </thead>
+          <tbody>
+            {curriculum.lessons.slice(0, 20).map((l) => (
+              <tr key={l.slug} className="border-t">
+                <td className="p-2">{l.slug}</td>
+                <td className="p-2 text-center">{l.level}</td>
+                <td className="p-2 text-center">{l.sentences.length}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </main>
+  );
+}

src/app/admin/page.tsx

@@ -1,3 +1,9 @@
-import { NextResponse } from "next/server";
 import { curriculum } from "@/lib/curriculum";
-export async function GET() { return NextResponse.json({ lessons: curriculum.lessons.length, sample: curriculum.lessons.slice(0, 5) }); }
+import { ok, withErrorHandling } from "@/lib/api/http";
+
+export const GET = withErrorHandling(async () => {
+  return ok({
+    lessons: curriculum.lessons.length,
+    sample: curriculum.lessons.slice(0, 5),
+  });
+});

src/app/api/admin/lesson/route.ts

@@ -0,0 +1,18 @@
+import { ok, withErrorHandling } from "@/lib/api/http";
+import { curriculum } from "@/lib/curriculum";
+import { curriculumExerciseSummary } from "@/lib/exercise-engine";
+
+export const GET = withErrorHandling(async () => {
+  const summary = curriculumExerciseSummary();
+
+  return ok({
+    service: "lumbre-api",
+    status: "healthy",
+    checks: {
+      curriculumLoaded: curriculum.lessons.length > 0,
+      exerciseTypesComplete: summary.missing.length === 0 && summary.unknown.length === 0,
+    },
+    uptimeSeconds: Math.round(process.uptime()),
+    timestamp: new Date().toISOString(),
+  });
+});

src/app/api/health/route.ts

@@ -0,0 +1,12 @@
+import { ApiError, ok, withErrorHandling } from "@/lib/api/http";
+import { getLesson } from "@/lib/curriculum";
+
+export const GET = withErrorHandling(async (_req: Request, context: { params: Promise<{ slug: string }> }) => {
+  const { slug } = await context.params;
+  const lesson = getLesson(slug);
+  if (!lesson) {
+    throw new ApiError(404, `Lesson not found: ${slug}`);
+  }
+
+  return ok({ lesson });
+});

src/app/api/lesson/[slug]/route.ts

@@ -1,3 +1,33 @@
-import { NextResponse } from "next/server";
+import { z } from "zod";
 import { calcStreak, calcXP, sm2Review } from "@/lib/progress";
-export async function POST(req: Request) { const body = await req.json(); const xp = calcXP(body.correct ?? 0, body.total ?? 10); const streak = calcStreak(body.lastActiveAt ? new Date(body.lastActiveAt) : undefined, body.streak ?? 0); const srs = sm2Review({ interval: 1, repetition: 0, ease: 2.5, dueDate: new Date() }, body.quality ?? 4); return NextResponse.json({ xp, streak, nextReview: srs.dueDate.toISOString(), interval: srs.interval }); }
+import { ApiError, ok, safeJson, withErrorHandling } from "@/lib/api/http";
+
+const progressSchema = z.object({
+  correct: z.number().int().min(0).default(0),
+  total: z.number().int().min(1).default(10),
+  streak: z.number().int().min(0).default(0),
+  quality: z.number().int().min(0).max(5).default(4),
+  lastActiveAt: z.string().datetime().optional(),
+});
+
+export const POST = withErrorHandling(async (req: Request) => {
+  const body = progressSchema.safeParse(await safeJson(req));
+  if (!body.success) {
+    throw new ApiError(422, "Invalid progress payload", body.error.flatten());
+  }
+
+  const xp = calcXP(body.data.correct, body.data.total);
+  const streak = calcStreak(body.data.lastActiveAt ? new Date(body.data.lastActiveAt) : undefined, body.data.streak);
+  const srs = sm2Review({ interval: 1, repetition: 0, ease: 2.5, dueDate: new Date() }, body.data.quality);
+
+  return ok({
+    xp,
+    streak,
+    srs: {
+      nextReview: srs.dueDate.toISOString(),
+      interval: srs.interval,
+      repetition: srs.repetition,
+      ease: srs.ease,
+    },
+  });
+});