Initial implementation of Bluetooth toy control app

Next.js app with a browser-side buttplug/buttplug-wasm control layer
(server never touches real-time device commands), SQLite storage via
Drizzle, single-secret auth, recordings/replay with device remapping,
a usage stats dashboard, Docker deployment, and Gitea CI.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W8WkFF5ppURBAB918593Eb

lib/db/client.ts

@@ -0,0 +1,43 @@
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { getEnv } from "@/lib/env";
+import * as schema from "./schema";
+
+const globalForDb = globalThis as unknown as { __bpSqlite?: Database.Database };
+
+function openDatabase(): Database.Database {
+  if (globalForDb.__bpSqlite) return globalForDb.__bpSqlite;
+
+  const path = getEnv().DATABASE_PATH;
+  mkdirSync(dirname(path), { recursive: true });
+
+  const instance = new Database(path);
+  instance.pragma("journal_mode = WAL");
+  instance.pragma("foreign_keys = ON");
+
+  // Reused across hot-reloads in dev so we don't leak file handles / open a
+  // fresh WAL-mode connection on every request.
+  globalForDb.__bpSqlite = instance;
+  return instance;
+}
+
+// Lazy by design: `next build` imports this module's whole graph while
+// collecting route metadata, even for force-dynamic pages that are never
+// actually rendered at build time. Opening the DB (and requiring env vars)
+// as a module-level side effect would make `pnpm build` fail in CI, where
+// no secrets are configured. The proxy defers both until first real query.
+export const sqlite = new Proxy({} as Database.Database, {
+  get(_target, prop) {
+    // drizzle-orm's `isConfig()` probes `.constructor.name` on its first
+    // argument to tell a client instance from a plain config object - that
+    // introspection must not itself trigger opening the real connection.
+    if (prop === "constructor") return Database;
+    const instance = openDatabase();
+    const value = Reflect.get(instance, prop, instance);
+    return typeof value === "function" ? value.bind(instance) : value;
+  },
+}) as Database.Database;
+
+export const db = drizzle(sqlite, { schema });

lib/db/migrate.ts

@@ -0,0 +1,10 @@
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import { db } from "./client";
+import { createLogger } from "@/lib/logger";
+
+const log = createLogger("db:migrate");
+
+export function runMigrations(): void {
+  migrate(db, { migrationsFolder: "./drizzle" });
+  log.info("migrations applied");
+}

lib/db/queries/devices.ts

@@ -0,0 +1,52 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { devices, type DeviceCapabilities } from "@/lib/db/schema";
+
+export async function listDevices() {
+  return db.select().from(devices).orderBy(devices.lastConnectedAt);
+}
+
+export async function getDevice(id: number) {
+  const [row] = await db.select().from(devices).where(eq(devices.id, id));
+  return row;
+}
+
+/** Upserts by advertised BLE name - the only stable-ish identity Web Bluetooth exposes. */
+export async function upsertDeviceByBleName(input: {
+  bleName: string;
+  deviceClass?: string | null;
+  capabilities?: DeviceCapabilities;
+}): Promise<typeof devices.$inferSelect> {
+  const now = Date.now();
+  const [existing] = await db.select().from(devices).where(eq(devices.bleName, input.bleName));
+
+  if (existing) {
+    const [updated] = await db
+      .update(devices)
+      .set({
+        lastConnectedAt: now,
+        deviceClass: input.deviceClass ?? existing.deviceClass,
+        capabilities: input.capabilities ?? existing.capabilities,
+      })
+      .where(eq(devices.id, existing.id))
+      .returning();
+    return updated;
+  }
+
+  const [created] = await db
+    .insert(devices)
+    .values({
+      bleName: input.bleName,
+      deviceClass: input.deviceClass,
+      capabilities: input.capabilities,
+      createdAt: now,
+      lastConnectedAt: now,
+    })
+    .returning();
+  return created;
+}
+
+export async function renameDevice(id: number, displayName: string) {
+  const [updated] = await db.update(devices).set({ displayName }).where(eq(devices.id, id)).returning();
+  return updated;
+}

lib/db/queries/play-sessions.ts

