Deploy SPA's in ARPIA AI APP Studio

Overview#

Single-Page Apps (SPA) let you build and deploy custom web apps inside your ARPIA Workarea — dashboards, tools, and visualizations that run in the browser and can read your ARPIA data.

You can build a SPA two ways:

• Inside ARPIA with the built-in Edit Code editor and the ARPIA Codex AI assistant — no external tools needed. (Recommended.)
• On your own computer, then upload a ZIP. (For people with an existing IDE/toolchain.)

🟢 New here? Jump to the Quickstart below. Everything after it is reference material you can read later.

Quickstart: Build Your First SPA in 5 Steps#

The fastest path to a working app — no setup, no data wiring, no ZIP files.

1. Create the app. Go to AI Apps Studio → + CREATE APP. Name it, pick Private, click CREATE.
2. Open the editor. On your app's page, click Edit Code. A starter index.html is already built for you.
3. Ask Codex to build it. Open the ARPIA Codex panel, set mode to Build, and type what you want — e.g. "Make a page with a title and three cards."
4. Preview it. Click Preview to see it live. Use Console if something looks off.
5. Publish. Click Save a Version, then Actions → Publish Version. Your app is live.

✅ That's a working SPA. To connect data, add AI tools, or develop locally, read on.

Key Terms (read once, then move on)#

How to Create a Single-Page App#

Prerequisites#

Minimum to start (Quickstart / Path A):

1. An ARPIA account with access to a Workarea

Also needed for data-connected apps:

2. MCP configured in ARPIA with the nodes/workspaces you'll use — required only for private SPAs that expose MCP Collections or a Workshop API
3. (Path B only) An external IDE such as Cursor or VS Code

Step 1: Create the SPA in ARPIA#

1. Navigate to AI Apps Studio in your Workarea

2. Click "+ CREATE APP"

3. Enter a name for your application
4. (Optional) Add it to a group to stay organized — select an existing group, or type a new name and press Add
5. In Privacy, choose Public or Private.
   Tip

   Not sure? Pick Private if you'll use AI tools or Workshop APIs, or want it limited to your Workarea. Pick Public for a read-only widget any ARPIA user can open.

6. (Optional) Add a Description of what your SPA does
7. Click "CREATE"

You'll land on your SPA's main configuration page.

Step 2: Choose Your Path#

🟢 New here? Use Path A. It's the recommended path and needs no external tools. Skip Path B until you specifically need an offline/IDE workflow.

• Path A — In-Platform (Edit Code): Build inside ARPIA with Edit Code, Codex, live preview, and native data wiring. Recommended for most users.
• Path B — External + ZIP Upload: Develop locally in your own IDE, then upload a ZIP. Advanced / optional.

Both paths share the same publishing and access steps (Step 3 and Step 4).

Path A — In-Platform Development with Edit Code#

The fastest way to build. Everything happens inside ARPIA.

A1. Open the Editor#

From your SPA configuration page, click Edit Code.

A new SPA opens pre-scaffolded with:

• index.html — your entry point (keep it at the root)
• arpia-font.css — ARPIA fonts
• spa.css — ARPIA UX SDK styling

A2. Work With Your Files#

Create and organize .html, .css, and .js files, edit them side by side, and keep index.html at the root.

A3. Build With ARPIA Codex#

1. Open the Codex panel
2. Select the model to use
3. Pick a mode: * Explore — reads and explains your code, changes nothing * Planning — drafts a plan and waits for your OK * Build — applies changes to your files
4. Review, refine your prompt, re-run

A4. Connect Your Data — Knowledge Ontology Relationship#

This is where you let your app (and Codex) use your data.

1. Open the Knowledge Ontology Relationship button
2. Choose which nodes the SPA can read
3. Attach the Actions the SPA is allowed to run
4. For private SPAs, you can also attach: * MCP Collections — groups of endpoints with context for AI models * Workshop API — a POST endpoint that runs a workflow of code + native ARPIA objects

Once set, Codex automatically knows your node structures and API schemas.

A5. Preview and Debug#

• Preview — see and use your app live
• Console — read logs and debug JavaScript, in-platform

A6. Keep ARPIA Modules Up to Date#

A7. Save a Version#

Click Save a Version. Publishing and rollback work as in Step 3 and Step 4.

Path B — External Development & ZIP Upload#

B1: Configure MCP in Your IDE (Cursor example)#

1. Cursor settings → Tools & MCP → New MCP Server
2. In mcp.json, add:

{
  "mcpServers": {
    "MCP Arpia": {
      "url": "https://cloud.arpia.ai/mcp/?token=INSERT_TOKEN_HERE"
    }
  }
}

3. Replace INSERT_TOKEN_HERE with your ARPIA MCP token, then save.

B2: Download the ARPIA UX SDK#

