Starter Template

This starter template helps you build machine applications — apps that control or monitor Vention-powered automation systems.
It comes with everything you need to get started quickly:

🧠 A Python backend that defines how your machine behaves
💾 A database layer that remembers configurations and results
💻 A React frontend that operators interact with

It uses three key tools from the Vention Developer Toolkit:

Vention Storage — Saves and tracks your app’s data
Vention State Machine — Controls the application logic
Machine UI — Low level Vention-styled UI components

Overview

This starter template provides a complete example of building modern machine applications using the Vention developer toolkit. It includes:

State Machine: Real-time demo application using vention-state-machine
Data Storage: Persistent storage with audit trails using vention-storage
React Frontend: Modern UI using @vention/machine-ui and @vention/machine-apps-components assets

Project Structure

machine-code-demo/
├── backend/                           # Python backend
│   ├── app.py                         # State machine implementation
│   ├── models.py                      # Data models
│   ├── requirements.txt               # Python dependencies
│   ├── server.py                      # FastAPI server
│   └── data/                          # SQLite database (created on first run)
├── src/                               # React frontend source code
│   ├── app/                           # Main application components
│   │   ├── pages/                     # Page components
│   │   ├── api.ts                     # Type-safe API client
│   │   ├── app-context.tsx            # React context for state management
│   │   └── app.tsx                    # Main app component and router
│   ├── i18n/                          # Translations (en, fr, de, es)
│   └── main.tsx                       # Application entry point
└── [build config files]

Backend Files

`app.py`

Core state machine implementation using vention-state-machine. This file contains:

Robot Reach Study State Machine: Three-state workflow (generating → presenting → grading)
Automatic Timeouts: Configurable timeout handling with countdown timers
Guard Conditions: Answer validation before state transitions

`models.py`

Data models using SQLModel for vention-storage integration:

Quiz Model: Stores reach study problems and user answers
Configuration Model: Runtime settings for configuring the quiz
Automatic Validation: Built-in answer correctness calculation

`server.py`

FastAPI server that provides:

CRUD APIs: REST endpoints for all models
State Machine API: Endpoints to read the current state and trigger transitions
Audit Trails: All operations tracked with user attribution
Bootstrap Integration: One-command setup with vention-storage

`requirements.txt`

Python dependencies:

uvicorn - ASGI server
vention-state-machine - State machine library
vention-storage - Data persistence with audit trails

Frontend Files

`src/app/app.tsx`

Main application page, contains:

Status Bar and Navigation: Leveraging @vention/machine-apps-components
Routing: React router for the operation, quiz, components, logs, and settings pages

`src/app/api.ts`

API helpers for communicating with the backend:

Types: Request/Response models for all endpoints
REST endpoints: Strongly typed REST calls using fetch

`src/app/app-context.tsx`

React context provider:

Hooks: Provide granular access to specific parts of the context
Callbacks: Memo wrapper around the API calls
Data Store: Remember the latest state/quiz from the backend

`src/app/pages/`

The individual pages:

operation-page.tsx: The operation dashboard with robot controls, triggers transitions in the state machine
quiz-page.tsx: The reach study quiz itself
components-demo-page.tsx: A showcase of the available Machine UI components
logs-page.tsx: The application logs panel
settings-page.tsx: The app configuration page, reads/writes to the database through the storage module

Key Features Demonstrated

This starter template showcases:

Modern State Management: Using vention-state-machine for complex application workflows
Persistent Data Storage: Using vention-storage with CRUD APIs and audit trails
Type Safety: Front-to-back strong typing with complete openAPI spec
Modern UI: React with Vention Machine UI components and responsive design
Development Experience: Hot reload, auto-reload, and comprehensive API documentation

Demo Application: Robot Reach Study

This starter template includes a complete demo application that showcases how to build a real-time, state-driven application using the Vention developer toolkit libraries. The demo is a robot reach study quiz — the user is shown a stack of boxes and answers whether the robot can reach them — that demonstrates best practices for:

State Management: Using vention-state-machine for complex application workflows
Data Persistence: Using vention-storage for robust data management with audit trails
Modern UI: React frontend with Vention Machine UI components

How Vention Libraries Are Used

🎯 Vention State Machine (`vention-state-machine`)

The demo showcases a sophisticated state machine with three main states:

class QuizStates(StateGroup):
    generating: State = State()    # Creating new problems
    presenting: State = State()    # Displaying problems to user
    grading: State = State()       # Waiting for user input

Key Features Demonstrated:

Declarative State Definition: Using StateGroup and State classes for type-safe state management
Automatic Timeouts: Problems auto-fault if not answered within the timeout period
Guard Conditions: Only correct answers can trigger state transitions
Lifecycle Hooks: State entry/exit callbacks for UI updates and countdown timers

State Flow:

generating → Creates new reach study problem (1s delay)
presenting → Displays problem to user (immediate transition)
grading → Waits for user answer with countdown timer
fault → Entered if timeout expires (auto-recovery via reset)

💾 Vention Storage (`vention-storage`)

The demo uses vention-storage for robust data management with automatic audit trails:

Data Models:

class Quiz(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    box_height: int                       # Height of each box (mm)
    num_boxes: int                        # Number of boxes in the problem
    can_reach: Optional[bool] = None      # User's answer: can the robot reach?
    correct: Optional[bool] = None        # Auto-evaluated correctness

class Configuration(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    max_box_height: int = Field(default=150)    # Max box height (mm)
    timeout_seconds: int = Field(default=10)    # Answer timeout
    robot_reach: int = Field(default=1750)      # Robot arm reach (mm)

Key Features Demonstrated:

CRUD API: Full REST endpoints (/quiz/, /config/)
Audit Trails: All data changes tracked with actor attribution (X-User header)
Lifecycle Hooks: Before-update validation to auto-calculate correct answers
Bootstrap System: One-command setup with bootstrap() function
Type Safety: Full TypeScript integration with a typed API client

Storage Operations:

Quiz Creation: New problems automatically inserted with audit trail
Answer Validation: Answers validated against the robot's reach with automatic correct field update
Configuration Management: Runtime settings stored and retrieved via REST API
Audit Logging: All operations tracked with timestamps and user attribution

Demo Workflow

Startup: State machine begins in ready state, configuration loaded from storage
Problem Generation: User triggers start → generating state → creates new quiz problem
Problem Presentation: Auto-transitions to presenting → displays problem to user
Answer Collection: Enters grading state → starts countdown timer → waits for user input
Answer Validation: User submits answer → stored in database → validated against the robot's reach
State Transition: If correct → returns to generating for next problem; if timeout → enters fault
Recovery: User can reset from fault state to continue

Real-time Features

Progress Indicators: Visual countdown timer showing time remaining
Error Handling: Graceful fault state with user-friendly recovery options
Responsive UI: State-driven rendering with appropriate loading states and feedback

Configuration Options

The demo supports runtime configuration via the storage system:

Maximum Box Height: Controls difficulty (box heights from 100 to max_box_height)
Robot Reach: The reach distance answers are validated against
Timeout Seconds: How long users have to answer each problem
Real-time Updates: Configuration changes immediately affect new problems

This demo serves as a comprehensive example of how to build production-ready applications using the Vention developer toolkit, showcasing both the power and simplicity of the state machine and storage libraries.

Notes

The demo application runs independently and can be tested locally using cd backend && uvicorn server:app --reload
The React UI will only be visible when accessing the HMI in the MachineLogic platform or locally
The application uses SQLite for data persistence, which is automatically created on first run
All data operations are automatically audited with timestamps and user attribution

Starter Template

Table of Contents

Overview

Project Structure

Backend Files

app.py

models.py

server.py

requirements.txt