@@ -0,0 +1,112 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { playSessions, sessionDevices, devices } from "@/lib/db/schema";
+import { upsertDeviceByBleName } from "./devices";
+import { incrementPlayCount } from "./recordings";
+import type { DeviceCapabilities } from "@/lib/db/schema";
+
+export interface StartSessionDeviceInput {
+  slotLabel: string;
+  bleName: string;
+  deviceClass?: string | null;
+  capabilities?: DeviceCapabilities;
+}
+
+export interface StartSessionInput {
+  kind: "live" | "replay";
+  replayedRecordingId?: number;
+  name?: string;
+  devices: StartSessionDeviceInput[];
+}
+
+export async function startPlaySession(input: StartSessionInput) {
+  const now = Date.now();
+
+  const [session] = await db
+    .insert(playSessions)
+    .values({
+      kind: input.kind,
+      replayedRecordingId: input.replayedRecordingId,
+      name: input.name,
+      status: "active",
+      startedAt: now,
+    })
+    .returning();
+
+  const sessionDeviceRows = [];
+  for (const d of input.devices) {
+    const device = await upsertDeviceByBleName({
+      bleName: d.bleName,
+      deviceClass: d.deviceClass,
+      capabilities: d.capabilities,
+    });
+    const [sessionDevice] = await db
+      .insert(sessionDevices)
+      .values({
+        playSessionId: session.id,
+        deviceId: device.id,
+        slotLabel: d.slotLabel,
+        connectedAt: now,
+      })
+      .returning();
+    sessionDeviceRows.push(sessionDevice);
+  }
+
+  if (input.kind === "replay" && input.replayedRecordingId) {
+    await incrementPlayCount(input.replayedRecordingId, now);
+  }
+
+  return { session, sessionDevices: sessionDeviceRows };
+}
+
+export async function endPlaySession(
+  id: number,
+  input: { status: "completed" | "aborted" },
+) {
+  const [existing] = await db.select().from(playSessions).where(eq(playSessions.id, id));
+  if (!existing) return undefined;
+
+  const endedAt = Date.now();
+  const durationMs = endedAt - existing.startedAt;
+
+  await db
+    .update(sessionDevices)
+    .set({ disconnectedAt: endedAt })
+    .where(eq(sessionDevices.playSessionId, id));
+
+  const [updated] = await db
+    .update(playSessions)
+    .set({ endedAt, durationMs, status: input.status })
+    .where(eq(playSessions.id, id))
+    .returning();
+  return updated;
+}
+
+export async function listPlaySessions() {
+  return db.select().from(playSessions).orderBy(playSessions.startedAt);
+}
+
+export async function getPlaySessionDetail(id: number) {
+  const [session] = await db.select().from(playSessions).where(eq(playSessions.id, id));
+  if (!session) return undefined;
+
+  const sessionDeviceRows = await db
+    .select({
+      id: sessionDevices.id,
+      slotLabel: sessionDevices.slotLabel,
+      connectedAt: sessionDevices.connectedAt,
+      disconnectedAt: sessionDevices.disconnectedAt,
+      deviceId: devices.id,
+      deviceDisplayName: devices.displayName,
+      deviceBleName: devices.bleName,
+    })
+    .from(sessionDevices)
+    .innerJoin(devices, eq(sessionDevices.deviceId, devices.id))
+    .where(eq(sessionDevices.playSessionId, id));
+
+  return { session, devices: sessionDeviceRows };
+}
+
+export async function deletePlaySession(id: number) {
+  await db.delete(playSessions).where(eq(playSessions.id, id));
+}

lib/db/queries/recordings.ts

