Guides
WebSiteHomeAcademy

Deploy SPA's in ARPIA AI APP Studio

Deploy custom web applications and interactive dashboards within ARPIA

Suggest Edits

Overview

Single-Page Apps (SPA) is a feature in ARPIA that allows you to deploy and manage custom web applications within your Workarea. Upload your HTML, CSS, and JavaScript files to create interactive, client-side applications that integrate seamlessly with your ARPIA environment.

What are Single-Page Apps?

Single-Page Apps in ARPIA are self-contained web applications that run entirely in the browser. They provide a way to extend ARPIA's functionality with custom interfaces, dashboards, tools, and visualizations built using modern web technologies.

Key Features

Version Management

  • Upload multiple versions of your application
  • Customize version names for easy identification
  • Track changes and updates over time
  • Roll back to previous versions when needed
  • Delete old versions to manage storage
  • Publish specific versions to make them live
  • Preview any version before publishing

File Upload System

  • Package your application files (HTML, CSS, JavaScript, Images) into a ZIP archive
  • Simple drag-and-drop upload interface
  • Automatic extraction and deployment
  • Maximum ZIP file size: 25MB when compressed
  • Only .zip format is accepted

Access Control

  • Private Mode: Restrict access to specific users within your Workarea
  • Public Mode: Make your app accessible to any authenticated user in ARPIA
  • Flexible permission settings to control visibility

AI-Generated Documentation

  • Automatic description generation for your application upon first upload
  • AI analyzes your app structure and purpose
  • Edit or customize the generated description as needed
  • Helps users understand what your app does

Changelog

  • Maintain a detailed history of changes across versions
  • Document new features, bug fixes, and improvements
  • Keep stakeholders informed of updates

Usage Analytics & Insights

  • Track when your app is accessed
  • Monitor how many times the app has been opened
  • See usage patterns and engagement metrics

Supported Technologies

Supported

  • HTML5
  • CSS3 (including frameworks like Tailwind, Bootstrap)
  • JavaScript (vanilla JS and frameworks like React, Vue, Angular)
  • Client-side libraries and dependencies
  • Static assets (images, fonts, icons)
  • JSON data files

Not Supported

  • Server-side code (Python, PHP, Node.js, Ruby, etc.)
  • Backend APIs or databases
  • Server-side rendering
  • File system operations
  • Server-side authentication
  • Archive formats other than .zip (no .rar, .7z, .tar.gz)

How to Create a Single-Page App

Prerequisites

Before you begin, ensure you have:

  1. An ARPIA account with access to a Workarea
  2. MCP (Model Context Protocol) configured in ARPIA with the nodes and workspaces you'll use
  3. A development environment (Cursor, VS Code, Lovable, etc.)

Step 1: Configure MCP in Your Development Environment

If you're using Cursor or similar AI-powered IDEs, configure the ARPIA MCP for seamless integration:

A. Access MCP Configuration in Cursor

  1. Open Cursor settings
  2. Navigate to the "Tools & MCP" tab
  3. Select "New MCP Server"


Screenshot showing Cursor settings with Tools & MCP tab and New MCP Server option highlighted

B. Add ARPIA MCP Configuration

  1. In the mcp.json configuration file, add:
{
  "mcpServers": {
    "MCP Arpia": {
      "url": "https://cloud.arpia.ai/mcp/?token=INSERT_TOKEN_HERE"
    }
  }
}
  1. Replace INSERT_TOKEN_HERE with your actual ARPIA MCP token
  2. Save the configuration file


Screenshot of the mcp.json configuration file with ARPIA MCP URL

Step 2: Create SPA in ARPIA Platform

A. Initialize the Application

  1. Navigate to AI Apps Studio in your ARPIA Workarea


Screenshot showing the ARPIA interface with AI Apps Studio highlighted

  1. Click the "+ CREATE APP" button


Screenshot highlighting the "+ CREATE APP" button in the interface

  1. Enter a name for your application
  2. In the "App Type" field, select "Single Page App (SPA)"
  3. Click "CREATE"


Screenshot of the Create App form with App Type dropdown showing "Single Page App (SPA)" option

  1. You'll be redirected to your SPA's main configuration page


