---
title: "Starter Template"
slug: "starter-template"
updated: 2025-10-28T23:11:21Z
published: 2025-10-28T23:11:21Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vention.io/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: Multiplication Quiz](/docs/starter-template#demo-application-multiplication-quiz)
  - [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 `@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:**

1. `generating` → Creates new multiplication 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)
    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

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 correct solution
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 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