feat: bootstrap initial Convex backend

.github/workflows/baseline-checks.yml

@@ -17,6 +17,7 @@ jobs:
   lint-web:
     name: Lint Web
     runs-on: ubuntu-latest
+    timeout-minutes: 10
 
     steps:
       - name: Checkout
@@ -40,6 +41,7 @@ jobs:
   typecheck-web:
     name: Typecheck Web
     runs-on: ubuntu-latest
+    timeout-minutes: 10
 
     steps:
       - name: Checkout
@@ -60,10 +62,62 @@ jobs:
       - name: Run typecheck
         run: pnpm typecheck:web
 
+  typecheck-backend:
+    name: Typecheck Backend
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run backend typecheck
+        run: pnpm typecheck:backend
+
+  verify-backend-local:
+    name: Verify Backend Local
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Verify backend bootstrap
+        run: pnpm verify:backend:local
+
+      - name: Check generated backend files
+        run: git diff --exit-code -- convex/_generated
+
   build-web:
     name: Build Web
-    needs: [lint-web, typecheck-web]
+    needs: [lint-web, typecheck-web, typecheck-backend, verify-backend-local]
     runs-on: ubuntu-latest
+    timeout-minutes: 15
 
     steps:
       - name: Checkout

.gitignore

@@ -2,3 +2,7 @@ AGENTS.local.md
 .opencode/state/
 node_modules/
 .husky/_/
+.convex-home/
+.convex-tmp/
+.env
+.env.local

README.md

@@ -7,20 +7,32 @@
 - `AGENTS.md` - repo-wide agent rules and durable workflow defaults
 - `AGENTS.local.md.example` - local operator preference template for `AGENTS.local.md`
 - `apps/web` - initial `Next.js` web application scaffold
+- `convex` - initial Convex backend functions, schema, and generated API types
 - `docs/README.md` - docs entry point
 - `docs/planning/` - product, architecture, roadmap, backlog, and issue-planning docs
 - `docs/agentic/` - software-factory, onboarding, and agent workflow docs
+- `docs/backend/` - backend setup notes and implementation-facing docs
 - `.opencode/skills/` - repo-local skills, including onboarding
 
-## Local app bootstrap
+## Local bootstrap
 
 - install workspace dependencies: `pnpm install`
 - install git hooks after dependency changes if needed: `pnpm prepare`
+- bootstrap an anonymous local Convex deployment and run the backend health query: `pnpm bootstrap:backend:local`
+- keep the local Convex backend watcher running: `pnpm dev:backend:local`
+- run the one-shot local Convex health check alias: `pnpm run:backend:health:local`
+- typecheck Convex backend files: `pnpm typecheck:backend`
+- re-run the local backend verification pass: `pnpm verify:backend:local`
+- confirm committed Convex codegen is current: `pnpm check:backend:generated`
 - run the web app: `pnpm dev:web`
 - lint the web app: `pnpm lint:web`
 - typecheck the web app: `pnpm typecheck:web`
 - build the web app: `pnpm build:web`
-- run the baseline local verification pass: `pnpm verify:web`
+- run the baseline local verification pass: `pnpm verify`
+
+Convex writes repo-root deployment configuration to `.env.local` during local setup and keeps anonymous local state under `.convex-home/` plus `.convex-tmp/`. Keep all of those uncommitted. The committed `convex/_generated/` files are expected to stay clean after `pnpm check:backend:generated`.
+
+`pnpm verify` is the full repo verification pass and now includes the local Convex bootstrap checks. If you are iterating on the web app only, use `pnpm verify:web` for the lighter web-only path.
 
 ## Start here
 
@@ -39,6 +51,7 @@ Important planning note:
 Currently locked stack direction:
 
 - `Next.js`
+- `TypeScript`
 - `Convex`
 - `AWS`
 - `Stripe`

apps/web/src/app/page.tsx

@@ -7,7 +7,7 @@ export default function Home() {
             <div className="flex flex-col gap-8">
               <div className="flex items-center gap-3 text-sm uppercase tracking-[0.28em] text-muted">
                 <span className="rounded-full border border-border px-3 py-1">VRDex</span>
-                <span>Initial web scaffold</span>
+                <span>Web + backend bootstrap</span>
               </div>
 
               <div className="max-w-3xl space-y-5">
@@ -65,7 +65,7 @@ export default function Home() {
                 </div>
                 <div className="flex items-start justify-between gap-4">
                   <dt className="text-muted">Next issues</dt>
-                  <dd className="text-right font-medium">#54, #55, #56, #59</dd>
+                  <dd className="text-right font-medium">#55, #56, #59</dd>
                 </div>
               </dl>
             </aside>
@@ -92,11 +92,13 @@ export default function Home() {
               Deliberately deferred
             </p>
             <h2 className="mt-4 text-2xl font-semibold tracking-[-0.03em]">
-              Backend and auth wiring
+              App integration and auth wiring
             </h2>
             <p className="mt-3 text-sm leading-7 text-muted">
-              Convex, identity providers, billing, and deployment posture stay in
-              their own issues so this bootstrap remains easy to reason about.
+              Convex now has a real backend foothold under{" "}
+              <code className="font-mono text-[0.95em]">convex/</code>, while app
+              integration, identity providers, billing, and deployment posture
+              stay in their own follow-on issues.
             </p>
           </article>
 

convex.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "./node_modules/convex/schemas/convex.schema.json",
+  "node": {
+    "nodeVersion": "22"
+  }
+}

convex/README.md

@@ -0,0 +1,18 @@
+# Convex Backend
+
+This directory holds the initial Convex backend slice for `VRDex`.
+
+- `health.ts` exposes the placeholder public query `health:status`
+- `schema.ts` keeps the starting schema explicit and intentionally empty
+- `_generated/` contains committed Convex codegen output and should not be edited by hand
+- `tsconfig.json` is the Convex-managed TypeScript config for backend functions
+
+Use the repo-root scripts for local work:
+
+- `pnpm bootstrap:backend:local`
+- `pnpm dev:backend:local`
+- `pnpm run:backend:health:local`
+- `pnpm typecheck:backend`
+- `pnpm check:backend:generated`
+
+The canonical workflow notes live in `docs/backend/convex-bootstrap.md`.

convex/_generated/api.d.ts

@@ -0,0 +1,49 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as health from "../health.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  health: typeof health;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

convex/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();

convex/_generated/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;