# VISA API And Migration Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a real backend API surface and a database schema migration for the VISA backend foundation.

**Architecture:** Add an Express app factory with seeded in-memory VISA data so the API can run without introducing a database driver yet. Add a PostgreSQL migration file that creates the normalized VISA schema described in `docs/visa-backend-database-design.md`.

**Tech Stack:** TypeScript, Express, Node assert tests, PostgreSQL SQL migration.

---

### Task 1: API Tests

**Files:**
- Create: `src/server/visaApi.test.ts`

- [ ] **Step 1: Write failing API tests**

Test `GET /api/model-versions/:id/visa`, `GET /api/model-versions/:id/view-model`, `POST /api/model-versions/:id/actions/run-check`, and a missing model version response.

- [ ] **Step 2: Run the test to verify red**

Run: `npx.cmd tsx src/server/visaApi.test.ts`.
Expected: FAIL because the server app module does not exist.

### Task 2: API Implementation

**Files:**
- Create: `src/server/visaRepository.ts`
- Create: `src/server/visaApi.ts`
- Create: `src/server/index.ts`
- Modify: `package.json`

- [ ] **Step 1: Add in-memory repository**

Seed the repository with `createDefaultVisaSpec()` and expose `getVisaSpec`, `getWorkflowViewModel`, and `runConsistencyCheck`.

- [ ] **Step 2: Add Express app factory**

Expose the VISA JSON endpoint, view-model endpoint, and run-check action.

- [ ] **Step 3: Add server entry and npm script**

Add `src/server/index.ts` and a `server` script using `tsx`.

- [ ] **Step 4: Run API tests**

Run: `npx.cmd tsx src/server/visaApi.test.ts`.
Expected: PASS.

### Task 3: Migration Tests

**Files:**
- Create: `db/migrations/202606230001_create_visa_schema.test.ts`

- [ ] **Step 1: Write failing migration test**

Assert the migration includes the system tables, VISA semantic tables, consistency check table, foreign keys, and indexes.

- [ ] **Step 2: Run the test to verify red**

Run: `npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts`.
Expected: FAIL because the SQL migration does not exist.

### Task 4: Migration SQL

**Files:**
- Create: `db/migrations/202606230001_create_visa_schema.sql`

- [ ] **Step 1: Add PostgreSQL schema migration**

Create model/version tables, VISA T1-T8 normalized tables, consistency check table, foreign keys, uniqueness constraints, and basic indexes.

- [ ] **Step 2: Run migration test**

Run: `npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts`.
Expected: PASS.

### Task 5: Verification

**Files:**
- Modify as needed based on test results.

- [ ] **Step 1: Run model and API tests**

Run:
- `npx.cmd tsx src/workflowModel.test.ts`
- `npx.cmd tsx src/visaModel.test.ts`
- `npx.cmd tsx src/server/visaApi.test.ts`
- `npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts`

- [ ] **Step 2: Run TypeScript check**

Run: `npm.cmd run lint`.