Skip to content

Tutorial: Your First App

This tutorial walks you through creating a complete Virtualitics SDK app from start to finish.

What You'll Build

A simple data analysis app that:

  1. Loads a CSV file
  2. Displays summary statistics
  3. Creates visualizations
  4. Allows filtering and export

Prerequisites

  • Python 3.11+
  • Virtualitics AI Platform installed
  • Basic pandas knowledge

Step 1: Project Setup

Create a new directory for your app:

mkdir my_first_app
cd my_first_app

Create the following structure:

my_first_app/
├── __init__.py
├── app.py
└── requirements.txt

Step 2: Define Requirements

requirements.txt: 

virtualitics-sdk>=1.54.0
pandas>=2.0.0
plotly>=5.0.0

Step 3: Create Your First Step

app.py: 

from virtualitics_sdk import (
    App, Step, StepType, Page, Section, Card,
    Table, PlotlyPlot, SingleDropdown, Dataset
)
import pandas as pd
import plotly.express as px

class LoadDataStep(Step):
    """Load and display CSV data."""

    def run(self, flow_metadata):
        # Load sample data
        df = pd.DataFrame({
            'Month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
            'Sales': [1200, 1500, 1100, 1800, 2000],
            'Region': ['North', 'South', 'North', 'West', 'East']
        })

        # Create dataset
        dataset = Dataset(name="Sales Data", data=df)
        self._outLink.sales_data = dataset

        # Display table
        return Page(
            title="Data Loaded",
            sections=[
                Section(
                    title="Sales Data",
                    cards=[
                        Card(
                            title="Raw Data",
                            content=[Table(data=df)]
                        )
                    ]
                )
            ]
        )

Step 4: Add Visualization Step

Add to app.py: 

class VisualizeStep(Step):
    """Create visualizations."""

    def run(self, flow_metadata):
        # Get data from previous step
        df = self._inLink.sales_data.data

        # Create plot
        fig = px.bar(
            df,
            x='Month',
            y='Sales',
            color='Region',
            title='Sales by Month and Region'
        )

        return Page(
            title="Visualizations",
            sections=[
                Section(
                    title="Sales Analysis",
                    cards=[
                        Card(
                            title="Sales Chart",
                            content=[PlotlyPlot(figure=fig)]
                        )
                    ]
                )
            ]
        )

Step 5: Create the App

Add to app.py: 

# Create app instance
my_app = App(
    name="Sales Analysis",
    description="Analyze monthly sales data",
    is_shareable=True
)

# Create step instances
load_step = LoadDataStep(
    title="Load Data",
    description="Load sales data",
    parent="Data",
    type=StepType.INPUT,
    page=Page(title="Loading...", sections=[])
)

viz_step = VisualizeStep(
    title="Visualize",
    description="Create charts",
    parent="Analysis",
    type=StepType.DASHBOARD,
    page=Page(title="Loading...", sections=[])
)

# Chain steps together
my_app.chain([load_step, viz_step])

Step 6: Make App Discoverable

__init__.py: 

from .app import my_app

__all__ = ['my_app']

Step 7: Deploy Locally

Add to docker-compose.yml: 

services:
  backend:
    environment:
      - PROJECTS_LIST=["predict_demos", "my_first_app"]
    volumes:
      - ./my_first_app:/opt/app-root/src/my_first_app

Restart the platform: 

docker-compose down
./start.sh

Step 8: Test Your App

  1. Navigate to http://localhost:3000
  2. Find "Sales Analysis" in the app list
  3. Click to run the app
  4. Verify data loads and chart displays correctly

Next Steps

Complete Code

See the full example in the Examples Gallery.