---
title: "Starter Template"
slug: "starter-template"
updated: 2026-08-14T19:15:05Z
published: 2026-08-14T19:15:05Z
canonical: "docs.vention.com/starter-template"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vention.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://pypi.org/project/vention-storage/) — Saves and tracks your app’s data
- [Vention State Machine](https://pypi.org/project/vention-state-machine/) — Controls the application logic
- [Machine UI](https://assets.vention.com/machine-ui-storybook/index.html?path=/) — Low level Vention-styled UI components

## Table of Contents

- [Overview](/docs/starter-template#overview)
- [Project Structure](/docs/starter-template#project-structure)
- [Backend Files](/docs/starter-template#backend-files)
- [Frontend Files](/docs/starter-template#frontend-files)
- [Key Features Demonstrated](/docs/starter-template#key-features-demonstrated)
- [Demo Application: Robot Reach Study](/docs/starter-template#demo-application-robot-reach-study)
  - [How Vention Libraries Are Used](/docs/starter-template#how-vention-libraries-are-used)
  - [Demo Workflow](/docs/starter-template#demo-workflow)
  - [Real-time Features](/docs/starter-template#real-time-features)
  - [Configuration Options](/docs/starter-template#configuration-options)
- [Notes](/docs/starter-template#notes)

## 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:**

1. `generating` → Creates new reach study problem (1s delay)
2. `presenting` → Displays problem to user (immediate transition)
3. `grading` → Waits for user answer with countdown timer
4. `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

1. **Startup**: State machine begins in `ready` state, configuration loaded from storage
2. **Problem Generation**: User triggers `start` → `generating` state → creates new quiz problem
3. **Problem Presentation**: Auto-transitions to `presenting` → displays problem to user
4. **Answer Collection**: Enters `grading` state → starts countdown timer → waits for user input
5. **Answer Validation**: User submits answer → stored in database → validated against the robot's reach
6. **State Transition**: If correct → returns to `generating` for next problem; if timeout → enters `fault`
7. **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