Deploy GitHub commit 302c19c3bb59a508ad8f0b239bf0fca864f37f70

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.env
+.env.*
+!.env.example
+node_modules
+**/dist
+coverage
+playwright-report
+test-results
+.data
+.tmp
+*.log

.env.example

@@ -0,0 +1,8 @@
+NODE_ENV=development
+PORT=7860
+DATA_DIR=/data
+DATABASE_URL=file:/data/database/oloka-dev.db
+APP_VERSION=0.1.0
+GIT_COMMIT_SHA=local
+BUILD_TIMESTAMP=development
+LOG_LEVEL=info

.github/workflows/deploy-hf.yml

@@ -0,0 +1,41 @@
+name: Deploy development Space
+
+on:
+  push:
+    branches: [develop]
+
+permissions:
+  contents: read
+
+jobs:
+  validation:
+    uses: ./.github/workflows/validation.yml
+
+  deploy:
+    needs: validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Hugging Face Hub client
+        run: python -m pip install --disable-pip-version-check huggingface-hub==1.23.0
+      - name: Sync validated commit to Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          test -n "$HF_TOKEN"
+          python - <<'PY'
+          import os
+          from huggingface_hub import HfApi
+
+          HfApi(token=os.environ["HF_TOKEN"]).upload_folder(
+              repo_id="phucsd/Oloka-Video-Dev",
+              repo_type="space",
+              folder_path=".",
+              ignore_patterns=[".git/**", ".git"],
+              delete_patterns="*",
+              commit_message=f"Deploy GitHub commit {os.environ['GITHUB_SHA']}",
+          )
+          PY

.github/workflows/validation.yml

@@ -0,0 +1,38 @@
+name: Validation
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run format:check
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm run test:unit
+      - run: npm run test:integration
+      - run: npm run test:frontend
+      - run: npm run build
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:e2e
+      - name: Build production image
+        run: |
+          docker build \
+            --build-arg APP_VERSION=0.1.0 \
+            --build-arg GIT_COMMIT_SHA=${GITHUB_SHA} \
+            --build-arg BUILD_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
+            -t oloka-video:${GITHUB_SHA} .

.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+coverage/
+.env
+.env.*
+!.env.example
+.data/
+.tmp/
+playwright-report/
+test-results/
+*.log
+.DS_Store

.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+coverage
+playwright-report
+test-results
+package-lock.json

Dockerfile

@@ -0,0 +1,40 @@
+# syntax=docker/dockerfile:1.7
+FROM node:22-bookworm-slim AS dependencies
+WORKDIR /app
+COPY package.json package-lock.json ./
+COPY apps/server/package.json apps/server/package.json
+COPY apps/web/package.json apps/web/package.json
+COPY packages/contracts/package.json packages/contracts/package.json
+COPY packages/design-system/package.json packages/design-system/package.json
+RUN npm ci
+
+FROM dependencies AS build
+COPY . .
+RUN npm run build
+RUN npm prune --omit=dev
+
+FROM node:22-bookworm-slim AS runtime
+ARG APP_VERSION=0.1.0
+ARG GIT_COMMIT_SHA=unknown
+ARG BUILD_TIMESTAMP=unknown
+ENV NODE_ENV=production \
+    PORT=7860 \
+    DATA_DIR=/data \
+    DATABASE_URL=file:/data/database/oloka-dev.db \
+    APP_VERSION=${APP_VERSION} \
+    GIT_COMMIT_SHA=${GIT_COMMIT_SHA} \
+    BUILD_TIMESTAMP=${BUILD_TIMESTAMP} \
+    LOG_LEVEL=info
+WORKDIR /app
+RUN mkdir -p /data/database && chown -R 1000:1000 /data /app
+COPY --from=build --chown=1000:1000 /app/package.json /app/package-lock.json ./
+COPY --from=build --chown=1000:1000 /app/node_modules ./node_modules
+COPY --from=build --chown=1000:1000 /app/apps/server/dist ./apps/server/dist
+COPY --from=build --chown=1000:1000 /app/apps/web/dist ./apps/web/dist
+COPY --from=build --chown=1000:1000 /app/packages/contracts/package.json ./packages/contracts/package.json
+COPY --from=build --chown=1000:1000 /app/packages/contracts/dist ./packages/contracts/dist
+USER 1000:1000
+EXPOSE 7860
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:7860/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"]
+CMD ["node", "apps/server/dist/index.js"]

README.md

@@ -1,10 +1,97 @@
 ---
