AgentBlock/docs/superpowers/plans/2026-06-23-visa-backend-foundation.md

VISA Backend Foundation 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 VISA-native backend/database foundation while keeping the current frontend workflow model compatible through an adapter.

Architecture: Define VISA T1-T8 as backend-oriented domain structures, add a canonical sample specification, and convert that specification into the existing WorkflowModel view model. Keep the database design in documentation for the next backend phase.

Tech Stack: TypeScript, Node assert tests, Vite React, Markdown database design documentation.

---

Task 1: Adapter Tests

Files:

• Create: src/visaModel.test.ts

• Step 1: Write tests for VISA-to-workflow conversion

Create tests that assert the adapter exposes VISA agents as frontend workflow nodes, internal functions as behavior sections, sensing records as observable rows, and model-level tables as schedule/data/I-O/validation rows.

• Step 2: Run test to verify it fails

Run: npx tsx src/visaModel.test.ts Expected: FAIL because visaModel does not exist yet.

Task 2: VISA Domain Model

Files:

• Create: src/visaModel.ts

• Step 1: Define VISA T1-T8 TypeScript interfaces

Define backend-facing types for agents, variables, sensing relations, internal functions, associated data, inputs, outputs, schedule steps, termination conditions, validations, and consistency check results.

• Step 2: Add a canonical default VISA specification

Create createDefaultVisaSpec() using the existing segregation-style example but expressed as VISA T1-T8 rather than frontend tables.

Task 3: Workflow Adapter

Files:

• Modify: src/visaModel.ts

• Step 1: Implement buildWorkflowFromVisaSpec

Convert T1 agents into workflow nodes, selected T3/T4 relations into view edges and behavior sections, and T5-T8 records into the existing table rows.

• Step 2: Run adapter tests

Run: npx tsx src/visaModel.test.ts Expected: PASS.

Task 4: Database Design Documentation

Files:

• Create: docs/visa-backend-database-design.md

• Step 1: Document the database schema

Write the scheme as eight VISA semantic modules plus normalized helper tables for sensing/function references, model versions, and consistency check results.

• Step 2: Document frontend boundary

State that the frontend must not show the eight tables as raw database tables; it consumes view models derived from VISA data.

Task 5: Verification

Files:

• Modify as needed based on test results.

• Step 1: Run all model tests

Run: npx tsx src/workflowModel.test.ts and npx tsx src/visaModel.test.ts.

• Step 2: Run TypeScript lint

Run: npm run lint.

• Step 3: Report status

Summarize changed files, tests, and remaining backend work.