# Phoenix Knowledge Base Crosswalk

## Sources used

- [Knowledge Base root](https://jiffy-ai.atlassian.net/wiki/spaces/PHO/pages/3940057124/Knowledge+Base)
- [Phoenix Platform Documentation DRAFT](https://jiffy-ai.atlassian.net/wiki/spaces/PHO/pages/4049371158)
- [Phoenix Sprint 16 Demo — Meeting Minutes](https://jiffy-ai.atlassian.net/wiki/spaces/PHO/pages/4208197633)
- [Bundle, Service Request, email, and saved-query notes](https://jiffy-ai.atlassian.net/wiki/spaces/PHO/pages/4167335966)
- [Service Request servicing and ChangeSet design](https://jiffy-ai.atlassian.net/wiki/spaces/PHO/pages/4002709641)

The pages are not equally authoritative. The platform document is a draft; sprint minutes describe recent demonstrations; design pages describe intended product behavior. The table below reconciles them with direct production observations.

## Architectural interpretation: applications as Service Requests

The documentation should use an SR-first mental model for complex Phoenix applications. A Service Request is the durable unit of work connecting business data, task state, assignee or role, workflow actions, approvals, documents, SLA, notifications, execution history, and audit. Application screens create and service that unit of work.

This interpretation explains why a visually complete CRUD application is not equivalent to a complete Phoenix application. Generic entity operations can display and update records, but they do not by themselves provide the operational guarantees of native task assignment, state transitions, SLA/escalation, workflow execution, notification delivery, retry history, and audit evidence.

## Capability crosswalk

| Capability | Knowledge Base | Production evidence | Documentation status |
|---|---|---|---|
| AI prompt → code → preview | AI code visibility, code review, questionnaire, and live progress | Executed twice; small app and SR-like app generated | Verified |
| Versioned app lifecycle | Draft/sandbox, dependency validation, publish, instance | Draft editors and publish controls observed; app publication not executed | Observed + KB |
| Entity/schema migration | AI can build data-backed apps | AI proposed 18-field entity and required confirmation; migration executed | Verified |
| Saved-query CRUD | CSV export/upsert/API writes described | List/detail/update generated; fulfillment worked, create/approval exposed defects | Partially verified |
| Async workflow engine | Waiting, retry/backoff, switch, loops, sleep, parallel, subflows, signals | Platform workflow names visible in schedule selector; nodes not executed | KB only in this tenant |
| Node status tracking and SLA | Status tracking defaults on; SLA days and responsible role | Native task did not expose default-on status; SLA Tracking said it had no arguments | Failed/current WIP: PHX-5831, PHX-5832 |
| Notification node | Internal users via in-app and/or email; full compose UI | Missing from both current-app and platform palettes; AI could only create invalid placeholders | Failed: PHX-6025 |
| Email functional node | Explicit third-party message and attachments | No workflow node configured or sent | KB only |
| Inbound email | OAuth inbox can trigger workflows and persist attachments | Connected Inboxes, Rules, Activity observed; no mailbox linked | Observed + KB |
| Document classification/extraction | Document processing, schema, approval | End-to-end upload, classify, extract, approve succeeded | Verified |
| Document variants and bundles | Shared payload, roles/signatures, sequential/parallel e-sign | Draft variant created; bundle library blocked by publication failure | Partially verified |
| Service Request nodes | Data capture, document generation, signing, draft and node management | Native type, task states, approval, and jumps configured; notification/status unavailable | Partially verified |
| SR execution history | Per-task status | Native empty-history surface observed; no run because Test required a valid `srInstanceId` | Observed, not executed |
| Servicing ChangeSet | SR → Scope → ChangeSet → Validation → Approval → Execution → Audit | Not exposed in generated generic SR app | Design-only |
| Menu Editor | AI routes/menus and production navigation | Main menu list fails with missing query; Add dialog opens | Failed |
| Tenant isolation and roles | Multi-tenancy, sharing codes, auditability, role permission enforcement | Roles and permission groups inspected | Observed; enforcement not executed |
| PII masking | Nine backend/query-level categories; raw JSON concern noted | No masking scenario performed with real or synthetic sensitive classes | KB only |

## Workflow details to include in future documentation

The platform draft describes an asynchronous engine capable of waiting and resuming, retries with exponential backoff, branching/switch behavior, loops, sleep, parallel work, subflows, workflow calls, signals, assignments, and automation tasks.

Those capabilities should be documented at three levels:

1. **Designer:** node purpose, inputs, outputs, status tracking, SLA, and role.
2. **Runtime:** queued/running/waiting/succeeded/failed states, retry policy, signals, and execution history.
3. **Operations:** audit records, responsible user/role, error remediation, and safe replay or rollback.

The current production audit confirmed that workflows exist in a hierarchical selector, an inactive schedule can reference one, and a native Service Request approval flow can be authored. It did not execute the Service Request because the Test runner required a valid `srInstanceId` that the design surface did not provide.

## Service Request model from the design pages

The servicing design describes a controlled lifecycle:

```text
Service Request
  → Scope
  → ChangeSet
  → Validation
  → Approval
  → Execution
  → Audit
```

ChangeSets can include targets, operations, value sources, preconditions, validations, approvals, execution behavior, and before/after audit evidence. Proposed templates cover field updates, collection changes, relationship changes, parameter changes, documents/consent, and lifecycle actions.

This is materially richer than the tested generic `service_request` entity. The generated app stored status fields and ran client-side threshold logic; it did not create a ChangeSet. The later native Service Request test did create an approval chain, but no instance was executed and no ChangeSet workflow was configured.

## Notification and email model

Sprint 16 documentation makes an important product distinction:

- **Notification:** inform internal people about a platform event, via in-app and/or email channel.
- **Email:** send an explicit message, often to an external party, with content and attachments.

It also describes organization-level mailboxes, compliance outbox behavior, and BCC configuration. Documentation should state which mailbox sends a message, who can audit it, and whether the event is an internal notification or an external email.

The July 30 Sprint 16 notes are especially specific: a functional Notification node was said to be built with full compose behavior, while a separate Email node should handle explicit messages and attachments. They also say auto-mapped inputs must be visibly marked, internal wiring should be hidden, status tracking should default on, and SLA should expose only days and responsible role. Current giftcards production differs in all four areas:

- Notification is absent from both palettes: [PHX-6025](https://jiffy-ai.atlassian.net/browse/PHX-6025).
- AI generated invalid empty placeholders instead: [PHX-6024](https://jiffy-ai.atlassian.net/browse/PHX-6024).
- Status tracking remains under active implementation: [PHX-5831](https://jiffy-ai.atlassian.net/browse/PHX-5831).
- SLA exposes no arguments: [PHX-5832](https://jiffy-ai.atlassian.net/browse/PHX-5832).

## Documentation gaps revealed by testing

- Exact prerequisites and permissions for publishing a document type.
- How a published document type becomes visible in the bundle library and how long indexing should take.
- How AI selects or creates a Service-Request-tagged workflow.
- How a designer creates or selects a Service Request instance and obtains `srInstanceId` for Test.
- Whether the native Service Request AI validates its generated DSL before the first save.
- How unavailable functional actions are prevented from becoming empty Compose placeholders.
- Where delivered in-app notifications can be viewed and acknowledged.
- Notification delivery audit, retry behavior, and failure states.
- Schedule timezone, interval-to-cron conversion rules, and edit semantics.
- Test mailbox setup for inbound Gmail and safe outbound email testing.
- Which AI editor actions generate a new prompt automatically and which only navigate to a tool page.