-title: Oloka Video Dev
-emoji: 🔥
-colorFrom: red
-colorTo: indigo
+title: Oloka Video
+emoji: 🎬
+colorFrom: green
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Oloka Video
+
+Oloka Video is a greenfield TypeScript modular monolith. This foundation hosts a React frontend and a Fastify API in one Docker image on port `7860`, with explicit database, storage, contract, and design-system boundaries.
+
+## Repository layout
+
+- `apps/web` — React status experience built by Vite.
+- `apps/server` — Fastify API and production static-file host.
+- `packages/contracts` — shared Zod API schemas and TypeScript types.
+- `packages/design-system` — design tokens and reusable UI primitives.
+- `docs/architecture` — architecture and operations guides.
+- `docs/decisions` — architecture decision records.
+
+## Run locally
+
+Requirements: Node.js 22+, npm 10+, and a writable data directory.
+
+```bash
+npm ci
+npm run dev
+```
+
+The API listens on `http://localhost:7860`; Vite serves the local frontend on `http://localhost:5173` and proxies `/api` to the backend. On Windows, override the Linux online defaults:
+
+```powershell
+$env:DATA_DIR = "$PWD\.data"
+$env:DATABASE_URL = "file:$($PWD.Path.Replace('\','/'))/.data/database/oloka-dev.db"
+npm run dev
+```
+
+Run all local validation:
+
+```bash
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm run test:e2e
+```
+
+## Build and run Docker
+
+```bash
+docker build \
+  --build-arg APP_VERSION=0.1.0 \
+  --build-arg GIT_COMMIT_SHA=$(git rev-parse HEAD) \
+  --build-arg BUILD_TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
+  -t oloka-video:dev .
+
+docker run --rm -p 7860:7860 -v oloka-video-data:/data oloka-video:dev
+```
+
+The named volume is mounted at `/data`; the development SQLite database is created at `/data/database/oloka-dev.db`. The process runs as UID `1000`.
+
+## Verify the service
+
+```bash
+curl http://localhost:7860/api/health
+curl http://localhost:7860/api/ready
+curl http://localhost:7860/api/version
+```
+
+`health` only confirms that the application process responds. `ready` performs live database and filesystem read/write checks. `version` exposes immutable build identity.
+
+## Configure Hugging Face
+
+1. Create the Docker Space `phucsd/Oloka-Video-Dev` and select Docker SDK.
+2. Configure persistent storage so Hugging Face mounts it at `/data`.
+3. In the GitHub repository, open **Settings → Secrets and variables → Actions** and add a repository secret named `HF_TOKEN`. Use a Hugging Face token with write access to the target Space.
+4. Push a validated change to `develop`. `.github/workflows/deploy-hf.yml` runs the full validation workflow and only pushes to the Space after it succeeds.
+5. Open the Space **Logs** tab to view Docker build logs and structured runtime logs. The public application is available at `https://phucsd-oloka-video-dev.hf.space` after the Space reaches `RUNNING`.
+
+No token belongs in `.env`, Git history, Docker build arguments, or the Space repository.
+
+## Roll back a deployment
+
+Find the last known-good commit in GitHub Actions or `GET /api/version`, then create a revert commit on `develop` and push it. The same validation gate redeploys that source state:
+
+```bash
+git revert <bad-commit-sha>
+git push origin develop
+```
+
+Avoid force-resetting shared GitHub history. If the Space itself is unhealthy, pause it while investigating and restart after a validated rollback is available.
+
+See [foundation architecture](docs/architecture/FOUNDATION.md), [deployment](docs/architecture/DEPLOYMENT.md), and [local development](docs/architecture/LOCAL_DEVELOPMENT.md) for deeper operational details.

apps/server/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@oloka/server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "predev": "npm run build -w @oloka/contracts",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "pretest": "npm run build -w @oloka/contracts",
+    "test:unit": "npm run build -w @oloka/contracts && vitest run --exclude **/*.integration.test.ts",
+    "test:integration": "npm run build -w @oloka/contracts && vitest run src/http/routes.integration.test.ts"
+  },
+  "dependencies": {
+    "@fastify/static": "10.1.2",
+    "@oloka/contracts": "0.1.0",
+    "fastify": "5.11.2",
+    "zod": "4.0.17"
+  },
+  "devDependencies": {
+    "@types/node": "24.2.1",
+    "tsx": "4.20.3",
+    "vitest": "3.2.7"
+  }
+}

apps/server/src/app.ts

@@ -0,0 +1,71 @@
+import fastifyStatic from "@fastify/static";
+import {
+  healthResponseSchema,
+  readyResponseSchema,
+  versionResponseSchema,
+} from "@oloka/contracts";
+import Fastify, { type FastifyInstance } from "fastify";
+import { resolve } from "node:path";
+import type { AppEnvironment } from "./config/environment.js";
+import { createDatabase } from "./database/create-database.js";
+import { FilesystemObjectStorage } from "./storage/filesystem-object-storage.js";
+import { HealthService } from "./system/health-service.js";
+import { ReadinessService } from "./system/readiness-service.js";
+import { VersionService } from "./system/version-service.js";
+
+export interface BuildApplicationOptions {
+  environment: AppEnvironment;
+  serveFrontend?: boolean;
+}
+
+export async function buildApplication(
+  options: BuildApplicationOptions,
+): Promise<FastifyInstance> {
+  const { environment } = options;
+  const app = Fastify({
+    logger:
+      environment.logLevel === "silent"
+        ? false
+        : { level: environment.logLevel },
+  });
+  const database = await createDatabase(environment.databaseUrl);
+  database.migrate();
+  const storage = new FilesystemObjectStorage(environment.dataDir);
+  const initialStorageState = await storage.checkReadiness();
+  if (initialStorageState.status !== "ready") {
+    await database.close();
+    throw new Error(
+      `Persistent storage startup check failed: ${initialStorageState.message ?? "unknown error"}`,
+    );
+  }
+
+  app.get("/api/health", () =>
+    healthResponseSchema.parse(new HealthService().getHealth()),
+  );
+  const readinessService = new ReadinessService(database, storage);
+  app.get("/api/ready", async (_request, reply) => {
+    const result = readyResponseSchema.parse(
+      await readinessService.getReadiness(),
+    );
+    return reply.code(result.status === "ready" ? 200 : 503).send(result);
+  });
+  app.get("/api/version", () =>
+    versionResponseSchema.parse(new VersionService(environment).getVersion()),
+  );
+
+  if (options.serveFrontend !== false) {
+    const webRoot = resolve(process.cwd(), "apps/web/dist");
+    await app.register(fastifyStatic, { root: webRoot, wildcard: false });
+    app.setNotFoundHandler(async (request, reply) => {
+      if (request.url.startsWith("/api/"))
+        return reply.code(404).send({ error: "Not Found" });
+      return reply.sendFile("index.html");
+    });
+  }
+
+  app.addHook("onClose", async () => {
+    await Promise.all([storage.close(), database.close()]);
+  });
+
+  return app;
+}

