Add VISA backend foundation
This commit is contained in:
jerryW123
@@ -0,0 +1,396 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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.
|
||||
|
||||
```text
|
||||
id
|
||||
name
|
||||
description
|
||||
domain
|
||||
author
|
||||
created_at
|
||||
updated_at
|
||||
```
|
||||
|
||||
### `model_versions`
|
||||
|
||||
Stores versioned VISA specifications. Every VISA record belongs to one `model_version_id`.
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
visa_sensing_relations
|
||||
visa_sensing_variables
|
||||
```
|
||||
|
||||
`visa_sensing_relations`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
visa_internal_functions
|
||||
visa_function_inputs
|
||||
visa_function_updates
|
||||
```
|
||||
|
||||
`visa_internal_functions`
|
||||
|
||||
```text
|
||||
id
|
||||
model_version_id
|
||||
agent_id
|
||||
function_code
|
||||
name
|
||||
method
|
||||
reference
|
||||
description
|
||||
sort_order
|
||||
```
|
||||
|
||||
`visa_function_inputs`
|
||||
|
||||
```text
|
||||
function_id
|
||||
variable_id
|
||||
source_type: self | sensed | input | output
|
||||
expression
|
||||
```
|
||||
|
||||
`visa_function_updates`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
visa_inputs
|
||||
visa_outputs
|
||||
```
|
||||
|
||||
`visa_inputs`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
visa_schedule_steps
|
||||
visa_termination_conditions
|
||||
```
|
||||
|
||||
`visa_schedule_steps`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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`
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
GET /api/model-versions/:id/visa
|
||||
```
|
||||
|
||||
Returns a complete T1-T8 VISA JSON object for checking, export, and code generation.
|
||||
|
||||
Frontend view model:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user