Screenshot of the main SPA configuration page after creation

B. Download the ARPIA UX SDK

To ensure your app follows ARPIA's design system and integrates properly:

  1. On your SPA configuration page, locate the dropdown arrow next to the "UPLOAD VERSION" button
  2. Select "Download UX SDK"


Screenshot showing the dropdown menu with "Download UX SDK" option

  1. A ZIP file containing the SDK will be downloaded

The SDK includes:

  • template.html: Base HTML structure
  • instructions.md: Design guidelines and UX patterns
  • README.md: Implementation instructions
  • assets/: Design assets and resources
  • css/: ARPIA styling framework

Step 3: Set Up Your Development Environment

A. Create Project Structure

  1. Create a new folder for your project on your computer
  2. Open the folder in your development environment (Cursor, VS Code, etc.)
    • In Cursor: File → Open Folder


Screenshot showing Cursor's File menu with "Open Folder" option

  1. Extract the contents of the ARPIA UX SDK ZIP file into your project folder


Screenshot showing the file explorer with the arpia-ux-sdk folder extracted

Your project structure should look like:

my-spa-project/
├── arpia-ux-sdk/
│   ├── assets/
│   ├── css/
│   ├── instructions.md
│   ├── README.md
│   └── template.html
├── (your application files will go here)


Screenshot of Cursor showing the arpia-ux-sdk folder structure in the sidebar

B. Review SDK Documentation

Before development, thoroughly review:

  • instructions.md: Contains design guidelines, UX patterns, and conventions
  • README.md: Provides implementation instructions and best practices
  • template.html: Shows the required DOM structure

Step 4: Develop Your Application

A. Use the AI-Assisted Development Prompt

If using AI-powered development tools (Cursor, GitHub Copilot, etc.), use this prompt template to ensure proper integration:

# SPA Development Prompt – ARPIA / Cursor

## Objective
Act as a Frontend Developer using the Arpia UX SDK to develop a **Single Page Application (SPA)** using the **Cursor platform**. Reference `@instructions.md` for class rules and `@template.html` for the DOM structure.

Static assets only (HTML, CSS, JS, images). The server-side request will be managed by the ARPIA platform, so there's no need to create server-side functions or files.

## Context & Resources
- The project includes an **ARPIA-provided UX SDK**.
- Inside the project folder you will find:
  - An **HTML template** that must be used as the base of the application.
  - An `instructions.md` file containing **design guidelines, UX patterns, and conventions**.

⚠️ **You must read and follow both `instructions.md` and `README.md` before making any architectural or implementation decisions.**

## Application Domain
- The application is built on **MCP Arpia**.
- Core entities:
  - **[List your entities, e.g., Leads, Opportunities, Customers]**
- The application must:
  - Display and manage information related to [your entities]
  - Provide tools to **create, update, and manage** [your entities] using MCP Arpia capabilities.

## Development Guidelines
- Follow the **file structure, UX patterns, and conventions** defined by the ARPIA UX SDK.
- Reuse existing templates and components whenever possible.
- Do not introduce new architectural patterns unless clearly justified.
- Keep the codebase **modular, readable, and maintainable**.
- Follow SPA best practices appropriate for the Cursor platform.
- **For the REST API calls, use static Endpoint calls, based on these endpoints, use the MCP collection id as a bearer token:**

"resources": "https://cloud.arpia.ai/mcp/api/v1/collections/{collection_id}/resources",
"tools": "https://cloud.arpia.ai/mcp/api/v1/collections/{collection_id}/tools"

## Assumptions & Clarifications
- **The index.html should be in the root of the folder.**
- **The css file should use relative paths.**
- **Do not assume missing requirements or behaviors.**
- If any part of the scope, data model, APIs, or UX flows is unclear, **ask for clarification before proceeding**.


Screenshot showing Cursor with AI agent developing the application files

B. Development Best Practices

  • Keep your apps lightweight for faster loading
  • Minimize and optimize your JavaScript and CSS
  • Use responsive design for cross-device compatibility
  • Include proper error handling
  • Use relative paths for all file references (no absolute paths)
  • Test across multiple browsers (Chrome, Firefox, Safari, Edge)
  • Follow the structure and patterns in the ARPIA UX SDK