apps/server/src/config/environment.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+const environmentSchema = z.object({
+  NODE_ENV: z
+    .enum(["development", "test", "production"])
+    .default("development"),
+  PORT: z.coerce.number().int().min(1).max(65_535).default(7860),
+  DATA_DIR: z.string().min(1).default("/data"),
+  DATABASE_URL: z.string().min(1).optional(),
+  APP_VERSION: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/)
+    .default("0.1.0"),
+  GIT_COMMIT_SHA: z.string().min(1).default("local"),
+  BUILD_TIMESTAMP: z.string().min(1).default("development"),
+  LOG_LEVEL: z
+    .enum(["fatal", "error", "warn", "info", "debug", "trace", "silent"])
+    .default("info"),
+});
+
+export interface AppEnvironment {
+  nodeEnv: "development" | "test" | "production";
+  port: number;
+  dataDir: string;
+  databaseUrl: string;
+  appVersion: string;
+  gitCommitSha: string;
+  buildTimestamp: string;
+  logLevel: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "silent";
+}
+
+export function parseEnvironment(input: NodeJS.ProcessEnv): AppEnvironment {
+  const parsed = environmentSchema.parse(input);
+  const databaseUrl =
+    parsed.DATABASE_URL ?? `file:${parsed.DATA_DIR}/database/oloka-dev.db`;
+
+  if (
+    !databaseUrl.startsWith("file:") &&
+    !databaseUrl.startsWith("postgresql://")
+  ) {
+    throw new Error("DATABASE_URL must use file: or postgresql://");
+  }
+
+  return {
+    nodeEnv: parsed.NODE_ENV,
+    port: parsed.PORT,
+    dataDir: parsed.DATA_DIR,
+    databaseUrl,
+    appVersion: parsed.APP_VERSION,
+    gitCommitSha: parsed.GIT_COMMIT_SHA,
+    buildTimestamp: parsed.BUILD_TIMESTAMP,
+    logLevel: parsed.LOG_LEVEL,
+  };
+}

apps/server/src/config/environment.unit.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import { parseEnvironment } from "./environment.js";
+
+describe("parseEnvironment", () => {
+  it("rejects an invalid public port", () => {
+    expect(() => parseEnvironment({ PORT: "70000" })).toThrow(/PORT/);
+  });
+});

apps/server/src/database/create-database.ts

@@ -0,0 +1,16 @@
+import type { SystemDatabase } from "./database.js";
+import { SqliteSystemDatabase } from "./sqlite-system-database.js";
+
+export async function createDatabase(
+  databaseUrl: string,
+): Promise<SystemDatabase> {
+  if (databaseUrl.startsWith("file:")) {
+    return SqliteSystemDatabase.connect(databaseUrl);
+  }
+  if (databaseUrl.startsWith("postgresql://")) {
+    throw new Error(
+      "PostgreSQL adapter is not enabled in the online development foundation",
+    );
+  }
+  throw new Error("Unsupported DATABASE_URL");
+}

apps/server/src/database/database.ts

@@ -0,0 +1,9 @@
+import type { ReadyResponse } from "@oloka/contracts";
+
+export type DatabaseReadiness = ReadyResponse["checks"]["database"];
+
+export interface SystemDatabase {
+  migrate(): void;
+  checkReadiness(): Promise<DatabaseReadiness>;
+  close(): Promise<void>;
+}

apps/server/src/database/sqlite-system-database.ts

@@ -0,0 +1,63 @@
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+import type { DatabaseReadiness, SystemDatabase } from "./database.js";
+
+export class SqliteSystemDatabase implements SystemDatabase {
+  private constructor(private readonly database: DatabaseSync) {}
+
+  static async connect(databaseUrl: string): Promise<SqliteSystemDatabase> {
+    if (!databaseUrl.startsWith("file:")) {
+      throw new Error("The SQLite adapter requires a file: DATABASE_URL");
+    }
+    const databasePath = fileURLToPath(databaseUrl);
+    await mkdir(dirname(databasePath), { recursive: true });
+    return new SqliteSystemDatabase(new DatabaseSync(databasePath));
+  }
+
+  migrate(): void {
+    this.database.exec(`
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS schema_migrations (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS system_metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      INSERT OR IGNORE INTO schema_migrations (version, name, applied_at)
+      VALUES (1, 'foundation_system_tables', datetime('now'));
+    `);
+  }
+
+  checkReadiness(): Promise<DatabaseReadiness> {
+    try {
+      const result = this.database.prepare("SELECT 1 AS healthy").get() as
+        | { healthy?: number }
+        | undefined;
+      return Promise.resolve(
+        result?.healthy === 1
+          ? { status: "ready" }
+          : {
+              status: "not_ready",
+              message: "Database health query returned an unexpected result",
+            },
+      );
+    } catch (error) {
+      return Promise.resolve({
+        status: "not_ready",
+        message:
+          error instanceof Error ? error.message : "Unknown database error",
+      });
+    }
+  }
+
+  close(): Promise<void> {
+    this.database.close();
+    return Promise.resolve();
+  }
+}

apps/server/src/http/routes.integration.test.ts

@@ -0,0 +1,79 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildApplication } from "../app.js";
+import { parseEnvironment } from "../config/environment.js";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+async function createTestApplication() {
+  const dataDir = await mkdtemp(join(tmpdir(), "oloka-api-"));
+  temporaryDirectories.push(dataDir);
+  return buildApplication({
+    environment: parseEnvironment({
+      NODE_ENV: "test",
+      DATA_DIR: dataDir,
+      DATABASE_URL: pathToFileURL(join(dataDir, "database", "test.db")).href,
+      APP_VERSION: "1.2.3",
+      GIT_COMMIT_SHA: "abc123",
+      BUILD_TIMESTAMP: "2026-08-05T01:00:00.000Z",
+      LOG_LEVEL: "silent",
+    }),
+    serveFrontend: false,
+  });
+}
+
+describe("system API", () => {
+  it("GET /api/health confirms the process is running", async () => {
+    const app = await createTestApplication();
+    const response = await app.inject({ method: "GET", url: "/api/health" });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toMatchObject({ status: "ok" });
+
+    await app.close();
+  });
+
+  it("GET /api/ready checks the database, storage, and configuration", async () => {
+    const app = await createTestApplication();
+    const response = await app.inject({ method: "GET", url: "/api/ready" });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({
+      status: "ready",
+      checks: {
+        database: { status: "ready" },
+        storage: { status: "ready" },
+        configuration: { status: "ready" },
+      },
+    });
+
+    await app.close();
+  });
+
+  it("GET /api/version returns immutable build metadata", async () => {
+    const app = await createTestApplication();
+    const response = await app.inject({ method: "GET", url: "/api/version" });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({
+      name: "Oloka Video",
+      version: "1.2.3",
+      environment: "test",
+      gitCommitSha: "abc123",
+      buildTimestamp: "2026-08-05T01:00:00.000Z",
+    });
+
+    await app.close();
+  });
+});

apps/server/src/index.ts

