Skip to content

domain_spec.md

Latest commit

 

History

History
244 lines (191 loc) · 8.24 KB

domain_spec.md

File metadata and controls

244 lines (191 loc) · 8.24 KB

Domain Specification

Context Map

Context Relationships

Upstream Context Downstream Context Relationship Pattern Translation Notes
Viz-Server Flowr-Core CUSTOMER-SUPPLIER Viz-Server reads/writes flow YAMLs

Context Map Diagram

graph TB
    VizServer[Viz-Server] --> FlowrCore[Flowr-Core]
Loading

Anti-Corruption Layers

ACL Protects Context From Context ADR Reference
FlowYamlAdapter Viz-Server Flowr-Core ?

Flowr-Core

Context

The Flowr-Core is the engine that manages the execution and definition of software engineering workflows. It handles the loading of flow definitions from YAML, tracks the current state of a session, and manages transitions between states.

Entities

Name Type Purpose Aggregate Root?
Flow Entity Top-level definition of a workflow, containing states, params, and exits Yes
State Entity A node in the workflow with transitions, attributes, and optional subflow links No
Transition Entity A mapping from a trigger to a target state, potentially guarded by conditions No
Session Entity Tracks the current progress of a user through a flow, including the call stack for subflows Yes
Param Value Object A parameter declaration with an optional default value —
GuardCondition Value Object A mapping of evidence keys to condition expressions —

Relationships

Subject Relation Object Cardinality Notes
Flow contains State 1:N
State has Transition 1:N
Transition targets State N:1
Session tracks Flow 1:1
Session current State 1:1
Session has SessionStackFrame 1:N Used for subflow nesting

Aggregate Boundaries

Aggregate Root Entity Why Grouped See
FlowDefinition Flow Ensuring consistency of states and transitions within a single flow ### Invariants
SessionState Session Atomic updates to current state and stack frames ### Invariants

Data Shapes

Flow

Field Type Required Constraints
flow string Yes
version string Yes
exits list[str] Yes
states list[State] Yes
params list[Param] No

Session

Field Type Required Constraints
flow string Yes
state string Yes
name string Yes
stack list[SessionStackFrame] Yes
params dict Yes

Integration Points

Technology Requirements

Context Requirement Verification
Flowr-Core YAML Loading check flowr.domain.loader
Flowr-Core Atomic Session Storage check flowr.infrastructure.session_store

External Contracts

CLI: flowr check

  • Actor: User
  • Trigger: CLI invocation
  • Input: {flow: string, state: string}
  • Output: {attrs: dict, transitions: list}
  • Side Effects: None (read-only)

CLI: flowr transition

  • Actor: User
  • Trigger: CLI invocation
  • Input: {trigger: string, session: string}
  • Output: {from: string, to: string}
  • Side Effects: Updates session state in store.

Viz-Server

Context

The Viz-Server provides a visual interface for inspecting and editing flow definitions. It acts as a bridge between the raw YAML flow files and a web-based visualization tool.

Entities

Name Type Purpose Aggregate Root?
VizServerConfig Value Object Configuration for the server (host, port, path) —
FlowDefinition Entity A representation of a flow state machine read from disk Yes

Relationships

Subject Relation Object Cardinality Notes
VizServerConfig configures Viz-Server 1:1
Viz-Server manages FlowDefinition 1:N One server can load multiple flows from a path

Aggregate Boundaries

Aggregate Root Entity Why Grouped See
ServerSettings VizServerConfig Grouping server parameters for runtime ### Invariants

Data Shapes

VizServerConfig

Field Type Required Constraints
host string Yes Valid hostname/IP
port integer Yes 1-65535
path string Yes Existing directory path

FlowDefinition

Field Type Required Constraints
flow_id string Yes Unique identifier
states list Yes List of state definitions
transitions list Yes List of transitions

Integration Points

Technology Requirements

Context Requirement Verification
Viz-Server HTTP Server (e.g. FastAPI/Flask) check imports
Viz-Server YAML Parser check imports

Viz-Server -> Flowr-Core

  • Purpose: Load and save flow definitions to disk
  • Trigger: User interaction in the UI
  • Mechanism: Shared Filesystem (YAML files)
  • Pattern: CUSTOMER-SUPPLIER
  • Payload: {flow_data: string}
  • Response: {status: string}
  • Error handling: File not found, YAML syntax error
  • Ownership: Flowr-Core (defines the YAML schema)

External Contracts

CLI: flowr serve

  • Actor: User
  • Trigger: CLI invocation
  • Input: {host: string, port: integer, path: string}
  • Output: {server_url: string} on success
  • Errors:
    • Invalid path -> Error: Path does not exist
    • Port occupied -> Error: Port already in use
  • Side Effects: Starts a background process/server using FastAPI and Uvicorn.
  • Preconditions: flowr[viz] dependencies installed.

API: GET /api/flows

  • Actor: Viz-Frontend
  • Trigger: HTTP GET request
  • Input: {refresh: boolean}
  • Output: list[{name: string, relativePath: string, status: string, error: string}]
  • Errors:
    • Internal Error -> 500 Internal Server Error
  • Side Effects: Triggers flow discovery if refresh=true.

API: GET /api/flows/{flow_id}

  • Actor: Viz-Frontend
  • Trigger: HTTP GET request
  • Input: {flow_id: string}
  • Output: {flow_data: object}
  • Errors:
    • Flow Not Found -> 404 Not Found
    • Internal Error -> 500 Internal Server Error

API: PUT /api/flows/{flow_id}

  • Actor: Viz-Frontend
  • Trigger: HTTP PUT request
  • Input: {flow_data: object}
  • Output: {success: boolean, valid: boolean, violations: list}
  • Errors:
    • Editing Disabled -> 405 Method Not Allowed
    • Write Rejected -> 422 Unprocessable Entity
    • Flow Not Found -> 404 Not Found
    • Write Error -> 500 Internal Server Error
  • Side Effects: Overwrites YAML file on disk.

API: POST /api/flows

  • Actor: Viz-Frontend
  • Trigger: HTTP POST request
  • Input: {filename: string, flow_data: object}
  • Output: {success: boolean, valid: boolean, violations: list}
  • Errors:
    • Editing Disabled -> 405 Method Not Allowed
    • Invalid Input -> 422 Unprocessable Entity (missing filename)
    • Path Traversal -> 422 Unprocessable Entity
    • Write Rejected -> 422 Unprocessable Entity
    • Internal Error -> 500 Internal Server Error
  • Side Effects: Creates new YAML file on disk.

API: DELETE /api/flows/{flow_id}

  • Actor: Viz-Frontend
  • Trigger: HTTP DELETE request
  • Input: {flow_id: string}
  • Output: {success: boolean, deleted: string}
  • Errors:
    • Editing Disabled -> 405 Method Not Allowed
    • Write Rejected -> 422 Unprocessable Entity
    • Flow Not Found -> 404 Not Found
    • Write Error -> 500 Internal Server Error
  • Side Effects: Deletes YAML file from disk.

State Machines

Error Handling

Concurrency and Conflict Resolution

The Viz-Server uses a "last-write-wins" strategy for flow persistence. There is no distributed locking or optimistic concurrency control (e.g., ETags). If multiple users edit the same flow, the final state is determined by the last PUT/POST request processed by the server.

Invariants