Phase 1 foundation and deployment gate

.coderabbit.yaml

@@ -0,0 +1,4 @@
+reviews:
+  auto_review:
+    base_branches:
+      - develop

.gitignore

@@ -1,6 +1,9 @@
 node_modules/
 dist/
 build/
+apps/desktop/src-tauri/binaries/*
+apps/desktop/src-tauri/gen/
+apps/desktop/src-tauri/target/
 .next/
 .expo/
 coverage/

README.md

@@ -67,6 +67,12 @@ Start only the API sidecar in watch mode:
 pnpm --filter @edutrack/api run dev
 ```
 
+Start the desktop shell in development mode:
+
+```bash
+pnpm --filter @edutrack/desktop run dev
+```
+
 ## Quality Commands
 
 ```bash
@@ -97,7 +103,7 @@ Runs TypeScript project-reference checks across all active packages and apps.
 pnpm run test
 ```
 
-Runs the unit test suites for the API and web app.
+Runs the unit test suites for the database package, API and web app.
 
 ```bash
 pnpm run test:e2e
@@ -113,7 +119,19 @@ pnpm exec playwright install chromium
 pnpm run build
 ```
 
-Builds all active packages and apps.
+Builds the shared packages, database package, API and web app. Desktop packaging is handled separately through `pnpm run build:desktop`.
+
+```bash
+pnpm run check:desktop
+```
+
+Builds the Windows sidecar executable and runs the Tauri/Rust compile check.
+
+```bash
+pnpm run verify:sidecar
+```
+
+Starts the packaged Windows sidecar, calls `/health` with the local capability header, and confirms the SQLite probe database is created.
 
 ## Database Commands
 
@@ -123,12 +141,20 @@ Generate SQLite migrations from the Drizzle schema:
 pnpm run db:generate
 ```
 
-Push the SQLite schema to the configured local database:
+Apply committed SQLite migrations to the configured local database:
 
 ```bash
 pnpm run db:migrate
 ```
 
+For local schema prototyping only, `pnpm --filter @edutrack/db run db:push` can push the current Drizzle schema without using committed migrations.
+
+Seed deterministic Phase 1 foundation data:
+
+```bash
+pnpm run db:seed
+```
+
 By default, local SQLite uses:
 
 ```text
@@ -137,6 +163,34 @@ By default, local SQLite uses:
 
 Override it with `EDUTRACK_SQLITE_PATH` in `.env`.
 
+## Git Bash Convenience Scripts
+
+These scripts only group existing `pnpm` commands for local development convenience. The source of truth remains the `package.json` scripts above.
+
+```bash
+./scripts/db-setup.sh
+```
+
+Creates `.data`, runs migrations, seeds foundation data and prints the SQLite path for DBeaver.
+
+```bash
+./scripts/db-fresh.sh
+```
+
+Resets only the local development SQLite database after an explicit `RESET` confirmation, then migrates and seeds again.
+
+```bash
+./scripts/dev-verify.sh
+```
+
+Runs formatting check, lint, typecheck, unit tests and production build.
+
+```bash
+./scripts/phase-1-check.sh
+```
+
+Runs the current Phase 1 verification flow, including database setup, sidecar verification and desktop checks.
+
 ## Package-Specific Commands
 
 ```bash
@@ -151,11 +205,21 @@ Runs web-only development, build, tests, and preview.
 ```bash
 pnpm --filter @edutrack/api run dev
 pnpm --filter @edutrack/api run build
+pnpm --filter @edutrack/api run build:sidecar
+pnpm --filter @edutrack/api run verify:sidecar
 pnpm --filter @edutrack/api run start
 pnpm --filter @edutrack/api run test
 ```
 
-Runs API-only development, build, compiled start, and tests.
+Runs API-only development, build, packaged Windows sidecar build, packaged sidecar verification, compiled start, and tests.
+
+```bash
+pnpm --filter @edutrack/desktop run dev
+pnpm --filter @edutrack/desktop run check
+pnpm --filter @edutrack/desktop run build
+```
+
+Runs the Tauri desktop shell, sidecar-backed Rust/Tauri compile check, and Windows installer build.
 
 ```bash
 pnpm --filter @edutrack/domain run build
@@ -185,3 +249,5 @@ docs/
 ## Version 1 Scope Notes
 
 Version 1 is local and SQLite-only. Next.js, mobile apps, cloud sync, PostgreSQL runtime configuration, finance, attendance, parent/student portals, notifications, and remote web access are intentionally out of scope unless a later ADR approves them.
+
+The Phase 1 deployment spike is documented in `docs/deployment/phase-1-deployment-spike.md`.

apps/api/package.json

@@ -7,17 +7,22 @@
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
+    "build:sidecar": "pnpm --filter @edutrack/shared run build && pnpm --filter @edutrack/db run build && pnpm run build && node scripts/build-sidecar.mjs",
+    "verify:sidecar": "node scripts/verify-sidecar.mjs",
     "start": "node dist/index.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
     "@edutrack/db": "workspace:*",
     "@edutrack/shared": "workspace:*",
+    "better-sqlite3": "13.0.2",
     "fastify": "^4.26.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "@yao-pkg/pkg": "6.22.0",
+    "esbuild": "0.28.2",
     "tsx": "^4.23.12",
     "typescript": "^5.9.3"
   }

apps/api/pkg.sidecar.config.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  assets: [
+    'node_modules/better-sqlite3/prebuilds/win32-x64.node',
+    '../../packages/db/migrations/sqlite/**/*',
+  ],
+  publicPackages: ['better-sqlite3'],
+};