@@ -0,0 +1,37 @@
+import { buildApplication } from "./app.js";
+import { parseEnvironment } from "./config/environment.js";
+
+async function start(): Promise<void> {
+  const environment = parseEnvironment(process.env);
+  const app = await buildApplication({ environment });
+  let shuttingDown = false;
+
+  const shutdown = async (signal: NodeJS.Signals) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    app.log.info({ signal }, "graceful shutdown started");
+    await app.close();
+    process.exitCode = 0;
+  };
+
+  process.once("SIGTERM", () => void shutdown("SIGTERM"));
+  process.once("SIGINT", () => void shutdown("SIGINT"));
+
+  await app.listen({ host: "0.0.0.0", port: environment.port });
+  app.log.info(
+    {
+      port: environment.port,
+      environment: environment.nodeEnv,
+      version: environment.appVersion,
+      gitCommitSha: environment.gitCommitSha,
+    },
+    "Oloka Video is listening",
+  );
+}
+
+start().catch((error: unknown) => {
+  process.stderr.write(
+    `${JSON.stringify({ level: "fatal", message: "startup failed", error: error instanceof Error ? error.message : String(error) })}\n`,
+  );
+  process.exitCode = 1;
+});

apps/server/src/storage/filesystem-object-storage.ts

@@ -0,0 +1,55 @@
+import { mkdir, open, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import type { ObjectStorage, ReadinessResult } from "./object-storage.js";
+
+export class FilesystemObjectStorage implements ObjectStorage {
+  readonly #probePath: string;
+  #readinessQueue: Promise<ReadinessResult> = Promise.resolve({
+    status: "ready",
+  });
+
+  constructor(private readonly rootPath: string) {
+    this.#probePath = join(rootPath, ".oloka-readiness");
+  }
+
+  checkReadiness(): Promise<ReadinessResult> {
+    this.#readinessQueue = this.#readinessQueue.then(
+      () => this.runReadinessCheck(),
+      () => this.runReadinessCheck(),
+    );
+    return this.#readinessQueue;
+  }
+
+  async close(): Promise<void> {
+    await this.#readinessQueue.catch(() => undefined);
+    await unlink(this.#probePath).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+
+  private async runReadinessCheck(): Promise<ReadinessResult> {
+    try {
+      await mkdir(this.rootPath, { recursive: true });
+      const handle = await open(this.#probePath, "w+");
+      try {
+        const marker = Buffer.from("1");
+        await handle.write(marker, 0, marker.length, 0);
+        await handle.sync();
+        const verification = Buffer.alloc(1);
+        const result = await handle.read(verification, 0, 1, 0);
+        if (result.bytesRead !== 1 || verification.toString() !== "1") {
+          throw new Error("Storage write verification failed");
+        }
+      } finally {
+        await handle.close();
+      }
+      return { status: "ready" };
+    } catch (error) {
+      return {
+        status: "not_ready",
+        message:
+          error instanceof Error ? error.message : "Unknown storage error",
+      };
+    }
+  }
+}

apps/server/src/storage/filesystem-object-storage.unit.test.ts

@@ -0,0 +1,30 @@
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { FilesystemObjectStorage } from "./filesystem-object-storage.js";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+describe("FilesystemObjectStorage", () => {
+  it("proves the configured storage is writable and cleans up its fixed probe", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oloka-storage-"));
+    temporaryDirectories.push(root);
+    const storage = new FilesystemObjectStorage(root);
+
+    await expect(storage.checkReadiness()).resolves.toEqual({
+      status: "ready",
+    });
+    await storage.close();
+
+    expect(await readdir(root)).toEqual([]);
+  });
+});

apps/server/src/storage/object-storage.ts

@@ -0,0 +1,8 @@
+import type { ReadyResponse } from "@oloka/contracts";
+
+export type ReadinessResult = ReadyResponse["checks"]["storage"];
+
+export interface ObjectStorage {
+  checkReadiness(): Promise<ReadinessResult>;
+  close(): Promise<void>;
+}

apps/server/src/system/health-service.ts

@@ -0,0 +1,10 @@
+import type { HealthResponse } from "@oloka/contracts";
+
+export class HealthService {
+  getHealth(): HealthResponse {
+    return {
+      status: "ok",
+      timestamp: new Date().toISOString(),
+    };
+  }
+}

apps/server/src/system/health-service.unit.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it, vi } from "vitest";
+import { HealthService } from "./health-service.js";
+
+describe("HealthService", () => {
+  it("reports process health with the current timestamp", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-08-05T01:00:00.000Z"));
+
+    expect(new HealthService().getHealth()).toEqual({
+      status: "ok",
+      timestamp: "2026-08-05T01:00:00.000Z",
+    });
+
+    vi.useRealTimers();
+  });
+});

apps/server/src/system/readiness-service.ts

@@ -0,0 +1,24 @@
+import type { ReadyResponse } from "@oloka/contracts";
+import type { SystemDatabase } from "../database/database.js";
+import type { ObjectStorage } from "../storage/object-storage.js";
+
+export class ReadinessService {
+  constructor(
+    private readonly database: SystemDatabase,
+    private readonly storage: ObjectStorage,
+  ) {}
+
+  async getReadiness(): Promise<ReadyResponse> {
+    const [database, storage] = await Promise.all([
+      this.database.checkReadiness(),
+      this.storage.checkReadiness(),
+    ]);
+    const configuration = { status: "ready" as const };
+    const status =
+      database.status === "ready" && storage.status === "ready"
+        ? "ready"
+        : "not_ready";
+
+    return { status, checks: { database, storage, configuration } };
+  }
+}

apps/server/src/system/version-service.ts

@@ -0,0 +1,16 @@
+import type { VersionResponse } from "@oloka/contracts";
+import type { AppEnvironment } from "../config/environment.js";
+
+export class VersionService {
+  constructor(private readonly environment: AppEnvironment) {}
+
+  getVersion(): VersionResponse {
+    return {
+      name: "Oloka Video",
+      version: this.environment.appVersion,
+      environment: this.environment.nodeEnv,
+      gitCommitSha: this.environment.gitCommitSha,
+      buildTimestamp: this.environment.buildTimestamp,
+    };
+  }
+}

apps/server/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true
+  },
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
+}

apps/server/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src"]
+}