C. File Organization

Ensure your final structure has index.html at the root:

my-app/
├── index.html          # Required at root level
├── styles/
│   └── main.css
├── scripts/
│   └── app.js
├── images/
│   └── logo.png
└── assets/

Step 5: Package Your Application

Once development is complete:

  1. Select all your application files and folders
  2. Compress them into a ZIP archive (must be .zip format)
  3. Ensure the ZIP file includes all necessary dependencies
  4. Verify the archive size does not exceed 25MB
  5. Critical: Confirm index.html is at the root level of the ZIP (not nested in a folder)

Requirements Checklist:

  • ✅ index.html is at the root level
  • ✅ No server-side code (PHP, Python, Ruby, etc.)
  • ✅ Static assets only (HTML, CSS, JS, images)
  • ✅ Total size under 25 MB when compressed
  • ✅ Only .zip format

Step 6: Upload to ARPIA

A. Upload Your First Version

  1. Return to your SPA configuration page in ARPIA
  2. Click "UPLOAD VERSION"


Screenshot showing the UPLOAD VERSION button on the SPA configuration page

  1. In the upload form:
    • Drop your ZIP file in the designated area or click to browse
    • Version Name: Enter a descriptive version name (e.g., "v1.0.0 - Initial Release")
    • Changelog / Release Notes: Describe what's in this version


Screenshot of the Upload Version form with ZIP file uploaded and fields filled

  1. Click "PROCESS VERSION"
  2. Wait for the upload and extraction to complete

B. Review Upload Results

After processing, you'll see:

  • Version listed in the versions table
  • Upload date and timestamp
  • Version size
  • Status indicator


Screenshot showing the version successfully uploaded in the versions table

Step 7: Manage and Deploy Your App

Version Actions

For each version, you have these actions available:

  • Publish Version: Makes this version the active, live version that users will see
  • Open: Opens the version in your browser for preview/testing
  • Download: Downloads the version's files as a ZIP for backup or local testing
  • Delete: Removes the version from the list (cannot delete the currently published version)


Screenshot showing multiple versions (v1, v2, v3) in the version management table


Screenshot showing the Actions dropdown menu with Publish, Open, Download, and Delete options

Publishing Your App

  1. Locate the version you want to make live
  2. Click "Actions" → "Publish Version"
  3. Confirm the publication
  4. The app is now accessible to users based on your access control settings

Step 8: Access Your Deployed App

Once deployed, your app is accessible through:

  1. Direct Link: ARPIA generates a unique URL for your app
    • Format: https://cloud.arpia.ai/spax/[your-app-id]/[app_version]
    • Find the link in the app details page
  2. Workarea Apps Menu: Apps appear in your Workarea's applications list
  3. Sharing: Copy the link to share with authorized users
  4. Bookmarking: Users can bookmark the URL for quick access


Screenshot of the deployed leads management application with navigation, statistics, and data table

Managing Your Apps

Updating Versions

To release a new version of your app:

  1. Make updates to your local application files
  2. Test thoroughly in your development environment
  3. Create a new ZIP archive with your updated files
  4. Navigate to your app in ARPIA
  5. Click "Upload Version"
  6. Upload the new ZIP file
  7. Provide a new version name (e.g., "v1.1.0 - Bug fixes and improvements")
  8. Add detailed changelog entries describing the changes
  9. Click "Process Version"
  10. Once processed, decide whether to:
    • Publish immediately: Make this the active version
    • Keep previous version active: Test the new version first before publishing

Version Rollback

To revert to a previous version:

  1. Navigate to your app's version history
  2. Locate the version you want to activate
  3. Click "Actions" → "Publish Version"
  4. Confirm the rollback action
  5. The selected version becomes the active version immediately

Deleting Versions

To remove old versions:

  1. Go to version management
  2. Select versions to delete (cannot delete the currently published version)
  3. Click "Actions" → "Delete"
  4. Confirm deletion
  5. The version is permanently removed

Access Control