apps/api/scripts/build-sidecar.mjs

@@ -0,0 +1,106 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const require = createRequire(import.meta.url);
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(scriptDir, '..');
+const workspaceRoot = resolve(packageRoot, '..', '..');
+const binariesDir = join(workspaceRoot, 'apps', 'desktop', 'src-tauri', 'binaries');
+const sidecarName = 'edutrack-api-sidecar';
+const pkgCliPath = require.resolve('@yao-pkg/pkg/lib-es5/bin.js');
+const bundledEntryPath = join(packageRoot, 'dist', 'sidecar.cjs');
+const pkgConfigPath = join(packageRoot, 'pkg.sidecar.config.cjs');
+
+const rustcVersion = commandOutput('rustc', ['-vV']);
+const targetTriple = parseRustHostTriple(rustcVersion);
+
+if (!targetTriple.endsWith('windows-msvc')) {
+  throw new Error(
+    `The Phase 1.2 sidecar spike currently targets Windows MSVC, got ${targetTriple}.`
+  );
+}
+
+mkdirSync(binariesDir, { recursive: true });
+
+const outputPath = join(binariesDir, `${sidecarName}-${targetTriple}.exe`);
+
+await build({
+  entryPoints: [join(packageRoot, 'dist', 'index.js')],
+  bundle: true,
+  platform: 'node',
+  target: 'node24',
+  format: 'cjs',
+  external: ['better-sqlite3'],
+  outfile: bundledEntryPath,
+  logLevel: 'info',
+  logOverride: {
+    'empty-import-meta': 'silent',
+  },
+});
+
+run(process.execPath, [
+  pkgCliPath,
+  bundledEntryPath,
+  '--config',
+  pkgConfigPath,
+  '--targets',
+  'node24-win-x64',
+  '--output',
+  outputPath,
+]);
+
+console.log(`Built ${outputPath}`);
+
+function commandOutput(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: workspaceRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(commandFailureMessage(command, args, result));
+  }
+
+  return result.stdout.trim();
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: packageRoot,
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(commandFailureMessage(command, args, result));
+  }
+}
+
+function parseRustHostTriple(rustcVersion) {
+  const hostLine = rustcVersion.split(/\r?\n/).find((line) => line.startsWith('host:'));
+
+  if (!hostLine) {
+    throw new Error('Could not determine the Rust host triple from rustc -vV output.');
+  }
+
+  const hostTriple = hostLine.slice('host:'.length).trim();
+
+  if (!hostTriple) {
+    throw new Error('Rust host triple was empty in rustc -vV output.');
+  }
+
+  return hostTriple;
+}
+
+function commandFailureMessage(command, args, result) {
+  const invocation = `${command} ${args.join(' ')}`;
+
+  if (result.error) {
+    return `Command failed: ${invocation}\n${result.error.name}: ${result.error.message}`;
+  }
+
+  return result.stderr?.trim() || `Command failed: ${invocation}`;
+}