apps/web/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#f4f5ef" />
+    <meta name="description" content="Oloka Video online foundation status." />
+    <title>Oloka Video</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/web/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@oloka/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "predev": "npm run build -w @oloka/contracts && npm run build -w @oloka/design-system",
+    "dev": "vite --host 0.0.0.0 --port 5173",
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build -w @oloka/contracts && npm run build -w @oloka/design-system",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@oloka/contracts": "0.1.0",
+    "@oloka/design-system": "0.1.0",
+    "react": "19.1.1",
+    "react-dom": "19.1.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.6.4",
+    "@testing-library/react": "16.3.0",
+    "@types/react": "19.1.10",
+    "@types/react-dom": "19.1.7",
+    "@vitejs/plugin-react": "4.7.0",
+    "jsdom": "26.1.0",
+    "vite": "7.3.6",
+    "vitest": "3.2.7"
+  }
+}

apps/web/src/App.test.tsx

@@ -0,0 +1,56 @@
+import { render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { App } from "./App";
+
+describe("App", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("renders connected state from the real API responses", async () => {
+    vi.spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ status: "ok", timestamp: "2026-08-05T00:00:00Z" }),
+        ),
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            status: "ready",
+            checks: {
+              database: { status: "ready" },
+              storage: { status: "ready" },
+              configuration: { status: "ready" },
+            },
+          }),
+        ),
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            name: "Oloka Video",
+            version: "1.2.3",
+            environment: "development",
+            gitCommitSha: "abc123",
+            buildTimestamp: "2026-08-05T00:00:00Z",
+          }),
+        ),
+      );
+
+    render(<App />);
+
+    expect(await screen.findByText("Connected")).toBeInTheDocument();
+    expect(screen.getByText("1.2.3")).toBeInTheDocument();
+    expect(screen.getByText("abc123")).toBeInTheDocument();
+  });
+
+  it("renders an error state when an API request fails", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(
+      new Error("Network unavailable"),
+    );
+
+    render(<App />);
+
+    expect(await screen.findByText("Connection error")).toBeInTheDocument();
+    expect(screen.getByText("Network unavailable")).toBeInTheDocument();
+  });
+});

apps/web/src/App.tsx