Configure who can access your app:

  • Workarea Private: Only members of your Workarea can access
  • ARPIA Public: Any authenticated ARPIA user can access

To change access settings:

  1. Go to your app's settings
  2. Select access level
  3. Save changes

Monitoring Usage

View analytics about your app:

  • Total Opens: How many times the app has been launched
  • Access Timeline: When the app was accessed
  • Active Version Usage: Which version is being used most
  • User Engagement: Patterns in how users interact with your app

Integration with ARPIA

Accessing ARPIA Data

Single-Page Apps can interact with ARPIA's data through:

  1. ARPIA JavaScript SDK: Include the SDK in your app for seamless integration
  2. MCP API Calls: Make authenticated requests to ARPIA's MCP endpoints
  3. Knowledge Node Queries: Retrieve data from your Workarea's Knowledge Nodes

MCP API Integration

Use the MCP API to access ARPIA resources and tools:

// API Endpoints
const ARPIA_API = {
  resources: "https://cloud.arpia.ai/mcp/api/v1/collections/{collection_id}/resources",
  tools: "https://cloud.arpia.ai/mcp/api/v1/collections/{collection_id}/tools"
};

// Example: Fetch resources
async function fetchResources(collectionId, bearerToken) {
  try {
    const response = await fetch(
      ARPIA_API.resources.replace('{collection_id}', collectionId),
      {
        headers: {
          'Authorization': `Bearer ${bearerToken}`,
          'Content-Type': 'application/json'
        }
      }
    );
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching resources:', error);
    throw error;
  }
}

Authentication

  • Apps inherit the user's ARPIA session
  • No additional authentication required for same-domain API calls
  • Use the ARPIA SDK for automatic credential handling
  • MCP collection ID serves as the bearer token for API calls

Example: Querying Knowledge Node Data

// Using ARPIA SDK
const arpiaClient = new ARPIA.Client();

async function fetchData() {
  try {
    const data = await arpiaClient.knowledgeNode.query({
      node: 'sales-data',
      filters: { year: 2024 }
    });
    console.log(data);
  } catch (error) {
    console.error('Error fetching data:', error);
  }
}

Best Practices

Development

  • Use the ARPIA UX SDK: Always base your app on the provided SDK templates
  • Follow SDK Guidelines: Read and implement instructions.md and README.md patterns
  • Keep apps lightweight: Optimize for faster loading
  • Responsive design: Ensure cross-device compatibility
  • Error handling: Include comprehensive error handling
  • Relative paths: Use relative paths for all file references
  • Browser compatibility: Test across Chrome, Firefox, Safari, Edge
  • Code comments: Document complex logic inline
  • Modular structure: Keep code organized and maintainable

Version Management

  • Semantic versioning: Use standard versioning (e.g., v1.2.3)
    • Major: Breaking changes
    • Minor: New features, backwards compatible
    • Patch: Bug fixes
  • Clear changelogs: Write descriptive release notes
  • Test before publishing: Always preview versions before making them live
  • Keep rollback versions: Maintain previous stable versions
  • Document breaking changes: Clearly note any breaking changes
  • Version naming: Use consistent, descriptive version names

Documentation

  • Enhance AI descriptions: Build on auto-generated descriptions with specifics
  • Document requirements: Note any configuration or setup needs
  • User instructions: Provide clear usage guidelines for end users
  • Support contact: Include support information
  • Code documentation: Add inline comments for complex logic
  • Update regularly: Keep documentation in sync with app changes

Security

  • No hardcoded credentials: Never include sensitive credentials in code
  • Input validation: Validate and sanitize all user inputs
  • Web security: Follow XSS prevention and CSP best practices
  • Update dependencies: Keep libraries and frameworks current
  • CORS awareness: Be mindful when calling external APIs
  • HTTPS only: Use HTTPS for all external resource requests
  • Secure storage: Use secure browser APIs (not localStorage for secrets)
  • Token handling: Properly manage and secure API tokens