On your SPA page, open the dropdown next to "UPLOAD VERSION" → "Download UX SDK".

The SDK ZIP contains template.html, instructions.md, README.md, an assets/ folder, and a css/ framework.

B3: Set Up Your Project#

1. Create a project folder and open it in your IDE
2. Extract the SDK ZIP into it:

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

Use the SDK's template.html as the basis for your index.html at the project root, and link the SDK's CSS/JS with relative paths. index.html must sit at the root of the ZIP (see B5), not inside arpia-ux-sdk/.

Before coding, read instructions.md (design rules) and README.md (implementation) and check template.html (required DOM).

B4: Develop Your App#

If you use an AI IDE, this prompt keeps it on the rails:

# 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. Put the `collection_id` in the URL path, and use your ARPIA Personal Token as the 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**.

Best practices: keep it lightweight, use relative paths, handle errors, and test in Chrome/Firefox/Safari/Edge.

B5: Package It#

ZIP all your files with index.html at the root.

• ✅ index.html at root level
• ✅ Static assets only (no server-side code)
• ✅ Under 25 MB compressed
• ✅ .zip format only

B6: Upload It#

1. On your SPA page, click "UPLOAD VERSION"
2. Drop the ZIP, add a Version Name and Changelog
3. Click "PROCESS VERSION" and wait for extraction

Step 3: Publish & Deploy (both paths)#

For any version, use Actions:

• Publish Version — make it the live version
• Open — preview in browser
• Download — get a ZIP backup
• Delete — remove it (can't delete the live version)

To go live: find your version → Actions → Publish Version → confirm.

Step 4: Access Your App#

• Direct link: https://cloud.arpia.ai/spax/[your-app-id]/[app_version] (on the app details page)
• Workarea Apps menu: appears in your applications list
• Share / bookmark the link with authorized users

Managing Your Apps#

Update a Version#

Path A: Edit Code → make changes → Preview → (if needed) Update ARPIA Modules → Save a Version → Publish.

Path B: update local files → new ZIP → UPLOAD VERSION → name + changelog → PROCESS VERSION → publish when ready.

Roll Back#

Version history → pick the version → Actions → Publish Version → confirm. It goes live immediately.

Delete a Version#

Version management → select → Actions → Delete → confirm. (Can't delete the live version.)

Change Access#

App settings → choose Public (any ARPIA user) or Private (Workarea members) → save.

Note: MCP Collections and Workshop API attach to private SPAs only. ARPIA_ONTOLOGY.MD is generated for public apps only.

Monitor Usage#

See total opens, access timeline, active-version usage, and engagement patterns.

Integration with ARPIA#

The Knowledge Model#

Your data lives in nodes (tables). You change it through Actions (save/update/delete tools). The Knowledge Ontology Relationship controls which nodes your app can read and which Actions it can run. Private SPAs can also expose MCP Collections and a Workshop API.

Ways to Access Data#

1. ARPIA JavaScript SDK (arpia-sdk.js) — regenerated via Update ARPIA Modules
2. MCP API calls — authenticated requests to MCP endpoints
3. Knowledge Node queries
4. Actions / Workshop API

MCP API Example#

Put the collection_id in the URL path and pass your ARPIA Personal Token as the Bearer token:

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"
};

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'
        }
      }
    );
    return await response.json();
  } catch (error) {
    console.error('Error fetching resources:', error);
    throw error;
  }
}

Generate a Personal Token under "My Profile" in the ARPIA Platform. Same-domain calls inherit your ARPIA session.

Supported & Not Supported#

Supported: HTML5, CSS3 (Tailwind, Bootstrap), JavaScript (vanilla + React/Vue/Angular), client-side libraries, static assets, JSON files.

Note: Framework apps (React/Vue/Angular) must be compiled to static files before upload — ARPIA serves static assets only and runs no build step.

Not supported: server-side code (Python, PHP, Node.js, Ruby), backend APIs/databases, server-side rendering or auth, file-system operations, non-.zip archives.

Limits#

• ZIP ≤ 25 MB compressed
• index.html must be at the root
• No server-side languages
• MCP Collections / Workshop API → private SPAs only
• ARPIA_ONTOLOGY.MD → public apps only

Troubleshooting#

Upload fails — ZIP under 25 MB, index.html at root, .zip only, no server-side files.

App won't load — check the Console, use relative paths, include all dependencies, test in Preview first.

API calls fail — verify the collection_id (URL path) and Personal Token (Bearer), check endpoints, confirm nodes/Actions are attached in the Knowledge Ontology Relationship.

Codex can't see your data/tools — confirm the ontology defines the nodes/Actions; for MCP Collections/Workshop API the SPA must be private; re-run Update ARPIA Modules; use Build mode to apply changes.

Styling looks off — check relative CSS paths, confirm spa.css and arpia-font.css are linked, run Update ARPIA Modules, test other browsers.