@@ -0,0 +1,208 @@
+import {
+  healthResponseSchema,
+  readyResponseSchema,
+  versionResponseSchema,
+  type ReadyResponse,
+  type VersionResponse,
+} from "@oloka/contracts";
+import {
+  DefinitionRow,
+  StatusPill,
+  Surface,
+  type StatusTone,
+} from "@oloka/design-system";
+import { useEffect, useState } from "react";
+
+type DashboardState =
+  | { kind: "loading" }
+  | { kind: "connected"; ready: ReadyResponse; version: VersionResponse }
+  | { kind: "error"; message: string };
+
+async function getJson(path: string): Promise<unknown> {
+  const response = await fetch(path, {
+    headers: { accept: "application/json" },
+  });
+  if (!response.ok) throw new Error(`${path} returned ${response.status}`);
+  return response.json();
+}
+
+async function loadSystemState(): Promise<
+  Extract<DashboardState, { kind: "connected" }>
+> {
+  const [healthData, readyData, versionData] = await Promise.all([
+    getJson("/api/health"),
+    getJson("/api/ready"),
+    getJson("/api/version"),
+  ]);
+  healthResponseSchema.parse(healthData);
+  return {
+    kind: "connected",
+    ready: readyResponseSchema.parse(readyData),
+    version: versionResponseSchema.parse(versionData),
+  };
+}
+
+function ReadinessBadge({ value }: { value: "ready" | "not_ready" }) {
+  return (
+    <StatusPill tone={value === "ready" ? "success" : "danger"}>
+      {value === "ready" ? "Ready" : "Not ready"}
+    </StatusPill>
+  );
+}
+
+export function App() {
+  const [state, setState] = useState<DashboardState>({ kind: "loading" });
+
+  useEffect(() => {
+    let active = true;
+    loadSystemState()
+      .then((result) => active && setState(result))
+      .catch((error: unknown) => {
+        if (active)
+          setState({
+            kind: "error",
+            message:
+              error instanceof Error
+                ? error.message
+                : "Unknown connection error",
+          });
+      });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const connectionTone: StatusTone =
+    state.kind === "connected"
+      ? "success"
+      : state.kind === "error"
+        ? "danger"
+        : "neutral";
+  const connectionLabel =
+    state.kind === "connected"
+      ? "Connected"
+      : state.kind === "error"
+        ? "Connection error"
+        : "Connecting";
+
+  return (
+    <main className="page-shell">
+      <header className="topbar">
+        <a className="brand" href="/" aria-label="Oloka Video home">
+          <span className="brand-mark">O</span>
+          <span>Oloka Video</span>
+        </a>
+        <span className="environment-label">Online foundation</span>
+      </header>
+
+      <div className="content">
+        <section className="hero" aria-labelledby="page-title">
+          <div>
+            <p className="eyebrow">System overview</p>
+            <h1 id="page-title">A dependable start for every frame.</h1>
+            <p className="hero-copy">
+              Live infrastructure status for the Oloka Video development
+              environment.
+            </p>
+          </div>
+          <StatusPill tone={connectionTone}>{connectionLabel}</StatusPill>
+        </section>
+
+        {state.kind === "loading" && (
+          <Surface
+            className="state-panel loading-panel"
+            aria-live="polite"
+            aria-busy="true"
+          >
+            <span className="loading-line" />
+            <div>
+              <strong>Connecting to Oloka Video</strong>
+              <p>Checking the API and persistent services.</p>
+            </div>
+          </Surface>
+        )}
+
+        {state.kind === "error" && (
+          <Surface className="state-panel error-panel" role="alert">
+            <span className="state-symbol">!</span>
+            <div>
+              <strong>We could not reach the foundation services.</strong>
+              <p>{state.message}</p>
+            </div>
+          </Surface>
+        )}
+
+        {state.kind === "connected" && (
+          <div className="dashboard-grid">
+            <Surface className="status-card">
+              <div className="card-heading">
+                <div>
+                  <p className="eyebrow">Runtime</p>
+                  <h2>Service health</h2>
+                </div>
+                <StatusPill tone="success">API online</StatusPill>
+              </div>
+              <dl>
+                <DefinitionRow
+                  label="Database"
+                  value={
+                    <ReadinessBadge
+                      value={state.ready.checks.database.status}
+                    />
+                  }
+                />
+                <DefinitionRow
+                  label="Persistent storage"
+                  value={
+                    <ReadinessBadge value={state.ready.checks.storage.status} />
+                  }
+                />
+                <DefinitionRow
+                  label="Configuration"
+                  value={
+                    <ReadinessBadge
+                      value={state.ready.checks.configuration.status}
+                    />
+                  }
+                />
+              </dl>
+            </Surface>
+
+            <Surface className="status-card build-card">
+              <div className="card-heading">
+                <div>
+                  <p className="eyebrow">Release</p>
+                  <h2>Build identity</h2>
+                </div>
+                <span className="version-chip">v{state.version.version}</span>
+              </div>
+              <dl>
+                <DefinitionRow
+                  label="Application version"
+                  value={state.version.version}
+                />
+                <DefinitionRow
+                  label="Git commit"
+                  value={<code>{state.version.gitCommitSha}</code>}
+                />
+                <DefinitionRow
+                  label="Environment"
+                  value={state.version.environment}
+                />
+                <DefinitionRow
+                  label="Built"
+                  value={state.version.buildTimestamp}
+                />
+              </dl>
+            </Surface>
+          </div>
+        )}
+      </div>
+
+      <footer>
+        <span>Oloka Video</span>
+        <span>Foundation status updates on every load.</span>
+      </footer>
+    </main>
+  );
+}

apps/web/src/main.tsx

@@ -0,0 +1,11 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "@oloka/design-system/tokens.css";
+import "./styles.css";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

apps/web/src/styles.css

@@ -0,0 +1,229 @@
+* {
+  box-sizing: border-box;
+}
+html {
+  background: var(--color-canvas);
+  color: var(--color-ink);
+  font-family: var(--font-sans);
+}
+body {
+  margin: 0;
+  min-width: 320px;
+}
+button,
+input {
+  font: inherit;
+}
+
+.page-shell {
+  min-height: 100vh;
+  position: relative;
+}
+.page-shell::before {
+  background: linear-gradient(135deg, rgba(11, 104, 91, 0.08), transparent 55%);
+  border-radius: 50%;
+  content: "";
+  height: 32rem;
+  position: fixed;
+  right: -14rem;
+  top: -17rem;
+  width: 32rem;
+  z-index: -1;
+}
+
+.topbar,
+footer {
+  align-items: center;
+  display: flex;
+  justify-content: space-between;
+  margin: 0 auto;
+  max-width: 1180px;
+  padding: 1.4rem 2rem;
+}
+.topbar {
+  border-bottom: 1px solid var(--color-line);
+}
+.brand {
+  align-items: center;
+  color: var(--color-ink);
+  display: flex;
+  font-weight: 750;
+  gap: 0.72rem;
+  text-decoration: none;
+}
+.brand-mark {
+  align-items: center;
+  background: var(--color-brand);
+  border-radius: 10px;
+  color: white;
+  display: inline-flex;
+  height: 2rem;
+  justify-content: center;
+  width: 2rem;
+}
+.environment-label {
+  color: var(--color-muted);
+  font-size: 0.82rem;
+  font-weight: 650;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+.content {
+  margin: 0 auto;
+  max-width: 1180px;
+  padding: 6.5rem 2rem 5rem;
+}
+.hero {
+  align-items: flex-end;
+  display: flex;
+  gap: 2rem;
+  justify-content: space-between;
+  margin-bottom: 3.2rem;
+}
+.eyebrow {
+  color: var(--color-brand);
+  font-size: 0.76rem;
+  font-weight: 800;
+  letter-spacing: 0.13em;
+  margin: 0 0 0.7rem;
+  text-transform: uppercase;
+}
+h1 {
+  font-size: clamp(2.55rem, 6vw, 5.2rem);
+  letter-spacing: -0.055em;
+  line-height: 0.98;
+  margin: 0;
+  max-width: 820px;
+}
+.hero-copy {
+  color: var(--color-muted);
+  font-size: 1.05rem;
+  line-height: 1.7;
+  margin: 1.4rem 0 0;
+  max-width: 590px;
+}
+.dashboard-grid {
+  display: grid;
+  gap: 1.25rem;
+  grid-template-columns: minmax(0, 1.05fr) minmax(0, 0.95fr);
+}
+.status-card {
+  box-shadow: var(--shadow-card);
+  padding: 1.7rem 1.8rem 0.5rem;
+}
+.card-heading {
+  align-items: flex-start;
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 1.5rem;
+}
+.card-heading h2 {
+  font-size: 1.45rem;
+  letter-spacing: -0.025em;
+  margin: 0;
+}
+.card-heading .eyebrow {
+  margin-bottom: 0.35rem;
+}
+.status-card dl {
+  margin: 0;
+}
+.version-chip {
+  background: var(--color-brand-deep);
+  border-radius: var(--radius-sm);
+  color: white;
+  font-family: ui-monospace, monospace;
+  font-size: 0.82rem;
+  padding: 0.5rem 0.65rem;
+}
+code {
+  background: var(--color-neutral-soft);
+  border-radius: 6px;
+  font-size: 0.8rem;
+  padding: 0.3rem 0.45rem;
+  word-break: break-all;
+}
+.state-panel {
+  align-items: center;
+  box-shadow: var(--shadow-card);
+  display: flex;
+  gap: 1rem;
+  min-height: 190px;
+  padding: 2rem;
+}
+.state-panel p {
+  color: var(--color-muted);
+  margin: 0.45rem 0 0;
+}
+.loading-line {
+  animation: pulse 1.2s ease-in-out infinite;
+  background: var(--color-brand);
+  border-radius: 999px;
+  height: 3rem;
+  opacity: 0.5;
+  width: 0.3rem;
+}
+.error-panel {
+  border-color: #e9c7c1;
+}
+.state-symbol {
+  align-items: center;
+  background: var(--color-danger-soft);
+  border-radius: 50%;
+  color: var(--color-danger);
+  display: flex;
+  font-weight: 800;
+  height: 2.5rem;
+  justify-content: center;
+  width: 2.5rem;
+}
+footer {
+  border-top: 1px solid var(--color-line);
+  color: var(--color-muted);
+  font-size: 0.8rem;
+}
+footer span:first-child {
+  color: var(--color-ink);
+  font-weight: 750;
+}
+
+@keyframes pulse {
+  50% {
+    opacity: 1;
+    transform: scaleY(1.15);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .loading-line {
+    animation: none;
+  }
+}
+@media (max-width: 760px) {
+  .content {
+    padding-top: 4.2rem;
+  }
+  .hero {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+  .dashboard-grid {
+    grid-template-columns: 1fr;
+  }
+  .environment-label,
+  footer span:last-child {
+    display: none;
+  }
+  .topbar,
+  footer,
+  .content {
+    padding-left: 1.15rem;
+    padding-right: 1.15rem;
+  }
+  .status-card {
+    padding-left: 1.2rem;
+    padding-right: 1.2rem;
+  }
+  .card-heading {
+    gap: 1rem;
+  }
+}

apps/web/src/test/setup.ts

@@ -0,0 +1,5 @@
+import "@testing-library/jest-dom/vitest";
+import { afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+afterEach(() => cleanup());

apps/web/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "types": ["vite/client", "vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

apps/web/vite.config.ts

@@ -0,0 +1,14 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: { "/api": "http://localhost:7860" },
+  },
+  test: {
+    environment: "jsdom",
+    setupFiles: "./src/test/setup.ts",
+    css: true,
+  },
+});

docs/architecture/DEPLOYMENT.md

@@ -0,0 +1,21 @@
+# Deployment
+
+## Build artifact
+
+The multi-stage Docker build installs the locked dependency graph, compiles contracts, design system, web, and server, then prunes development dependencies. The runtime stage contains only production dependencies and compiled artifacts. It runs as UID/GID `1000`, exposes `7860`, and includes an application health check.
+
+Build identity enters the image through `APP_VERSION`, `GIT_COMMIT_SHA`, and `BUILD_TIMESTAMP` build arguments. Runtime configuration can override ordinary environment values, but production operators should keep build identity immutable.
+
+## GitHub to Hugging Face
+
+The `develop` deployment workflow invokes the reusable validation workflow first. Formatting, lint, typecheck, unit, integration, frontend, production, browser, and Docker checks must all pass. The deployment job then pushes the exact validated Git commit to `phucsd/Oloka-Video-Dev` using the masked `HF_TOKEN` secret.
+
+The Space reads Docker metadata from the YAML header in `README.md`. Persistent Hugging Face storage must be attached at `/data`; replacing that path with ephemeral storage loses SQLite state after rebuilds.
+
+## Observability
+
+Fastify emits JSON logs to standard output. Use the Space Logs tab for build and container logs. Diagnose deployment layers separately: GitHub validation, repository sync, Docker build, container start, `/api/health`, then `/api/ready`.
+
+## Rollback
+
+Revert the faulty GitHub commit on `develop`. A new workflow run validates and deploys the revert. Confirm `/api/version` returns the expected rollback SHA and then confirm `/api/ready` reports every dependency ready.

docs/architecture/FOUNDATION.md

@@ -0,0 +1,29 @@
+# Foundation architecture
+
+## Purpose
+
+This repository establishes the smallest online-safe base for Oloka Video. It deliberately contains no authentication, project management, uploads, AI integrations, editor, or rendering pipeline.
+
+## Module boundaries
+
+The browser depends on `@oloka/contracts` and `@oloka/design-system`. The server depends on `@oloka/contracts`, application services, and infrastructure adapters. Routes translate HTTP to application services; they do not access SQLite or the filesystem directly.
+
+The database boundary is `SystemDatabase`. `SqliteSystemDatabase` is the online-development adapter. A PostgreSQL adapter can later implement the same contract without changing system services or routes.
+
+The persistent-data boundary is `ObjectStorage`. `FilesystemObjectStorage` owns all filesystem readiness work beneath `DATA_DIR`; future object-store implementations can replace it without changing HTTP handlers.
+
+## Request flow
+
+1. Configuration is parsed and validated before the listener opens.
+2. The database directory is created and migrations are applied idempotently.
+3. Persistent storage completes a real read/write startup probe.
+4. Fastify exposes system endpoints and serves the compiled React application.
+5. The frontend fetches all three system endpoints and validates responses with shared schemas.
+
+## Readiness semantics
+
+`/api/health` is a liveness check only. `/api/ready` executes `SELECT 1`, checks storage through a fixed `.oloka-readiness` probe, and reports validated configuration. The probe is overwritten rather than multiplied and removed during graceful shutdown. A failed component returns HTTP `503` with per-component status.
+
+## Persistence schema
+
+Migration 1 creates `schema_migrations` and `system_metadata`. There are no product-domain tables in the foundation phase. SQLite uses WAL mode for safer online-development concurrency.

docs/architecture/LOCAL_DEVELOPMENT.md

@@ -0,0 +1,22 @@
+# Local development
+
+## Setup
+
+Install Node.js 22 or later and run `npm ci`. Copy `.env.example` only when a local environment file is useful; never add `.env` to Git. Windows developers should set `DATA_DIR` and `DATABASE_URL` to a writable repository-local path because `/data` is the online Linux default.
+
+`npm run dev` starts Fastify on `7860` and Vite on `5173`. Vite proxies API requests to Fastify. Production and browser checks use the single-port compiled build.
+
+## Quality commands
+
+- `npm run format:check` verifies formatting.
+- `npm run lint` applies typed ESLint rules.
+- `npm run typecheck` checks every workspace and tool configuration.
+- `npm run test:unit` verifies environment, health, and storage behavior.
+- `npm run test:integration` exercises all system endpoints through Fastify injection.
+- `npm run test:frontend` exercises connected and error states.
+- `npm run build` produces all production artifacts.
+- `npm run test:e2e` starts the compiled server and checks the page in Chromium.
+
+## Data cleanup
+
+Repository-local `.data` and `.tmp` directories are ignored. Stop the server before removing a SQLite development database, especially on Windows where open files remain locked. Do not delete a mounted production `/data` volume as part of routine development.

docs/decisions/0001-modular-monolith.md

@@ -0,0 +1,16 @@
+# ADR 0001: TypeScript modular monolith
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Oloka Video needs a small deployable base while preserving explicit frontend, backend, contract, and UI boundaries.
+
+## Decision
+
+Use npm workspaces with `apps/web`, `apps/server`, `packages/contracts`, and `packages/design-system`. Build one deployable process without combining source modules.
+
+## Consequences
+
+One image and one runtime simplify operations. Workspace contracts prevent accidental coupling and leave modules separable if scale later justifies it.

docs/decisions/0002-single-hf-docker-space.md

@@ -0,0 +1,16 @@
+# ADR 0002: Single Hugging Face Docker Space
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+The development environment needs to be online from the first commit with minimal operational surface.
+
+## Decision
+
+Serve the compiled React application and API from one Fastify process on public port `7860` in `phucsd/Oloka-Video-Dev`.
+
+## Consequences
+
+Frontend and API share an origin, eliminating CORS configuration and coordinating deployment. Independent scaling is deferred until product usage requires it.

docs/decisions/0003-storage-abstraction.md

@@ -0,0 +1,16 @@
+# ADR 0003: Persistent storage abstraction
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+Online development uses Hugging Face persistent disk, while future production may use object storage.
+
+## Decision
+
+Application services depend on `ObjectStorage`. The first adapter uses the filesystem below `/data` and owns its safe read/write readiness probe.
+
+## Consequences
+
+Routes contain no direct filesystem operations. A cloud object-store adapter can replace the filesystem adapter without changing HTTP contracts.

docs/decisions/0004-database-abstraction.md

@@ -0,0 +1,16 @@
+# ADR 0004: Database abstraction
+
+- Status: Accepted
+- Date: 2026-08-05
+
+## Context
+
+SQLite minimizes online-development infrastructure, while expected production workloads may require PostgreSQL.
+
+## Decision
+
+System services depend on `SystemDatabase`. Use Node's SQLite adapter for development and reserve `postgresql://` URLs for a future PostgreSQL implementation.
+
+## Consequences
+
+Business and HTTP code do not know the active database engine. PostgreSQL activation requires a new adapter and focused contract tests, not route rewrites.

eslint.config.js

@@ -0,0 +1,47 @@
+import eslint from "@eslint/js";
+import prettier from "eslint-config-prettier";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: [
+      "**/dist/**",
+      "**/coverage/**",
+      "playwright-report/**",
+      "test-results/**",
+    ],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked.map((config) => ({
+    ...config,
+    files: ["**/*.ts", "**/*.tsx"],
+  })),
+  prettier,
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: ["playwright.config.ts", "tests/e2e/*.ts"],
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    files: ["apps/server/**/*.ts", "*.ts", "*.js"],
+    languageOptions: { globals: globals.node },
+  },
+  {
+    files: ["apps/web/**/*.ts", "apps/web/**/*.tsx"],
+    languageOptions: { globals: globals.browser },
+  },
+  {
+    files: ["**/*.test.ts", "**/*.test.tsx", "tests/**/*.ts"],
+    rules: {
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+    },
+  },
+);

package.json

@@ -0,0 +1,39 @@
+{
+  "name": "oloka-video",
+  "version": "0.1.0",
+  "private": true,
+  "description": "The online foundation for Oloka Video.",
+  "type": "module",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "npm run build -w @oloka/contracts && npm run build -w @oloka/design-system && npm run build -w @oloka/web && npm run build -w @oloka/server",
+    "dev": "concurrently -n server,web -c blue,green \"npm run dev -w @oloka/server\" \"npm run dev -w @oloka/web\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint . --max-warnings=0",
+    "typecheck": "npm run typecheck -w @oloka/contracts && npm run typecheck -w @oloka/design-system && npm run typecheck -w @oloka/server && npm run typecheck -w @oloka/web && tsc -p tsconfig.tools.json --noEmit",
+    "test": "npm run test -w @oloka/server && npm run test -w @oloka/web",
+    "test:unit": "npm run test:unit -w @oloka/server",
+    "test:integration": "npm run test:integration -w @oloka/server",
+    "test:frontend": "npm run test -w @oloka/web",
+    "test:e2e": "playwright test",
+    "start": "node apps/server/dist/index.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.32.0",
+    "@playwright/test": "1.62.1",
+    "concurrently": "9.2.0",
+    "eslint": "9.32.0",
+    "eslint-config-prettier": "10.1.8",
+    "globals": "16.3.0",
+    "prettier": "3.6.2",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.39.0"
+  }
+}

packages/contracts/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@oloka/contracts",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "zod": "4.0.17"
+  }
+}