@@ -0,0 +1,86 @@
+import { desc, eq } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { recordings, sessionDevices, devices, playSessions, type RecordingDeviceSlot } from "@/lib/db/schema";
+import { getEventsForSession } from "./session-events";
+
+/**
+ * A recording is a thin pointer over an already-captured play_session, not a
+ * duplicated event pipeline: every live command is always persisted to
+ * session_events (stats need it regardless of whether the user saves a
+ * recording), so "saving a recording" just snapshots the session's device
+ * slots and points a new row at it. This keeps the replay-loader query and
+ * the stats-timeline query reading the exact same rows, with zero risk of
+ * live/recorded data drifting apart.
+ */
+export async function createRecording(input: {
+  sourcePlaySessionId: number;
+  name: string;
+  description?: string;
+}) {
+  const [session] = await db.select().from(playSessions).where(eq(playSessions.id, input.sourcePlaySessionId));
+  if (!session) throw new Error("source play session not found");
+
+  const sessionDeviceRows = await db
+    .select({
+      sessionDeviceId: sessionDevices.id,
+      slotLabel: sessionDevices.slotLabel,
+      bleName: devices.bleName,
+      deviceClass: devices.deviceClass,
+      capabilities: devices.capabilities,
+    })
+    .from(sessionDevices)
+    .innerJoin(devices, eq(sessionDevices.deviceId, devices.id))
+    .where(eq(sessionDevices.playSessionId, input.sourcePlaySessionId));
+
+  const deviceSlots: RecordingDeviceSlot[] = sessionDeviceRows.map((row) => ({
+    slotLabel: row.slotLabel,
+    recordedBleName: row.bleName,
+    deviceClass: row.deviceClass,
+    capabilities: row.capabilities,
+    sourceSessionDeviceId: row.sessionDeviceId,
+  }));
+
+  const [recording] = await db
+    .insert(recordings)
+    .values({
+      sourcePlaySessionId: input.sourcePlaySessionId,
+      name: input.name,
+      description: input.description,
+      createdAt: Date.now(),
+      durationMs: session.durationMs ?? 0,
+      deviceSlots,
+      playCount: 0,
+    })
+    .returning();
+
+  return recording;
+}
+
+export async function listRecordings() {
+  return db.select().from(recordings).orderBy(desc(recordings.createdAt));
+}
+
+export async function getRecording(id: number) {
+  const [recording] = await db.select().from(recordings).where(eq(recordings.id, id));
+  if (!recording) return undefined;
+  const events = await getEventsForSession(recording.sourcePlaySessionId);
+  return { recording, events };
+}
+
+export async function renameRecording(id: number, input: { name?: string; description?: string }) {
+  const [updated] = await db.update(recordings).set(input).where(eq(recordings.id, id)).returning();
+  return updated;
+}
+
+export async function deleteRecording(id: number) {
+  await db.delete(recordings).where(eq(recordings.id, id));
+}
+
+export async function incrementPlayCount(id: number, playedAt: number): Promise<void> {
+  const [existing] = await db.select().from(recordings).where(eq(recordings.id, id));
+  if (!existing) return;
+  await db
+    .update(recordings)
+    .set({ playCount: existing.playCount + 1, lastPlayedAt: playedAt })
+    .where(eq(recordings.id, id));
+}

lib/db/queries/session-events.ts

@@ -0,0 +1,42 @@
+import { asc, eq } from "drizzle-orm";
+import { db, sqlite } from "@/lib/db/client";
+import { sessionEvents } from "@/lib/db/schema";
+
+export interface IncomingEvent {
+  sessionDeviceId: number;
+  tsMs: number;
+  commandType: "vibrate" | "rotate" | "linear" | "stop";
+  featureIndex: number;
+  value: number;
+  durationMs?: number;
+}
+
+export async function insertEvents(playSessionId: number, events: IncomingEvent[]): Promise<void> {
+  if (events.length === 0) return;
+
+  const insertMany = sqlite.transaction((rows: IncomingEvent[]) => {
+    for (const row of rows) {
+      db.insert(sessionEvents)
+        .values({
+          playSessionId,
+          sessionDeviceId: row.sessionDeviceId,
+          tsMs: row.tsMs,
+          commandType: row.commandType,
+          featureIndex: row.featureIndex,
+          value: row.value,
+          durationMs: row.durationMs,
+        })
+        .run();
+    }
+  });
+
+  insertMany(events);
+}
+
+export async function getEventsForSession(playSessionId: number) {
+  return db
+    .select()
+    .from(sessionEvents)
+    .where(eq(sessionEvents.playSessionId, playSessionId))
+    .orderBy(asc(sessionEvents.tsMs));
+}

lib/db/queries/stats.ts

