Initial scaffold: Turborepo monorepo + design wiki

Turborepo (pnpm workspaces) with all dependencies pinned to latest
mutually-compatible versions: turbo 2.9, TypeScript 6, Fastify 5,
React 19, Vite 8, better-sqlite3 12 + Drizzle ORM 0.45.

Layout:
- apps/server   Fastify backend (local JWT auth + role guard, /health)
- apps/web      React 19 + Vite 8 operator SPA
- packages/db   Drizzle schema on SQLite/WAL; append-only events + users
- packages/devices  reader/printer/relay adapter interfaces (intent-only relay)
- packages/shared   shared domain types

Architecture constraints from the design wiki are encoded in the scaffold:
append-only hash-chained + signed event log, device-agnostic adapters,
"a barrier is not a door" (relay expresses intent only), fully-local
offline-first auth.

wiki/ is an LLM-maintained Obsidian knowledge base (28 pages) ingested
from the architecture & design notes, with its own maintenance schema.

Verified: pnpm install, full turbo build (5/5), server boots and serves
/health, drizzle-kit generates the initial migration.

apps/server/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@parking/server",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "node --watch --experimental-strip-types src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@parking/db": "workspace:*",
+    "@parking/devices": "workspace:*",
+    "@parking/shared": "workspace:*",
+    "@fastify/cors": "11.2.0",
+    "@fastify/jwt": "10.1.0",
+    "@fastify/static": "9.1.3",
+    "bcrypt": "6.0.0",
+    "fastify": "5.8.5",
+    "fastify-plugin": "6.0.0"
+  },
+  "devDependencies": {
+    "@types/bcrypt": "6.0.0",
+    "@types/node": "25.9.3",
+    "typescript": "6.0.3"
+  }
+}

apps/server/src/index.ts

@@ -0,0 +1,13 @@
+import { buildServer } from "./server.js";
+
+const PORT = Number(process.env.PORT ?? 3000);
+const HOST = process.env.HOST ?? "0.0.0.0";
+
+const app = await buildServer();
+
+try {
+  await app.listen({ port: PORT, host: HOST });
+} catch (err) {
+  app.log.error(err);
+  process.exit(1);
+}

apps/server/src/server.ts

@@ -0,0 +1,45 @@
+import jwt from "@fastify/jwt";
+import Fastify, { type FastifyInstance } from "fastify";
+import type { Role } from "@parking/shared";
+
+// The backend is Fastify (Node). Hardware drivers live as isolated Fastify
+// plugins emitting onto a shared internal event bus; auth is fully local
+// (offline-first). See wiki/entities/fastify.md and local-jwt-auth.md.
+
+declare module "@fastify/jwt" {
+  interface FastifyJWT {
+    payload: { sub: string; username: string; role: Role };
+    user: { sub: string; username: string; role: Role };
+  }
+}
+
+export async function buildServer(): Promise<FastifyInstance> {
+  const app = Fastify({
+    logger: { level: process.env.LOG_LEVEL ?? "info" },
+  });
+
+  // Local JWT signing with a local secret — no external identity provider.
+  await app.register(jwt, {
+    secret: process.env.JWT_SECRET ?? "dev-only-insecure-secret-change-me",
+  });
+
+  app.get("/health", async () => ({ status: "ok" }));
+
+  // TODO: register device-driver plugins (packages/devices adapters),
+  // the append-only event-log routes, and the role-guarded admin API.
+
+  return app;
+}
+
+/**
+ * preHandler role guard. Authorization is a simple per-route role check — no
+ * Casbin/RBAC engine needed at this scale. See wiki/entities/local-jwt-auth.md.
+ */
+export function requireRole(...allowed: Role[]) {
+  return async (req: { jwtVerify: () => Promise<void>; user?: { role: Role } }) => {
+    await req.jwtVerify();
+    if (!req.user || !allowed.includes(req.user.role)) {
+      throw Object.assign(new Error("forbidden"), { statusCode: 403 });
+    }
+  };
+}

apps/server/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "references": [
+    { "path": "../../packages/shared" },
+    { "path": "../../packages/db" },
+    { "path": "../../packages/devices" }
+  ],
+  "include": ["src/**/*"]
+}

apps/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Parking System</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/web/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@parking/web",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@parking/shared": "workspace:*",
+    "react": "19.2.7",
+    "react-dom": "19.2.7"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "6.0.2",
+    "typescript": "6.0.3",
+    "vite": "8.0.16"
+  }
+}

apps/web/src/App.tsx

@@ -0,0 +1,26 @@
+import { useEffect, useState } from "react";
+
+// Operator UI shell. Plain React (no admin framework) — the operator UI is
+// simple enough that a framework's abstractions cost more than they save.
+// See wiki/entities/react-vite-spa.md.
+
+export function App() {
+  const [health, setHealth] = useState<string>("checking…");
+
+  useEffect(() => {
+    fetch("/health")
+      .then((r) => r.json())
+      .then((d: { status: string }) => setHealth(d.status))
+      .catch(() => setHealth("unreachable"));
+  }, []);
+
+  return (
+    <main style={{ fontFamily: "system-ui", padding: "2rem" }}>
+      <h1>Parking System</h1>
+      <p>Operator console — scaffold.</p>
+      <p>
+        API health: <strong>{health}</strong>
+      </p>
+    </main>
+  );
+}

apps/web/src/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.js";
+
+const rootEl = document.getElementById("root");
+if (!rootEl) throw new Error("root element not found");
+
+createRoot(rootEl).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

apps/web/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

apps/web/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "references": [{ "path": "../../packages/shared" }],
+  "include": ["src/**/*", "vite.config.ts"]
+}

apps/web/vite.config.ts

@@ -0,0 +1,19 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// Operator SPA. Built by Vite and served by Fastify in production
+// (see wiki/entities/react-vite-spa.md). The dev proxy points the API at the
+// local Fastify server.
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": "http://localhost:3000",
+      "/health": "http://localhost:3000",
+    },
+  },
+  build: {
+    outDir: "dist",
+  },
+});