packages/contracts/src/index.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+export const healthResponseSchema = z.object({
+  status: z.literal("ok"),
+  timestamp: z.string(),
+});
+
+export const componentReadinessSchema = z.object({
+  status: z.enum(["ready", "not_ready"]),
+  message: z.string().optional(),
+});
+
+export const readyResponseSchema = z.object({
+  status: z.enum(["ready", "not_ready"]),
+  checks: z.object({
+    database: componentReadinessSchema,
+    storage: componentReadinessSchema,
+    configuration: componentReadinessSchema,
+  }),
+});
+
+export const versionResponseSchema = z.object({
+  name: z.literal("Oloka Video"),
+  version: z.string(),
+  environment: z.enum(["development", "test", "production"]),
+  gitCommitSha: z.string(),
+  buildTimestamp: z.string(),
+});
+
+export type HealthResponse = z.infer<typeof healthResponseSchema>;
+export type ReadyResponse = z.infer<typeof readyResponseSchema>;
+export type VersionResponse = z.infer<typeof versionResponseSchema>;

packages/contracts/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "declaration": true, "outDir": "dist" }
+}

packages/contracts/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src" },
+  "include": ["src"]
+}

packages/design-system/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@oloka/design-system",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.tsx",
+  "exports": {
+    ".": {
+      "types": "./src/index.tsx",
+      "import": "./dist/index.js"
+    },
+    "./tokens.css": "./src/tokens.css"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/react": "19.1.10",
+    "react": "19.1.1"
+  }
+}