@@ -0,0 +1,103 @@
+import { sql, eq, and, ne } from "drizzle-orm";
+import { db } from "@/lib/db/client";
+import { playSessions, sessionDevices, sessionEvents, devices, recordings } from "@/lib/db/schema";
+
+export async function getSessionsSummary() {
+  const [totals] = await db
+    .select({
+      count: sql<number>`count(*)`,
+      totalDurationMs: sql<number>`coalesce(sum(${playSessions.durationMs}), 0)`,
+      avgDurationMs: sql<number>`coalesce(avg(${playSessions.durationMs}), 0)`,
+    })
+    .from(playSessions)
+    .where(eq(playSessions.status, "completed"));
+
+  const byKind = await db
+    .select({
+      kind: playSessions.kind,
+      count: sql<number>`count(*)`,
+      totalDurationMs: sql<number>`coalesce(sum(${playSessions.durationMs}), 0)`,
+    })
+    .from(playSessions)
+    .where(eq(playSessions.status, "completed"))
+    .groupBy(playSessions.kind);
+
+  const durationPerDevice = await db
+    .select({
+      deviceId: devices.id,
+      displayName: devices.displayName,
+      bleName: devices.bleName,
+      totalActiveMs: sql<number>`coalesce(sum(coalesce(${sessionDevices.disconnectedAt}, ${sessionDevices.connectedAt}) - ${sessionDevices.connectedAt}), 0)`,
+    })
+    .from(sessionDevices)
+    .innerJoin(devices, eq(sessionDevices.deviceId, devices.id))
+    .groupBy(devices.id);
+
+  return { ...totals, byKind, durationPerDevice };
+}
+
+export async function getSessionTimeline(playSessionId: number, bucketMs = 1000) {
+  return db
+    .select({
+      bucket: sql<number>`(${sessionEvents.tsMs} / ${bucketMs}) * ${bucketMs}`,
+      sessionDeviceId: sessionEvents.sessionDeviceId,
+      slotLabel: sessionDevices.slotLabel,
+      avgValue: sql<number>`avg(${sessionEvents.value})`,
+      maxValue: sql<number>`max(${sessionEvents.value})`,
+    })
+    .from(sessionEvents)
+    .innerJoin(sessionDevices, eq(sessionEvents.sessionDeviceId, sessionDevices.id))
+    .where(and(eq(sessionEvents.playSessionId, playSessionId), ne(sessionEvents.commandType, "stop")))
+    .groupBy(sql`bucket`, sessionEvents.sessionDeviceId)
+    .orderBy(sql`bucket`);
+}
+
+export async function getDeviceUsageStats() {
+  return db
+    .select({
+      deviceId: devices.id,
+      displayName: devices.displayName,
+      bleName: devices.bleName,
+      sessionCount: sql<number>`count(distinct ${sessionDevices.playSessionId})`,
+      totalActiveMs: sql<number>`coalesce(sum(coalesce(${sessionDevices.disconnectedAt}, ${sessionDevices.connectedAt}) - ${sessionDevices.connectedAt}), 0)`,
+      lastUsedAt: sql<number | null>`max(${sessionDevices.connectedAt})`,
+    })
+    .from(devices)
+    .leftJoin(sessionDevices, eq(sessionDevices.deviceId, devices.id))
+    .groupBy(devices.id);
+}
+
+export async function getDeviceCommandCounts() {
+  return db
+    .select({
+      deviceId: devices.id,
+      commandCount: sql<number>`count(${sessionEvents.id})`,
+    })
+    .from(devices)
+    .leftJoin(sessionDevices, eq(sessionDevices.deviceId, devices.id))
+    .leftJoin(sessionEvents, eq(sessionEvents.sessionDeviceId, sessionDevices.id))
+    .groupBy(devices.id);
+}
+
+export async function getRecordingLibraryStats() {
+  const [totals] = await db
+    .select({
+      count: sql<number>`count(*)`,
+      avgDurationMs: sql<number>`coalesce(avg(${recordings.durationMs}), 0)`,
+      totalPlayCount: sql<number>`coalesce(sum(${recordings.playCount}), 0)`,
+    })
+    .from(recordings);
+
+  const list = await db
+    .select({
+      id: recordings.id,
+      name: recordings.name,
+      durationMs: recordings.durationMs,
+      playCount: recordings.playCount,
+      lastPlayedAt: recordings.lastPlayedAt,
+    })
+    .from(recordings)
+    .orderBy(sql`${recordings.playCount} desc`);
+
+  return { ...totals, list };
+}

lib/db/schema.ts

