create-softeneers-app 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-softeneers-app",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Scaffold a new Softeneers Framework project: 5 templates (next-fullstack, express-api, hono-api, tanstack-start, minimal) with db/auth/docker toggles.",
   "type": "module",
   "bin": {

package/templates/express-api/README.md

@@ -43,17 +43,18 @@ curl -X POST localhost:4000/api/cars -H 'content-type: application/json' \
 ## Database
 
 Persistence is MySQL via Sequelize ([`@softeneers/db`](https://www.npmjs.com/package/@softeneers/db)).
-Configure `DB_*` in `.env`, then:
+**`npm run dev` works immediately even without a database** — the store falls back
+to a pre-seeded in-memory one when MySQL is unreachable. To switch on real
+persistence, set `DB_*` in `.env` and start MySQL:
 
 ```bash
 # #if docker
 docker compose up -d   # start MySQL
 # #endif
+# The app auto-creates and seeds tables on first connect; these scripts give
+# you explicit control (e.g. reseeding or a clean reset):
 npm run db:migrate && npm run db:seed
 ```
-
-Toggle the database off at generation time (`--no-db`) to swap in a dependency-free
-in-memory store — the CRUD API behaves identically.
 # #endif
 # #if auth
 
@@ -67,11 +68,10 @@ mounted at `/api/auth/*`. Set a strong `AUTH_SECRET` in `.env` before deploying.
 
 ```bash
 npm install
-# #if docker
-docker compose up -d
-# #endif
+npm run dev          # a pre-seeded CRUD demo — no other setup needed
+```
 # #if db
-npm run db:migrate && npm run db:seed
+
+The app starts immediately on an in-memory demo and uses MySQL automatically once
+it's reachable — see **Database** above to enable persistence.
 # #endif
-npm run dev
-```

package/templates/express-api/softeneers.template.json

@@ -1,5 +1,5 @@
 {
-  "toggles": { "db": true, "auth": false, "docker": true },
+  "toggles": { "db": false, "auth": false, "docker": false },
   "fragments": {
     "db": {
       "removePaths": ["src/db.ts", "src/scripts", "docker-compose.yml"],

package/templates/express-api/src/cars/demo.ts

@@ -0,0 +1,10 @@
+import type { NewCar } from "./types.js";
+
+// Demo garage inventory seeded on first run so `npm run dev` shows a working
+// CRUD demo immediately — into MySQL when a database is reachable, otherwise
+// into the in-memory store.
+export const DEMO_CARS: NewCar[] = [
+  { brand: "Toyota", model: "Corolla", year: 2021 },
+  { brand: "Tesla", model: "Model 3", year: 2023 },
+  { brand: "Ford", model: "Mustang", year: 1969 },
+];

package/templates/express-api/src/cars/store.ts

@@ -1,8 +1,10 @@
+import { DEMO_CARS } from "./demo.js";
 import type { Car, NewCar } from "./types.js";
 
-// The data layer behind the CRUD routes. With the `db` toggle on this is backed
-// by MySQL (Sequelize via @softeneers/db); with it off it's an in-memory Map so
-// the API runs with zero infrastructure. Both satisfy the same CarStore.
+// The data layer behind the CRUD routes. With the `db` toggle on it persists to
+// MySQL (Sequelize via @softeneers/db) and **falls back to an in-memory store if
+// the database is unreachable**, so `npm run dev` always yields a working,
+// pre-seeded demo. With `db` off it is always in-memory.
 export interface CarStore {
   list(): Promise<Car[]>;
   get(id: number): Promise<Car | null>;
@@ -11,8 +13,43 @@ export interface CarStore {
   remove(id: number): Promise<boolean>;
 }
 
+// In-memory backend (the default, and the fallback when no database is reachable).
+function createMemoryStore(seed = true): CarStore {
+  let nextId = 1;
+  const cars = new Map<number, Car>();
+  if (seed) {
+    for (const car of DEMO_CARS) {
+      const id = nextId++;
+      cars.set(id, { id, ...car });
+    }
+  }
+  return {
+    async list() {
+      return [...cars.values()].sort((a, b) => a.id - b.id);
+    },
+    async get(id) {
+      return cars.get(id) ?? null;
+    },
+    async create(input) {
+      const car: Car = { id: nextId++, ...input };
+      cars.set(car.id, car);
+      return car;
+    },
+    async update(id, input) {
+      const car = cars.get(id);
+      if (!car) return null;
+      const next: Car = { ...car, ...input };
+      cars.set(id, next);
+      return next;
+    },
+    async remove(id) {
+      return cars.delete(id);
+    },
+  };
+}
+
 // #if db
-import { DataTypes, Model } from "@softeneers/db";
+import { assertConnection, DataTypes, Model } from "@softeneers/db";
 
 import { sequelize } from "../db.js";
 
@@ -37,56 +74,77 @@ export { CarModel };
 
 const toCar = (m: CarModel): Car => ({ id: m.id, brand: m.brand, model: m.model, year: m.year });
 
+function createDbStore(): CarStore {
+  return {
+    async list() {
+      return (await CarModel.findAll({ order: [["id", "ASC"]] })).map(toCar);
+    },
+    async get(id) {
+      const m = await CarModel.findByPk(id);
+      return m ? toCar(m) : null;
+    },
+    async create(input) {
+      return toCar(await CarModel.create(input));
+    },
+    async update(id, input) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return null;
+      await m.update(input);
+      return toCar(m);
+    },
+    async remove(id) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return false;
+      await m.destroy();
+      return true;
+    },
+  };
+}
+
+// Resolve the backend once, lazily, on first use: try MySQL (create tables +
+// seed if empty); on any connection error, fall back to the in-memory store.
+let backend: Promise<CarStore> | null = null;
+function resolveBackend(): Promise<CarStore> {
+  if (!backend) {
+    backend = (async () => {
+      try {
+        await assertConnection(sequelize);
+        await sequelize.sync();
+        const db = createDbStore();
+        if ((await db.list()).length === 0) {
+          for (const car of DEMO_CARS) await db.create(car);
+        }
+        console.log("Data store: MySQL");
+        return db;
+      } catch {
+        console.warn(
+          "Data store: in-memory — database unreachable. Run `docker compose up -d` (and `npm run db:migrate && npm run db:seed`) for MySQL.",
+        );
+        return createMemoryStore();
+      }
+    })();
+  }
+  return backend;
+}
+
 export const carStore: CarStore = {
   async list() {
-    return (await CarModel.findAll({ order: [["id", "ASC"]] })).map(toCar);
+    return (await resolveBackend()).list();
   },
   async get(id) {
-    const m = await CarModel.findByPk(id);
-    return m ? toCar(m) : null;
+    return (await resolveBackend()).get(id);
   },
   async create(input) {
-    return toCar(await CarModel.create(input));
+    return (await resolveBackend()).create(input);
   },
   async update(id, input) {
-    const m = await CarModel.findByPk(id);
-    if (!m) return null;
-    await m.update(input);
-    return toCar(m);
+    return (await resolveBackend()).update(id, input);
   },
   async remove(id) {
-    const m = await CarModel.findByPk(id);
-    if (!m) return false;
-    await m.destroy();
-    return true;
+    return (await resolveBackend()).remove(id);
   },
 };
 // #endif
 // #if !db
-let nextId = 1;
-const cars = new Map<number, Car>();
-
-export const carStore: CarStore = {
-  async list() {
-    return [...cars.values()].sort((a, b) => a.id - b.id);
-  },
-  async get(id) {
-    return cars.get(id) ?? null;
-  },
-  async create(input) {
-    const car: Car = { id: nextId++, ...input };
-    cars.set(car.id, car);
-    return car;
-  },
-  async update(id, input) {
-    const car = cars.get(id);
-    if (!car) return null;
-    const next: Car = { ...car, ...input };
-    cars.set(id, next);
-    return next;
-  },
-  async remove(id) {
-    return cars.delete(id);
-  },
-};
+export const carStore: CarStore = createMemoryStore();
 // #endif

package/templates/express-api/src/index.ts

@@ -3,12 +3,6 @@ import express from "express";
 
 import { carRouter } from "./cars/routes.js";
 import { env } from "./env.js";
-// #if db
-import { assertConnection } from "@softeneers/db";
-
-import { sequelize } from "./db.js";
-import "./cars/store.js"; // registers the Car model on the connection
-// #endif
 // #if auth
 import { toNodeHandler } from "@softeneers/auth";
 
@@ -38,18 +32,6 @@ app.use(
   },
 );
 
-async function start(): Promise<void> {
-  // #if db
-  await assertConnection(sequelize);
-  await sequelize.sync();
-  console.log("Database connected.");
-  // #endif
-  app.listen(env.PORT, () => {
-    console.log(`API running on http://localhost:${env.PORT}`);
-  });
-}
-
-start().catch((error) => {
-  console.error("Failed to start:", error);
-  process.exit(1);
+app.listen(env.PORT, () => {
+  console.log(`API running on http://localhost:${env.PORT}`);
 });

package/templates/express-api/src/scripts/seed.ts

@@ -2,24 +2,19 @@ import "dotenv/config";
 
 import { assertConnection } from "@softeneers/db";
 
-import { carStore } from "../cars/store.js";
+import { DEMO_CARS } from "../cars/demo.js";
+import { CarModel } from "../cars/store.js";
 import { sequelize } from "../db.js";
 
 await assertConnection(sequelize);
 await sequelize.sync();
 
-const existing = await carStore.list();
-if (existing.length > 0) {
-  console.log(`Skipped seeding — ${existing.length} cars already present.`);
+const count = await CarModel.count();
+if (count > 0) {
+  console.log(`Skipped seeding — ${count} cars already present.`);
 } else {
-  for (const car of [
-    { brand: "Toyota", model: "Corolla", year: 2021 },
-    { brand: "Tesla", model: "Model 3", year: 2023 },
-    { brand: "Ford", model: "Mustang", year: 1969 },
-  ]) {
-    await carStore.create(car);
-  }
-  console.log("Seeded 3 cars.");
+  await CarModel.bulkCreate([...DEMO_CARS]);
+  console.log(`Seeded ${DEMO_CARS.length} cars.`);
 }
 
 await sequelize.close();

package/templates/hono-api/README.md

@@ -43,17 +43,18 @@ curl -X POST localhost:4000/api/cars -H 'content-type: application/json' \
 ## Database
 
 Persistence is MySQL via Sequelize ([`@softeneers/db`](https://www.npmjs.com/package/@softeneers/db)).
-Configure `DB_*` in `.env`, then:
+**`npm run dev` works immediately even without a database** — the store falls back
+to a pre-seeded in-memory one when MySQL is unreachable. To switch on real
+persistence, set `DB_*` in `.env` and start MySQL:
 
 ```bash
 # #if docker
 docker compose up -d   # start MySQL
 # #endif
+# The app auto-creates and seeds tables on first connect; these scripts give
+# you explicit control (e.g. reseeding or a clean reset):
 npm run db:migrate && npm run db:seed
 ```
-
-Generate with `--no-db` to swap in a dependency-free in-memory store — the CRUD
-API behaves identically.
 # #endif
 # #if auth
 
@@ -67,11 +68,10 @@ mounted at `/api/auth/*`. Set a strong `AUTH_SECRET` in `.env` before deploying.
 
 ```bash
 npm install
-# #if docker
-docker compose up -d
-# #endif
+npm run dev          # a pre-seeded CRUD demo — no other setup needed
+```
 # #if db
-npm run db:migrate && npm run db:seed
+
+The app starts immediately on an in-memory demo and uses MySQL automatically once
+it's reachable — see **Database** above to enable persistence.
 # #endif
-npm run dev
-```

package/templates/hono-api/softeneers.template.json

@@ -1,5 +1,5 @@
 {
-  "toggles": { "db": true, "auth": false, "docker": true },
+  "toggles": { "db": false, "auth": false, "docker": false },
   "fragments": {
     "db": {
       "removePaths": ["src/db.ts", "src/scripts", "docker-compose.yml"],

package/templates/hono-api/src/cars/demo.ts

@@ -0,0 +1,10 @@
+import type { NewCar } from "./types.js";
+
+// Demo garage inventory seeded on first run so `npm run dev` shows a working
+// CRUD demo immediately — into MySQL when a database is reachable, otherwise
+// into the in-memory store.
+export const DEMO_CARS: NewCar[] = [
+  { brand: "Toyota", model: "Corolla", year: 2021 },
+  { brand: "Tesla", model: "Model 3", year: 2023 },
+  { brand: "Ford", model: "Mustang", year: 1969 },
+];

package/templates/hono-api/src/cars/store.ts

@@ -1,8 +1,10 @@
+import { DEMO_CARS } from "./demo.js";
 import type { Car, NewCar } from "./types.js";
 
-// The data layer behind the CRUD routes. With the `db` toggle on this is backed
-// by MySQL (Sequelize via @softeneers/db); with it off it's an in-memory Map so
-// the API runs with zero infrastructure. Both satisfy the same CarStore.
+// The data layer behind the CRUD routes. With the `db` toggle on it persists to
+// MySQL (Sequelize via @softeneers/db) and **falls back to an in-memory store if
+// the database is unreachable**, so `npm run dev` always yields a working,
+// pre-seeded demo. With `db` off it is always in-memory.
 export interface CarStore {
   list(): Promise<Car[]>;
   get(id: number): Promise<Car | null>;
@@ -11,8 +13,43 @@ export interface CarStore {
   remove(id: number): Promise<boolean>;
 }
 
+// In-memory backend (the default, and the fallback when no database is reachable).
+function createMemoryStore(seed = true): CarStore {
+  let nextId = 1;
+  const cars = new Map<number, Car>();
+  if (seed) {
+    for (const car of DEMO_CARS) {
+      const id = nextId++;
+      cars.set(id, { id, ...car });
+    }
+  }
+  return {
+    async list() {
+      return [...cars.values()].sort((a, b) => a.id - b.id);
+    },
+    async get(id) {
+      return cars.get(id) ?? null;
+    },
+    async create(input) {
+      const car: Car = { id: nextId++, ...input };
+      cars.set(car.id, car);
+      return car;
+    },
+    async update(id, input) {
+      const car = cars.get(id);
+      if (!car) return null;
+      const next: Car = { ...car, ...input };
+      cars.set(id, next);
+      return next;
+    },
+    async remove(id) {
+      return cars.delete(id);
+    },
+  };
+}
+
 // #if db
-import { DataTypes, Model } from "@softeneers/db";
+import { assertConnection, DataTypes, Model } from "@softeneers/db";
 
 import { sequelize } from "../db.js";
 
@@ -37,56 +74,77 @@ export { CarModel };
 
 const toCar = (m: CarModel): Car => ({ id: m.id, brand: m.brand, model: m.model, year: m.year });
 
+function createDbStore(): CarStore {
+  return {
+    async list() {
+      return (await CarModel.findAll({ order: [["id", "ASC"]] })).map(toCar);
+    },
+    async get(id) {
+      const m = await CarModel.findByPk(id);
+      return m ? toCar(m) : null;
+    },
+    async create(input) {
+      return toCar(await CarModel.create(input));
+    },
+    async update(id, input) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return null;
+      await m.update(input);
+      return toCar(m);
+    },
+    async remove(id) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return false;
+      await m.destroy();
+      return true;
+    },
+  };
+}
+
+// Resolve the backend once, lazily, on first use: try MySQL (create tables +
+// seed if empty); on any connection error, fall back to the in-memory store.
+let backend: Promise<CarStore> | null = null;
+function resolveBackend(): Promise<CarStore> {
+  if (!backend) {
+    backend = (async () => {
+      try {
+        await assertConnection(sequelize);
+        await sequelize.sync();
+        const db = createDbStore();
+        if ((await db.list()).length === 0) {
+          for (const car of DEMO_CARS) await db.create(car);
+        }
+        console.log("Data store: MySQL");
+        return db;
+      } catch {
+        console.warn(
+          "Data store: in-memory — database unreachable. Run `docker compose up -d` (and `npm run db:migrate && npm run db:seed`) for MySQL.",
+        );
+        return createMemoryStore();
+      }
+    })();
+  }
+  return backend;
+}
+
 export const carStore: CarStore = {
   async list() {
-    return (await CarModel.findAll({ order: [["id", "ASC"]] })).map(toCar);
+    return (await resolveBackend()).list();
   },
   async get(id) {
-    const m = await CarModel.findByPk(id);
-    return m ? toCar(m) : null;
+    return (await resolveBackend()).get(id);
   },
   async create(input) {
-    return toCar(await CarModel.create(input));
+    return (await resolveBackend()).create(input);
   },
   async update(id, input) {
-    const m = await CarModel.findByPk(id);
-    if (!m) return null;
-    await m.update(input);
-    return toCar(m);
+    return (await resolveBackend()).update(id, input);
   },
   async remove(id) {
-    const m = await CarModel.findByPk(id);
-    if (!m) return false;
-    await m.destroy();
-    return true;
+    return (await resolveBackend()).remove(id);
   },
 };
 // #endif
 // #if !db
-let nextId = 1;
-const cars = new Map<number, Car>();
-
-export const carStore: CarStore = {
-  async list() {
-    return [...cars.values()].sort((a, b) => a.id - b.id);
-  },
-  async get(id) {
-    return cars.get(id) ?? null;
-  },
-  async create(input) {
-    const car: Car = { id: nextId++, ...input };
-    cars.set(car.id, car);
-    return car;
-  },
-  async update(id, input) {
-    const car = cars.get(id);
-    if (!car) return null;
-    const next: Car = { ...car, ...input };
-    cars.set(id, next);
-    return next;
-  },
-  async remove(id) {
-    return cars.delete(id);
-  },
-};
+export const carStore: CarStore = createMemoryStore();
 // #endif

package/templates/hono-api/src/index.ts

@@ -4,12 +4,6 @@ import { cors } from "hono/cors";
 
 import { cars } from "./cars/routes.js";
 import { env } from "./env.js";
-// #if db
-import { assertConnection } from "@softeneers/db";
-
-import { sequelize } from "./db.js";
-import "./cars/store.js"; // registers the Car model on the connection
-// #endif
 // #if auth
 import { auth } from "./auth/auth.js";
 // #endif
@@ -27,18 +21,6 @@ app.route("/api/cars", cars);
 app.on(["GET", "POST"], "/api/auth/*", (c) => auth.handler(c.req.raw));
 // #endif
 
-async function start(): Promise<void> {
-  // #if db
-  await assertConnection(sequelize);
-  await sequelize.sync();
-  console.log("Database connected.");
-  // #endif
-  serve({ fetch: app.fetch, port: env.PORT }, (info) => {
-    console.log(`API running on http://localhost:${info.port}`);
-  });
-}
-
-start().catch((error) => {
-  console.error("Failed to start:", error);
-  process.exit(1);
+serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+  console.log(`API running on http://localhost:${info.port}`);
 });

package/templates/hono-api/src/scripts/seed.ts

@@ -2,24 +2,19 @@ import "dotenv/config";
 
 import { assertConnection } from "@softeneers/db";
 
-import { carStore } from "../cars/store.js";
+import { DEMO_CARS } from "../cars/demo.js";
+import { CarModel } from "../cars/store.js";
 import { sequelize } from "../db.js";
 
 await assertConnection(sequelize);
 await sequelize.sync();
 
-const existing = await carStore.list();
-if (existing.length > 0) {
-  console.log(`Skipped seeding — ${existing.length} cars already present.`);
+const count = await CarModel.count();
+if (count > 0) {
+  console.log(`Skipped seeding — ${count} cars already present.`);
 } else {
-  for (const car of [
-    { brand: "Toyota", model: "Corolla", year: 2021 },
-    { brand: "Tesla", model: "Model 3", year: 2023 },
-    { brand: "Ford", model: "Mustang", year: 1969 },
-  ]) {
-    await carStore.create(car);
-  }
-  console.log("Seeded 3 cars.");
+  await CarModel.bulkCreate([...DEMO_CARS]);
+  console.log(`Seeded ${DEMO_CARS.length} cars.`);
 }
 
 await sequelize.close();

package/templates/tanstack-start/README.md

@@ -39,16 +39,18 @@ functions — no hand-written API client, end-to-end type safety.
 ## Database
 
 Persistence is MySQL via Sequelize ([`@softeneers/db`](https://www.npmjs.com/package/@softeneers/db)).
-Set `DB_*` in `.env`, then:
+**`npm run dev` works immediately even without a database** — the server falls
+back to a pre-seeded in-memory store when MySQL is unreachable. To switch on real
+persistence, set `DB_*` in `.env` and start MySQL:
 
 ```bash
 # #if docker
 docker compose up -d   # start MySQL
 # #endif
+# The server auto-creates and seeds tables on first connect; these scripts give
+# you explicit control:
 npm run db:migrate && npm run db:seed
 ```
-
-Generate with `--no-db` to use a dependency-free in-memory store instead.
 # #endif
 # #if auth
 
@@ -63,11 +65,10 @@ served at `/api/auth/*`. Set a strong `AUTH_SECRET` in `.env`, and add the
 
 ```bash
 npm install
-# #if docker
-docker compose up -d
-# #endif
+npm run dev          # a pre-seeded CRUD demo on http://localhost:3000 — no other setup
+```
 # #if db
-npm run db:migrate && npm run db:seed
+
+The app starts immediately on an in-memory demo and uses MySQL automatically once
+it's reachable — see **Database** above to enable persistence.
 # #endif
-npm run dev
-```

package/templates/tanstack-start/softeneers.template.json

@@ -1,5 +1,5 @@
 {
-  "toggles": { "db": true, "auth": false, "docker": true },
+  "toggles": { "db": false, "auth": false, "docker": false },
   "fragments": {
     "db": {
       "removePaths": ["src/server/db.ts", "src/server/scripts", "docker-compose.yml"],

package/templates/tanstack-start/src/server/demo.ts

@@ -0,0 +1,9 @@
+import type { NewCar } from '../cars/types'
+
+// Demo garage inventory seeded on first run so `npm run dev` shows a working
+// CRUD demo immediately — into MySQL when reachable, else the in-memory store.
+export const DEMO_CARS: NewCar[] = [
+  { brand: 'Toyota', model: 'Corolla', year: 2021 },
+  { brand: 'Tesla', model: 'Model 3', year: 2023 },
+  { brand: 'Ford', model: 'Mustang', year: 1969 },
+]

package/templates/tanstack-start/src/server/scripts/seed.ts

@@ -2,24 +2,19 @@ import 'dotenv/config'
 
 import { assertConnection } from '@softeneers/db'
 
+import { DEMO_CARS } from '../demo'
 import { sequelize } from '../db'
-import { carStore } from '../store'
+import { CarModel } from '../store'
 
 await assertConnection(sequelize)
 await sequelize.sync()
 
-const existing = await carStore.list()
-if (existing.length > 0) {
-  console.log(`Skipped seeding — ${existing.length} cars already present.`)
+const count = await CarModel.count()
+if (count > 0) {
+  console.log(`Skipped seeding — ${count} cars already present.`)
 } else {
-  for (const car of [
-    { brand: 'Toyota', model: 'Corolla', year: 2021 },
-    { brand: 'Tesla', model: 'Model 3', year: 2023 },
-    { brand: 'Ford', model: 'Mustang', year: 1969 },
-  ]) {
-    await carStore.create(car)
-  }
-  console.log('Seeded 3 cars.')
+  await CarModel.bulkCreate([...DEMO_CARS])
+  console.log(`Seeded ${DEMO_CARS.length} cars.`)
 }
 
 await sequelize.close()

package/templates/tanstack-start/src/server/store.ts

@@ -1,9 +1,11 @@
 import type { Car, NewCar } from '../cars/types'
+import { DEMO_CARS } from './demo'
 
-// Server-only data layer behind the cars server functions. With `db` on it is
-// backed by MySQL (Sequelize via @softeneers/db); with it off it is an in-memory
-// Map. Both satisfy the same CarStore. This module is never bundled into the
-// client — it is only reached from server functions.
+// Server-only data layer behind the cars server functions. With `db` on it
+// persists to MySQL (Sequelize via @softeneers/db) and **falls back to an
+// in-memory store if the database is unreachable**, so `npm run dev` always
+// yields a working, pre-seeded demo. With `db` off it is always in-memory.
+// Never bundled into the client — only reached from server functions.
 export interface CarStore {
   list(): Promise<Array<Car>>
   get(id: number): Promise<Car | null>
@@ -11,8 +13,34 @@ export interface CarStore {
   remove(id: number): Promise<boolean>
 }
 
+// In-memory backend (the default, and the fallback when no database is reachable).
+function createMemoryStore(): CarStore {
+  let nextId = 1
+  const cars = new Map<number, Car>()
+  for (const car of DEMO_CARS) {
+    const id = nextId++
+    cars.set(id, { id, ...car })
+  }
+  return {
+    async list() {
+      return [...cars.values()].sort((a, b) => a.id - b.id)
+    },
+    async get(id) {
+      return cars.get(id) ?? null
+    },
+    async create(input) {
+      const car: Car = { id: nextId++, ...input }
+      cars.set(car.id, car)
+      return car
+    },
+    async remove(id) {
+      return cars.delete(id)
+    },
+  }
+}
+
 // #if db
-import { DataTypes, Model } from '@softeneers/db'
+import { DataTypes, Model, assertConnection } from '@softeneers/db'
 
 import { sequelize } from './db'
 
@@ -37,43 +65,68 @@ export { CarModel }
 
 const toCar = (m: CarModel): Car => ({ id: m.id, brand: m.brand, model: m.model, year: m.year })
 
-export const carStore: CarStore = {
-  async list() {
-    return (await CarModel.findAll({ order: [['id', 'ASC']] })).map(toCar)
-  },
-  async get(id) {
-    const m = await CarModel.findByPk(id)
-    return m ? toCar(m) : null
-  },
-  async create(input) {
-    return toCar(await CarModel.create(input))
-  },
-  async remove(id) {
-    const m = await CarModel.findByPk(id)
-    if (!m) return false
-    await m.destroy()
-    return true
-  },
+function createDbStore(): CarStore {
+  return {
+    async list() {
+      return (await CarModel.findAll({ order: [['id', 'ASC']] })).map(toCar)
+    },
+    async get(id) {
+      const m = await CarModel.findByPk(id)
+      return m ? toCar(m) : null
+    },
+    async create(input) {
+      return toCar(await CarModel.create(input))
+    },
+    async remove(id) {
+      const m = await CarModel.findByPk(id)
+      if (!m) return false
+      await m.destroy()
+      return true
+    },
+  }
+}
+
+// Resolve the backend once, lazily, on first use: try MySQL (create tables +
+// seed if empty); on any connection error, fall back to the in-memory store.
+let backend: Promise<CarStore> | null = null
+function resolveBackend(): Promise<CarStore> {
+  if (!backend) {
+    backend = (async () => {
+      try {
+        await assertConnection(sequelize)
+        await sequelize.sync()
+        const db = createDbStore()
+        if ((await db.list()).length === 0) {
+          for (const car of DEMO_CARS) await db.create(car)
+        }
+        console.log('Data store: MySQL')
+        return db
+      } catch {
+        console.warn(
+          'Data store: in-memory — database unreachable. Run `docker compose up -d` (and `npm run db:migrate && npm run db:seed`) for MySQL.',
+        )
+        return createMemoryStore()
+      }
+    })()
+  }
+  return backend
 }
-// #endif
-// #if !db
-let nextId = 1
-const cars = new Map<number, Car>()
 
 export const carStore: CarStore = {
   async list() {
-    return [...cars.values()].sort((a, b) => a.id - b.id)
+    return (await resolveBackend()).list()
   },
   async get(id) {
-    return cars.get(id) ?? null
+    return (await resolveBackend()).get(id)
   },
   async create(input) {
-    const car: Car = { id: nextId++, ...input }
-    cars.set(car.id, car)
-    return car
+    return (await resolveBackend()).create(input)
   },
   async remove(id) {
-    return cars.delete(id)
+    return (await resolveBackend()).remove(id)
   },
 }
 // #endif
+// #if !db
+export const carStore: CarStore = createMemoryStore()
+// #endif