Building enterprise applications on Phoenix
Phoenix is Jiffy.ai's platform for building and running enterprise web and mobile applications. It pairs an AI-assisted builder with a full set of platform services: service requests, an asynchronous workflow engine, document processing, schedules, email, companions, and tenant administration.
How this guide reads
Each section covers one platform capability. To keep the material concrete, a single worked example runs through the whole guide: a gift-card request application, built and tested in a production workspace on 4–5 August 2026. The gift-card app is not the point — it is simply a path through the platform that touches many capabilities in a realistic order.
Wherever the guide makes a claim about behavior, it carries an evidence label:
The action was completed in production and its result verified.
The UI and its controls were inspected without performing a persistent action.
An app showed a local UI effect — not a platform notification, email, or workflow.
Described in official Phoenix documentation but not executed in the tested tenant.
Specified in product design pages; implementation status varies by tenant.
Platform at a glance
The platform surface, in the order this guide covers it. Every area below exists in the production workspace or the official documentation; the badge shows how far the audit exercised it.
| Area | What it provides | Evidence |
|---|---|---|
| Workspace | App creation, search, versions, Live status, settings | Executed |
| Starter apps | Installable catalog: onboarding, advisor, servicing, and more | Observed |
| Launched apps | Deployed apps by version, environment, URL, status | Observed |
| AI app builder | Prompt → questionnaire → generated screens, tests, self-repair | Executed |
| App editor | Use cases, screens, workflows, servicing, entities, ETL, integrations, automations, reconciliations, AI agents | Executed |
| Changesets | Isolated streams of AI work with switching | Observed |
| Entities & queries | Confirmed schema migrations, saved-query CRUD, seeded data | Executed |
| App-scoped files | Attachment storage in Jiffy Drive per application | Executed |
| PII masking | Nine backend and query-level masking categories | KB |
| Service requests | Types, task states, role approvals, execution history | Executed |
| Servicing ChangeSets | Scoped, validated, approved, audited change execution | Design |
| Workflow engine | Async wait/resume, retries, branching, loops, parallel, subflows, signals | KB |
| Document processing | AI classification, extraction, approval, re-training | Executed |
| Types, variants, bundles | Versioned document artifacts, shared payloads, e-sign roles | Executed |
| Schedules | Hourly to cron triggers for any application workflow | Executed |
| Inbound email | Connected inboxes, rules, workflow routing, activity | Observed |
| Notifications & email nodes | Internal in-app/email notifications; explicit external email | KB |
| Companions | Assistants defined by function, skills, and test runs | Observed |
| Access control | Per-app roles, permission groups, tenant roles | Observed |
| Branding | Tenant themes, colors, typography, live preview | Observed |
| Menu editor | Navigation menus with types, items, preview | Observed |
| Environments | Tenant environments and partner preferences | Observed |
| Partner ecosystem | Installable partner apps, categories, authenticators | Observed |
| Automated testing | Starter-wide suite plus tagged per-page tests | Executed |
The application model
An enterprise application is more than pages and CRUD operations. It receives a request, progresses it through controlled states, assigns responsibility, performs work, records decisions, handles exceptions, and preserves an auditable outcome. Phoenix treats each of these concerns as a platform capability, organized around the Service Request:
The worked example configured five task states with a role-based approval. The same lifecycle applies to most request-driven applications:
A visually complete CRUD application can display and update records, but it does not by itself provide native task assignment, SLA, notification delivery, or audit history. For complex or stateful applications, define the service request first and treat screens as the experience around it.
Workspace and application lifecycle Executed
My Workspace is the home surface: it lists subscribed and in-progress applications with search, grid and list views, version and Live status, application settings, and a Create App action. New applications are Web or Mobile, and can be built step by step or with AI assistance.
Starter apps
The Apps area is a catalog of installable starter applications — among them Account Onboarding, Advisor Workstation, Servicing, Wealth Domain, Staffing Viewer, News Aggregator, Pershing BNY, Schwab, Companion, and Media Schema — with search, views, version information, and an install/publish action. Observed
Launched apps
Launched Apps tracks deployed applications in a searchable, paginated table: application name, version, environment, application URL, and status, with expandable rows. Observed
Versioned lifecycle
The knowledge base describes a versioned application lifecycle — draft and sandbox editing, dependency validation, publication, and running instances. Draft editors and publish controls were visible in production; full app publication was not executed during the audit. KB Observed
Building with AI Executed
The AI builder turns a short description into working React screens with a live preview. It asks clarification questions, generates code, repairs its own implementation issues, registers routes and navigation, and runs automated tests.
The typical sequence:
- Describe the application. Create an app, choose Web or Mobile, and describe the problem in plain language. Keep the first request to one or two pages.
- Answer clarification questions. Before generating, the builder asks about behavior, layout, users, and data source. Hardcoded sample data is much faster than creating an entity.
- Review generation. The chat streams reasoning, files being created, type checks, and self-corrections.
- Run the built-in tests. Every app carries a test suite; app-specific tags indicate coverage of the generated pages.
- Refine through chat. Follow-up prompts add pages, routes, and navigation without disturbing existing pages.
- Open the live app. App tools → Open app launches the running application on its own routes.
Worked example — gift cards Executed
From the prompt “Build a simple one-page web app that shows four gift card products, a category filter, and a Buy button on each card”, the first generation completed in 280 seconds over 35 steps, repairing several of its own issues along the way. A follow-up prompt added a second page with sidebar navigation in 133 seconds, leaving the first page unchanged.
The app editor
Every AI-created application also has a full internal editor. Its areas cover considerably more than the generated screens:
Workflows can be added with a name, an optional Workflow Lite mode, and a description; custom functional nodes can be defined with a name, icon, color, category, and description before configuration.
Editor tooling
The toolbar carries the changeset manager, model selection, a pinning control, publish, and the editor menu. Chat supports history with search, attachments, and floating or docked positions. App tools add operational helpers: refetch tenant data, open app, sync starter, component showcase, test results, error boundary, logs, review recent work, review full app, and a read-only Code & changes explorer grouped by AI request.
Changesets isolate streams of work: a Main changeset plus additional changesets that can be created, switched, and configured. Model selection in the tested tenant offered Claude Sonnet 5 (default), Claude Opus 4.8, Claude Opus 4.6, and Gemini 3.5 Flash. Observed
Entities and data Executed
When an application needs persistent data, the builder proposes an entity schema and pauses for confirmation before applying it. This gate matters: screens can be drafted freely, but an entity change is a persistent backend migration and should be reviewed like one.
Saved queries drive the data interactions — list, detail, insert, and update operations generated alongside the screens. The knowledge base additionally describes CSV export, upsert, and API-based writes over saved queries. KB
Files upload to app-scoped storage in Jiffy Drive, keeping attachments inside the application boundary.
Worked example — gift cards Executed
For the request-tracking variant of the app, the builder proposed an 18-field service_request entity and waited for confirmation before migrating. It then generated four saved queries (list, detail, insert, status update), seeded twelve synthetic records, and handled a PDF attachment upload to app-scoped Jiffy Drive.
Several generated interactions — request creation, approval, rejection, search, and filtering — failed in manual testing even though the automated suite was almost entirely green. The defects are tracked in the defect register.
Data protection
The platform documentation describes multi-tenant isolation with role-based permission enforcement, sharing codes, and auditability; roles and permission groups were inspected in production. It also describes PII masking across nine backend and query-level categories. No masking scenario was executed during the audit. KB Observed
Service requests and servicing Executed
The native service request designer, in the app editor's Servicing area, is where the operational backbone is configured. A service request type is created against an entity; the canvas then exposes settings, execution history, a test runner, and task states.
Approval nodes take a responsible role and branch on the decision through jump conditions. Execution history records per-task status once instances run. The knowledge base also describes service request nodes for data capture, document generation, and signing. KB
Worked example — gift cards Executed
A native type, QA Gift Card Service Request, was created with five task states. The saved flow runs Start → Approval (Tenant Admin) with mutually exclusive approved/rejected jumps → Return. No instance was executed, because the test runner requires an existing request instance id.
Servicing ChangeSets
The servicing design pages specify a richer controlled lifecycle for changes made while servicing a request:
Service Request → Scope → ChangeSet → Validation → Approval → Execution → Audit
A ChangeSet carries targets, operations, value sources, preconditions, validations, approvals, execution behavior, and before/after audit evidence, with proposed templates for field updates, collection changes, relationship changes, parameter changes, documents and consent, and lifecycle actions. This was not exposed in the tested generic app. Design
Current limitations
Worth knowing before designing around them: the notification node was absent from the node palettes (PHX-6025), SLA tracking exposed no configurable arguments (PHX-5832), and AI-generated flows should be checked so that every task resolves to a real catalog node — empty placeholder steps fail at runtime (PHX-6024).
Workflow engine Knowledge base
Behind service requests, schedules, and email rules sits an asynchronous workflow engine. The platform documentation describes:
- Waiting and resuming — long-running workflows that pause on external events and continue later.
- Retries with exponential backoff — automatic re-execution of failed nodes.
- Branching and switch behavior — conditional paths over node results.
- Loops, sleep, and parallel execution — iteration, timed pauses, and concurrent branches.
- Subflows, workflow calls, and signals — composition and cross-workflow communication.
- Assignments and automation tasks — human and automated steps in one flow.
In the tested tenant, platform workflows (for example Document Extraction and PDF Write) were visible in the hierarchical schedule selector, and an inactive schedule was saved against one; workflow nodes themselves were not executed. Observed
Workflow behavior is best documented at three levels: the designer (node purpose, inputs, outputs, status tracking, SLA, role), the runtime (queued, running, waiting, succeeded, failed, retry policy, signals, execution history), and operations (audit records, responsible role, error remediation, safe replay).
Document processing Executed
Phoenix separates document handling into four artifacts:
| Artifact | Purpose |
|---|---|
| Document | An uploaded file and its processing lifecycle. |
| Document type | An AI-classified schema shared by similar documents. |
| Variant | A versioned layout and processing definition for a type. |
| Bundle | Ordered type/variant items filled from a shared payload. |
Upload offers two processing modes in the tested tenant: Extraction (classify, create fields, extract values) and Fill (use a document as a fillable output template). With Extraction, AI classifies the document, proposes an editable schema in field groups, extracts values, and presents them for verification and approval. An approved document exposes Re-train, so classification and schema can be revised deliberately with new training input.
Publishing, variants, and bundles
Approval completes the training lifecycle; publishing a document type creates the versioned artifact (with a version number and URL prefix) that other platform pieces can depend on. The bundle editor draws its library only from published types and variants. A bundle is an ordered collection filled from one payload; signer roles and signature positions are inherited from the selected variants, and the knowledge base describes sequential and parallel e-signing. KB
Approved document → draft type & variant → publish → library item → bundle → publish → workflow / service request
Worked example — gift cards Executed
A synthetic gift-card request PDF was uploaded, classified as a new document type, and given a four-group schema. Extraction took about 2.5 minutes; values were verified field by field and the document approved, producing a draft variant. Publication failed with an HTTP 500 (PHX-5959), which blocked bundle construction downstream — a concrete illustration of the dependency chain above.
Schedules Executed
Schedules run application workflows on a timer: hourly, daily, weekly, monthly, or a cron expression. The workflow selector is hierarchical (application, then workflow), and advanced options include a group id and skipping upcoming executions. Saved schedules show type, cron, user, workflow, next run, and active state, with edit and delete actions.
Worked example — gift cards Executed
An inactive schedule was saved against the platform Document Extraction workflow. Two defects surfaced: a 24-hour interval persisted as 23 hours, and editing did not restore the workflow relationship fields — the schedule was left inactive for that reason. Schedule search not filtering is PHX-6021.
Email and notifications Observed Knowledge base
Inbound email
Email subscriptions connect an inbox (Gmail in the tested tenant) and route incoming mail into the platform. Rules carry a name, enabled switch, handler type, target workflow, a run-as user, and advanced JSON filters; a Recent Activity view shows email events once an inbox and rules are configured. In the tested tenant the handler type offered Workflow only, while the page guidance also mentions webhooks (PHX-6022).
Outbound: notification versus email
The platform documentation draws a deliberate distinction:
| Mechanism | Meaning |
|---|---|
| Toast | Transient feedback inside the current app session. |
| In-app notification | A platform-managed message on an internal user's notification surface. |
| Notification node | Workflow action informing internal people, by in-app and/or email channel. |
| Email node | An explicit message, often external, with its own body and attachments. |
| Reminder | A workflow- or SLA-driven notification. |
It also describes organization-level mailboxes, compliance outbox behavior, and BCC configuration — so documentation can state which mailbox sends a message and who can audit it. KB
Worked example — gift cards Simulated
The generated app had no notification backend hook; its success and reminder messages were local UI effects, prefixed “(Simulated)” after repair. In the native editor, the notification node was absent from both node palettes (PHX-6025), so composition and delivery could not be tested. Never claim a user was notified without a platform delivery record.
Companions and AI agents Observed
Companions are assistants defined at the workspace level. The Add Companion flow has three stages: Function (role, name, function and purpose), Skills (select or add skills), and Test. The area supports search and grid or list views.
Inside each application, the editor also has an AI Agents area alongside screens and workflows, and application settings include a Chat Agent toggle (present but marked coming soon in the tested tenant).
Administration Observed
Access control
Each application has roles — App Admin, App Designer, App User, Guest, Platform, Tenant Admin — and permission groups, with search, active switches, and row-level actions. Application settings also cover the app profile (name, description, version, status), preferences, and deletion.
Branding
Branding is tenant-wide: logo and favicon upload, multiple themes with full color control (primary through danger plus grayscale), typography, an inverted-sidebar option, and a live preview. Built-in themes can be duplicated and edited.
Navigation, environments, and partners
The Menu Editor manages navigation menus — menu types, items, and a visibility preview. (Its list view failed to load during the audit while the Add dialog still opened.) Tenant settings add environments (a develop environment in the tested tenant) and partner preferences.
The partner ecosystem covers installable partner apps and APIs — Data Manager, App Manager, and Jiffy Drive APIs were installed — organized into categories (Single Sign On, Custodian, Email Delivery, Portfolio Management) with authenticators for SSO (a SAML assertion generator in this tenant).
Team management and in-product tutorials are present in the navigation and marked coming soon.
Testing and quality Executed
Every generated application carries an automated test suite covering the app starter and each generated page, runnable from the editor. Page-specific tags are the clearest indicator of generated-page coverage.
Worked example — gift cards Executed
The two-page app finished with 1,375 tests passing, including nine tagged for the gift-cards page and four for the second page. The data-backed variant passed 1,396 of 1,397 — while request creation, approval, rejection, search, and filtering still failed in manual testing.
The practical rule: a green suite is necessary, not sufficient. Manually exercise the flows that matter — creation, approval, search — before treating a build as done.
Sources
This guide is built from a documentation source pack recorded during production capability testing of the Gift Cards workspace, 4–5 August 2026, reconciled with the official Phoenix knowledge base. The pack separates what was executed from what was observed, simulated, or known only from documentation.