@@ -0,0 +1,104 @@
+import { sqliteTable, text, integer, real, index, type AnySQLiteColumn } from "drizzle-orm/sqlite-core";
+
+export interface DeviceCapabilities {
+  /** Buttplug OutputType strings (Vibrate/Rotate/Position/...) present on any feature. */
+  outputs: string[];
+  featureCount: number;
+}
+
+// No `users` table - the app is gated by a single ACCESS_PASSWORD env var
+// (see lib/auth/session.ts), not a persisted account.
+
+export const devices = sqliteTable("devices", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  displayName: text("display_name"),
+  // Web Bluetooth exposes no stable hardware id, only the advertised name -
+  // this is the best identity key available across browser sessions.
+  bleName: text("ble_name").notNull(),
+  deviceClass: text("device_class"),
+  capabilities: text("capabilities", { mode: "json" }).$type<DeviceCapabilities>(),
+  createdAt: integer("created_at").notNull(),
+  lastConnectedAt: integer("last_connected_at"),
+});
+
+export const playSessions = sqliteTable("play_sessions", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name"),
+  kind: text("kind", { enum: ["live", "replay"] }).notNull(),
+  replayedRecordingId: integer("replayed_recording_id").references((): AnySQLiteColumn => recordings.id, {
+    onDelete: "set null",
+  }),
+  status: text("status", { enum: ["active", "completed", "aborted"] }).notNull().default("active"),
+  startedAt: integer("started_at").notNull(),
+  endedAt: integer("ended_at"),
+  durationMs: integer("duration_ms"),
+  notes: text("notes"),
+});
+
+export const sessionDevices = sqliteTable(
+  "session_devices",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    playSessionId: integer("play_session_id")
+      .notNull()
+      .references(() => playSessions.id, { onDelete: "cascade" }),
+    deviceId: integer("device_id")
+      .notNull()
+      .references(() => devices.id, { onDelete: "restrict" }),
+    slotLabel: text("slot_label").notNull(),
+    connectedAt: integer("connected_at").notNull(),
+    disconnectedAt: integer("disconnected_at"),
+  },
+  (table) => [index("session_devices_play_session_id_idx").on(table.playSessionId)],
+);
+
+export const sessionEvents = sqliteTable(
+  "session_events",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    playSessionId: integer("play_session_id")
+      .notNull()
+      .references(() => playSessions.id, { onDelete: "cascade" }),
+    sessionDeviceId: integer("session_device_id")
+      .notNull()
+      .references(() => sessionDevices.id, { onDelete: "cascade" }),
+    // Relative to the session's startedAt, not wall-clock - keeps timeline
+    // math and replay scheduling drift-free and reproducible.
+    tsMs: integer("ts_ms").notNull(),
+    commandType: text("command_type", { enum: ["vibrate", "rotate", "linear", "stop"] }).notNull(),
+    featureIndex: integer("feature_index").notNull(),
+    value: real("value").notNull(),
+    durationMs: integer("duration_ms"),
+    rawPayload: text("raw_payload", { mode: "json" }),
+  },
+  (table) => [
+    index("session_events_session_ts_idx").on(table.playSessionId, table.tsMs),
+    index("session_events_session_device_idx").on(table.sessionDeviceId),
+  ],
+);
+
+export interface RecordingDeviceSlot {
+  slotLabel: string;
+  recordedBleName: string;
+  deviceClass: string | null;
+  capabilities: DeviceCapabilities | null;
+  /** The original session_devices.id this slot was captured from - lets the
+   *  replay UI map a chosen live device back to this slot's session_events. */
+  sourceSessionDeviceId: number;
+}
+
+export const recordings = sqliteTable("recordings", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  // A recording is a thin pointer over an already-captured play_session, not
+  // a duplicated event pipeline - see lib/db/queries/recordings.ts for why.
+  sourcePlaySessionId: integer("source_play_session_id")
+    .notNull()
+    .references(() => playSessions.id, { onDelete: "restrict" }),
+  name: text("name").notNull(),
+  description: text("description"),
+  createdAt: integer("created_at").notNull(),
+  durationMs: integer("duration_ms").notNull(),
+  deviceSlots: text("device_slots", { mode: "json" }).$type<RecordingDeviceSlot[]>().notNull(),
+  playCount: integer("play_count").notNull().default(0),
+  lastPlayedAt: integer("last_played_at"),
+});