AgentBlock/docs/visa-backend-database-design.md

VISA Backend Database Design

Purpose

The project should treat VISA as a backend model specification protocol, not as a set of frontend tables. The database is the source of truth for reproducible ABM descriptions. The frontend consumes derived view models for graph editing, summaries, validation reports, and export actions.

This design follows the selected approach C:

Database and backend: VISA-native T1-T8 specification
Adapter API: VISA data -> frontend workflow view model
Frontend: modeling interface, not raw database table display

High-Level Architecture

Frontend
  Canvas, forms, summaries, validation report, export actions
        |
        v
Adapter API
  Builds frontend view models from VISA records
  Converts semantic edit actions into VISA updates
        |
        v
Backend Services
  Model versioning
  VISA T1-T8 CRUD
  19-rule consistency checking
  VISA JSON export
  Future code generation
        |
        v
Database
  Model/version metadata
  VISA semantic modules
  Normalized helper tables
  Consistency check results

System Tables

models

Stores the model project.

id
name
description
domain
author
created_at
updated_at

model_versions

Stores versioned VISA specifications. Every VISA record belongs to one model_version_id.

id
model_id
version_name
status: draft | checked | released | archived
source_protocol: VISA
created_by
created_at
notes

VISA Semantic Modules

The database may use more than eight physical tables, but the backend must expose eight VISA semantic modules.

T1 Agent

Physical table: visa_agents

id
model_version_id
name
symbol_set
instance_symbol
category: Environment | Space | Decision-maker | Passive
description
quantity_symbol
quantity_type: fixed | variable
quantity_value
sort_order

Design rule: database records should represent model-semantic agents, not implementation classes. Datasets, output records, and reports belong to T5 or T6, not T1.

T2 Variable

Physical table: visa_variables

id
model_version_id
agent_id
name
symbol
variable_type: exog_homo | exog_hetero | endog_decision | endog_non_decision
data_type
value_source
unit
description
is_time_indexed
sort_order

Design rule: endogenous variables should be traceable to T4 function IDs. Exogenous variables marked as Input must be covered by T6a.

T3 Sensing

Physical tables:

visa_sensing_relations
visa_sensing_variables

visa_sensing_relations

id
model_version_id
observer_agent_id
observed_agent_id
access_type: none | partial | all
scope: self | peer | other | all | singleton
condition
notes

visa_sensing_variables

sensing_relation_id
variable_id

Design rule: store sensing as normalized relations rather than a wide matrix. The backend can reconstruct the VISA matrix for export and can check whether T4 functions use only authorized information.

T4 Internal Function

Physical tables:

visa_internal_functions
visa_function_inputs
visa_function_updates

visa_internal_functions

id
model_version_id
agent_id
function_code
name
method
reference
description
sort_order

visa_function_inputs

function_id
variable_id
source_type: self | sensed | input | output
expression

visa_function_updates

function_id
target_agent_id
variable_id
update_type: self_state | external_effect | create_agent | remove_agent
expression

Design rule: every internal function must update at least one endogenous variable or create/remove an instance of a variable-quantity agent type.

T5 Associated Data

Physical table: visa_associated_data

id
model_version_id
data_code
title
data_type: Empirical | Literature | Generated
temporal_type: Static | Dynamic
source
collection_method: Survey | Administrative | Sensor | Experimental | Computational
preprocessing_method: None | Selected | Aggregated | Transformed
record_count
availability: Open | Restricted | Private
license
url_or_reference
description

Design rule: this table records data provenance. It is not merely a source-column lookup table.

T6 Input and Output

Physical tables:

visa_inputs
visa_outputs

visa_inputs

id
model_version_id
agent_id
variable_id
symbol
value_or_distribution
data_source_id
derivation: Direct | Estimated | Computed | Assumed
algorithm
reference
notes

visa_outputs

id
model_version_id
symbol
indicator_name
formula
data_type
unit
frequency
description

Design rule: T6a covers exogenous model inputs. T6b covers simulation output indicators. Component-to-component frontend wiring is a derived view, not the canonical T6 design.

T7 Schedule

Physical tables:

visa_schedule_steps
visa_termination_conditions

visa_schedule_steps

id
model_version_id
step_number
agent_id
function_id
execution_mode: Synchronous | Sequential | Random-order | Asynchronous
execution_parameters
condition
sort_order

visa_termination_conditions

id
model_version_id
condition_code
indicator_symbol
condition_expression
description
value_source
termination_logic

Design rule: execution mode must be structured because synchronization choices can change ABM behavior.

T8 Validation

Physical table: visa_validations

id
model_version_id
validation_code
level: Agent | Model | Output
validation_object
benchmark_data_id
method
indicator
passing_condition
reference
status: pending | passed | failed | blocked
notes

Design rule: T8 is scientific model validation. It should not be mixed with the 19-rule consistency checker.

Consistency Check Results

Physical table: visa_consistency_check_results

id
model_version_id
rule_code
rule_type: within_table | cross_table
status: passed | failed | warning
message
related_table
related_record_id
checked_at

The backend should run the VISA 19-rule checker against a complete model version and persist results here. These records drive frontend check reports.

Frontend Boundary

The frontend must not present the database as eight raw table pages. It should provide modeling workflows:

Model overview
Agent and space designer
Variable editor
Behavior/function designer
Data source manager
Schedule builder
Validation and check report
Export/generate actions

These screens are allowed to show summaries, forms, cards, graphs, and reports. They should not make the user edit visa_agents or visa_variables as database rows.

Adapter Contract

The adapter layer should expose two families of API responses.

Canonical VISA:

GET /api/model-versions/:id/visa

Returns a complete T1-T8 VISA JSON object for checking, export, and code generation.

Frontend view model:

GET /api/model-versions/:id/view-model

Returns graph nodes, graph edges, grouped variables, behavior cards, schedule timeline items, and validation summaries derived from VISA records.

Semantic edit actions:

POST /api/model-versions/:id/actions/add-agent
POST /api/model-versions/:id/actions/add-variable
POST /api/model-versions/:id/actions/add-function
POST /api/model-versions/:id/actions/run-check

The backend translates these actions into normalized VISA writes and refreshes the derived view model.

First Implementation Step

The current frontend can remain on WorkflowModel while a VISA adapter is introduced. The adapter converts:

T1 Agent -> workflow nodes
T3 Sensing + T4 Internal Function -> view edges and behavior sections
T5 Associated Data -> associated data rows
T6 Input/Output -> I/O rows
T7 Schedule -> schedule rows
T8 Validation -> validation rows

This keeps the existing UI functional while moving the source of truth toward the backend VISA model.