Custom Apps - Developer and Runtime Guide

Purpose

This guide is for developers and platform operators who build, deploy, and integrate Custom Apps at runtime. It covers editor workflows, tag-based versioning, preview behavior, service APIs, metrics, media delivery, template rendering, and packaging endpoints.

Runtime Surface Overview

Custom Apps runtime includes the following surfaces:

1. Host-based app resolution (verified domain first, subdomain fallback)
2. Web routes for pages, auth, users, tasks, and settings
3. API routes for deployment, preview, data, services, import, and export
4. Media proxying and secure content delivery

Editor Workflow

The browser editor is available at /custom-apps/editor/:id.

Core editor capabilities include:

1. File tree navigation and selection
2. Text editing with save
3. New file and new directory creation
4. File move and delete
5. Media file viewing support
6. Split behavior for code and preview contexts

Typical Editing Flow

To edit and validate templates in the editor, follow the below-mentioned steps:

1. Open editor for the target app.
2. Select the working tag.
3. Open or create template file.
4. Edit content and save.
5. Verify preview output.
6. Repeat until ready for deployment.

Tag And Version Management

Tags represent release lines for template content.

Supported capabilities include:

1. Select current tag
2. Create new tag
3. Delete non-active tag
4. Mark tag deployment complete
5. Set active tag
6. Persist user-selected tag preference

Important behavior:

1. Deployed tags are treated as read-only in editor flows.
2. Active tag determines runtime template source.

Deploy A Tag

To deploy a tag, follow the below-mentioned steps:

1. Complete template changes on a draft tag.
2. Run deployment complete for that tag.
3. Set the tag as active (if not auto-set in flow).
4. Validate runtime content and service calls.

Rollback Pattern

To roll back to a previous release tag, follow the below-mentioned steps:

1. Choose a previously deployed tag.
2. Set it as active.
3. Confirm runtime behavior and key pages.

Preview Capabilities

Preview upload endpoints allow writing files into tag-scoped directories without replacing active runtime content.

Preview mechanics include:

1. Preview URL includes tag context.
2. Editor can refresh preview with cache-busting parameters.
3. Template and asset resolution can switch by preview tag query.

AI Assistant In Editor

AI assistant features include:

1. Chat thread history
2. Attachment upload for prompts
3. Proposal generation
4. Diff visualization
5. Apply and revert operations
6. Multi-proposal tracking

To use the AI assistant in a controlled edit loop, follow the below-mentioned steps:

1. Open target file.
2. Request scoped change.
3. Review generated diff.
4. Apply accepted proposal.
5. Save and preview.

Editor Panels

Media Panel

The media panel is account-scoped and supports:

1. Upload (drag/drop and picker)
2. Search
3. Delete
4. Inline media preview
5. Liquid snippet insertion for media embeds

Service Panel

The Service panel manages API registries per app:

1. Create/update/delete registry entries
2. Set auth mode and credentials
3. Configure custom headers
4. Insert fetch-service snippets into templates

Translations Panel

The Translations panel supports:

1. Locale add/remove
2. Key add/delete
3. Inline locale value editing
4. Persisted translation values for runtime i18n rendering

API Capabilities

API sections below are organized by runtime function; use step-driven flows where execution order matters and reference lists where behavior is declarative.

Services API

Path pattern: /api/services/:api/*segments

Supported behavior includes:

1. GET and POST passthrough to configured registry service URL
2. HTML, JSON, and CSV response handling
3. Optional template partial rendering for HTML mode
4. Error normalization for downstream failures

Registry configuration concerns include:

1. Service URL
2. Auth mode
3. Token/custom headers
4. Optional OAuth settings

Data And Metrics API

Metrics endpoints support the following actions:

1. List metrics
2. Create metric
3. Update metric

Metric updates can be broadcast over websocket channels for live consumers.

Deployment API

Deployment endpoints support the following actions:

1. Tag availability check
2. Mark tag deployment complete
3. Set active tag

Preview API

Preview upload endpoint accepts file uploads and writes them to sanitized tag-scoped paths.

Import/Export APIs

1. Structured export returns app metadata snapshot including users, services, domains, and metrics.
2. Import accepts payloads and returns normalized per-item result mapping.

App Export ZIP API

Endpoint supports ZIP export by app_id under token-auth context.

Precondition:

1. At least one deployed tag must exist.

Authentication And Session Runtime

Runtime authentication capabilities include:

1. Basic session login/logout
2. Identity-provider flow for supported providers
3. Session transfer via one-time nonce across app domains
4. User confirmation and password reset flows

To execute session transfer across app domains, follow the below-mentioned steps:

1. Authenticated caller requests transfer for target domain.
2. Runtime issues single-use nonce.
3. Target domain exchanges nonce for authenticated session.

Users And Tasks Runtime Routes

Runtime includes page and API surfaces for:

1. User listing, creation, update, delete
2. Role assignment per app registration
3. Task listing, creation, update, delete
4. Task assignee synchronization
5. Task taxonomy CRUD (type, priority, status)

Media Delivery Runtime

Media proxy endpoint secures content by account ownership checks and forwards upstream media responses.

Supported behavior includes:

1. Inline display or forced download disposition
2. Range-request forwarding for partial content
3. Header pass-through where relevant

Template Runtime Model

Template roots are tag-aware and resolved as <subdomain>.<tag> or <subdomain>.

Directory roles include:

1. layout/ for wrappers
2. partials/ for reusable fragments
3. assets/ for static files
4. locales/ for i18n resources
5. .liquid and .md content pages

Rendering includes the following stages:

1. File metadata resolution
2. Assign/context merge
3. Liquid/Markdown rendering
4. Layout wrapping

Liquid Features

Common custom Liquid capabilities include:

1. Layout control tags
2. Image/video/media embedding tags
3. Asset URL helpers
4. Translation lookup tag
5. Table-of-contents support

Packaging And Export

Two primary export surfaces exist:

1. Browser-session export from app settings UI
2. Token-auth export API by app_id

Both require deployed tags and generate ZIP archives suitable for deployment and transport workflows.

Recommended DevOps Workflow

To run the recommended DevOps workflow, follow the below-mentioned steps:

1. Create or select draft tag.
2. Implement template and integration changes in editor.
3. Validate preview and service responses.
4. Run translation and media checks.
5. Mark tag deployment complete.
6. Set active tag.
7. Validate runtime host/domain behavior.
8. Generate export ZIP for release artifact.

Troubleshooting

Editor Save Fails With Read-Only Message

1. Confirm selected tag is not deployed.
2. Switch to draft tag or create a new tag.

Services API Returns Not Found

1. Verify API registry exists for :api name.
2. Verify auth mode, token/header, and service URL.

HTML Service Rendering Fails

1. Verify expected template partial exists in app root.
2. Validate response shape used by template context.

Preview Not Reflecting Latest Content

1. Save file first.
2. Refresh preview and confirm cache-busting query changes.
3. Verify selected tag and preview tag alignment.

Export ZIP Fails

1. Confirm app exists in caller account scope.
2. Confirm at least one deployed tag exists.
3. Check for server-side packaging errors.

Auth Callback Fails

1. Verify provider is supported and configured.
2. Validate provider secret values.
3. Confirm callback route and domain mapping.