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 @ventionco/machine-ui and @ventionco/machine-apps-components assets

Project Structure

machine-code-demo/
├── customui/                          # React frontend source code
│   └── src/
│       ├── 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
│       └── main.tsx                   # Application entry point
├── app.py                             # State machine implementation
├── models.py                          # Data models
├── requirements.txt                   # Python dependencies
├── server.py                          # FastAPI server
└── [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 multiplication 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:

Automatic CRUD APIs: Generated REST endpoints for all models
Audit Trails: All operations tracked with user attribution
Bootstrap Integration: One-command setup with vention-storage

`requirements.txt`

Python dependencies including:

fastapi - Modern web framework
uvicorn - ASGI server
vention-state-machine - State machine library
vention-storage - Data persistence with audit trails
sqlmodel - Type-safe database models

Frontend Files

`customui/src/app/app.tsx`

Main application page, contains:

Status Indicator and Robot Controls: Leveraging @ventionco/machine-app-components
Routing: React router for the quiz and settings pages

`customui/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

`customui/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

`customui/src/app/pages/`

The individual pages:

operation-page.tsx: The reach study quiz itself, triggers transitions in the state machine
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 automatic CRUD APIs and audit trails
Type Safety: Front-to-back strong typing with complete openAPI spec
Modern UI: React with Material-UI components and responsive design
Development Experience: Hot reload, auto-reload, and comprehensive API documentation

Demo Application: Multiplication Quiz

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 multiplication quiz 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 Material-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 multiplication 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)
    first_number: int
    second_number: int
    solution: Optional[int] = None   # User-provided answer
    correct: Optional[bool] = None   # Auto-evaluated correctness

class Configuration(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    max_number: int = Field(default=12)        # Max operand value
    timeout_seconds: int = Field(default=10)   # Answer timeout

Key Features Demonstrated:

Automatic CRUD API: Full REST endpoints generated automatically (/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 generated API types

Storage Operations:

Quiz Creation: New problems automatically inserted with audit trail
Answer Validation: Solutions validated against correct answer 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 correct solution
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 Number: Controls difficulty (operands from 1 to max_number)
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 uvicorn backend.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