Limitations

  • Maximum ZIP file size: 25MB when compressed
  • Only .zip archive format accepted
  • No server-side processing capabilities
  • Limited to client-side JavaScript execution
  • Cannot access server file systems
  • No direct database connections from client code
  • index.html must be at the root level of the ZIP
  • No server-side languages (Python, PHP, Ruby, Node.js)
  • No persistent server storage

Use Cases

Single-Page Apps in ARPIA are perfect for:

  • Custom Dashboards: Visualize data from ARPIA's Knowledge Nodes with interactive charts
  • CRM Tools: Manage leads, opportunities, and customer relationships
  • Interactive Tools: Calculators, converters, and utilities for your team
  • Data Visualizations: Real-time charts, graphs, and reports from ARPIA data
  • Form Builders: Custom input interfaces for data collection
  • Productivity Tools: Task managers, timers, note-taking apps
  • Educational Content: Interactive tutorials and guides
  • Analytics Dashboards: Monitor KPIs and metrics from your Workarea
  • Reporting Tools: Generate custom reports from ARPIA's Reasoning Atlas
  • Sales Management: Track and manage sales pipelines and activities
  • Project Management: Custom project tracking and collaboration tools

Troubleshooting

Common Issues

Upload Fails

  • Verify ZIP file is under 25MB
  • Ensure index.html is at root level (not in a subfolder)
  • Check that only .zip format is used (not .rar, .7z, etc.)
  • Remove any server-side code files

App Doesn't Load

  • Check browser console for JavaScript errors
  • Verify all file paths are relative (not absolute)
  • Ensure all dependencies are included in the ZIP
  • Test the app locally before uploading

API Calls Fail

  • Verify MCP collection ID and bearer token
  • Check API endpoint URLs are correct
  • Ensure proper CORS configuration for external APIs
  • Confirm user authentication is valid

Styling Issues

  • Verify CSS files are properly linked with relative paths
  • Check that ARPIA UX SDK styles are included
  • Test across different browsers
  • Ensure no conflicting CSS frameworks

Support

For additional help:

  • Review the ARPIA UX SDK documentation included with each download
  • Contact your Workarea administrator
  • Submit feedback through the ARPIA platform
  • Check the ARPIA documentation portal for updates

Image Assets

To use this documentation, save the following screenshots in an images/ folder:

  1. 01-cursor-mcp-settings.png - Cursor settings showing Tools & MCP tab
  2. 02-mcp-json-config.png - MCP configuration file example
  3. 03-ai-apps-studio-home.png - ARPIA AI Apps Studio interface
  4. 04-create-app-button.png - "+ CREATE APP" button location
  5. 05-create-app-form.png - Create App form with SPA option
  6. 06-spa-config-page.png - Main SPA configuration page
  7. 07-download-ux-sdk.png - Download UX SDK dropdown option
  8. 08-cursor-open-folder.png - Cursor File menu with Open Folder
  9. 09-project-folder-structure.png - File explorer showing extracted SDK
  10. 10-cursor-file-explorer.png - Cursor sidebar with folder structure
  11. 11-cursor-development.png - Development in progress screenshot
  12. 12-upload-version-button.png - UPLOAD VERSION button
  13. 13-upload-version-form.png - Complete upload form with ZIP file
  14. 14-version-uploaded.png - Version successfully uploaded
  15. 15-multiple-versions.png - Multiple versions in management table
  16. 16-version-actions-dropdown.png - Actions dropdown menu
  17. 17-deployed-app-running.png - Final deployed application

Changelog

Stay informed about updates to the SPA feature:

  • Version tracking for platform improvements
  • New capabilities and integrations
  • Bug fixes and enhancements
  • Best practice updates
I've added image placeholders throughout the documentation with:
- ✅ Descriptive alt text for accessibility
- ✅ Meaningful filenames that match the content
- ✅ Italicized captions explaining what each screenshot shows
- ✅ Strategic placement at the exact steps where users need visual guidance
- ✅ A complete list at the end showing all 17 images needed

The images folder structure should be:

documentation/
├── spa-documentation.md
└── images/
├── 01-cursor-mcp-settings.png
├── 02-mcp-json-config.png
├── 03-ai-apps-studio-home.png
├── ... (all 17 images)
└── 17-deployed-app-running.png

Updated 1 day ago