# Zoho Replacement Feature Map

Zoho Analytics is a reference system only and is expected to be cancelled. KPI Studio should reverse engineer useful builder/editor behavior from the captured manuals, screenshots, CSV filter notes, PDF/images, and sync artifacts, then implement those behaviors against KPI Studio's own data engine.

Zoho must not be used as a live KPI value source, a runtime dependency, or a production connector. The replacement target is KPI Studio-native metadata, queries, dashboards, permissions, and exports.

## Source Rule

| System | Role in KPI Studio |
| --- | --- |
| Zoho Analytics | Reference for UX, builder/editor behavior, chart families, formula/filter semantics, dashboard layout, menus, and permissions. Reference only. |
| KPI Studio Data Studio | Stored dataset registry and row storage for manual and pulled operational datasets. Primary builder source. |
| PrognoCIS | Live charge/appointment/encounter exports when CSV files are present. |
| Google Drive sheets | Case manager, PA, BV, DOL, and business report source material after controlled pull into KPI Studio storage. |
| Clinic Logix | Future live connector target. |

## Status Legend

| Status | Meaning | Dev action |
| --- | --- | --- |
| Implemented | Existing KPI Studio behavior is close enough for devs to build on. | Preserve behavior, add tests when modifying. |
| Partial | UI or metadata exists, but runtime behavior, persistence, or coverage is incomplete. | Complete the listed acceptance criteria before declaring parity. |
| Gap | No production-ready implementation is present. | Build KPI Studio-native behavior before Zoho cancellation if needed for replacement. |
| Deferred | Known Zoho capability or enhancement is intentionally out of the cancellation-critical path. | Do not block cancellation; keep documented for later roadmap. |

## Cancellation-Critical Checklist

These items define the replacement line before cancelling Zoho. Do not mark a row complete because the UI label exists; the control must save, reload, and drive KPI Studio data/query behavior unless the row explicitly says metadata-only.

### Implemented

| Area | Capability | KPI Studio target | Acceptance check |
| --- | --- | --- | --- |
| Builder | Chart type gallery | Report Creator in `client/src/pages/Builder.tsx` | Captured Zoho chart catalog is represented by grouped chart tiles; selecting a chart persists through tile save/edit. |
| Builder | Basic shelves | Builder graph/filter/user-filter panels | X/Y plus supported visual shelves render as pills and reload when editing an existing tile. |
| Builder | Measure aggregation menu | Builder field pill controls | Sum, average, count, distinct count, min, max, median, std dev, variance, first, last, and custom formula labels are available and persisted in tile config. |
| Builder | Date granularity labels | Builder date field controls | Actual, year, quarter, month, week, day/hour, seasonal, and fiscal variants are available as selectable metadata. |
| Filter | Captured operator labels | Builder filter cards and inline filter shelf | Text, number, and date fields expose Zoho-style operator choices; selected operators are saved in tile metadata. |
| Editor | Existing tile edit handoff | Dashboard tile edit into Report Creator | Editing a saved tile opens the Zoho-style creator with chart type, data source, measures, dimensions, filters, and aliases prefilled where possible. |
| Data source | Zoho source handling | `/api/studio/source-map` plus docs | `zoho.reference` is documented as reference-only and must not be treated as a value-producing source. |

### Partial

| Area | Capability | Current behavior | Complete when |
| --- | --- | --- | --- |
| Builder | Advanced shelves | X/Y/Color/Text/Size/Tooltip/Filter slots exist, but some are metadata-only. | Query builder and chart renderer consume every saved shelf consistently for the chart families where that shelf is valid. |
| Builder | Chart render adapters | Several visual families have preview shapes. | Each Zoho replacement chart type has a real KPI Studio data adapter or is explicitly mapped to a supported fallback with visible copy in dev notes. |
| Editor | Tile settings tabs | Captured-style tabs exist: Graph, Filters, User Filters, Reset All, Zia Suggestions; earlier parity notes also list Data, Format, Series, Threshold, Drill, Annotations, Trendline. | The final editor tab set is reconciled, duplicate/legacy labels are removed, each tab saves settings, and unsupported tabs are hidden or marked deferred. |
| Filter | Nested filter grammar | Field/operator selection exists. | AND/OR groups, nested conditions, null checks, relative date ranges, top/bottom N, and any Zoho condition caps are represented in saved metadata and evaluated server-side. |
| Filter | User filters | User-filter shelf exists. | Dashboard viewers can interact with user filters, filter state broadcasts to linked tiles, and tile-level overrides are supported. |
| Formula | Formula catalog | Captured formula JSON and browsing work were added in Data Studio according to progress notes. | The replacement exposes a searchable function browser from the captured categories and inserts functions into an editable expression field. |
| Formula | Validation | Not yet proved as runtime behavior. | Formula expressions are parsed/type-checked against KPI Studio dataset columns through a KPI Studio endpoint; validation errors appear inline and block invalid saves. |
| Dashboard | Canvas/grid | Dashboard resizing/placement exists. | Designer has stable 12-column snap/resize behavior, edit/view modes, selected handles, and persisted responsive coordinates. |
| Dashboard | Widget palette | Some dashboard/report library behavior exists. | Palette supports chart, KPI widget, filter, text, image, URL/embed, tab, and section divider widgets with save/reload coverage. |
| Dashboard | Theme shell | Captured theme controls exist. | Theme selection persists, applies to dashboard view/edit mode, and includes accessible default plus any custom KPI Studio themes chosen for replacement. |
| Dashboard | Drill and underlying data | Some drill/detail patterns exist. | Every chart/table tile menu can open underlying rows filtered by the tile query without using Zoho. |
| Menu | Tile context menu | Design reference lists expected actions. | Menu includes edit chart, change chart type, view underlying data, drill down, add filter, duplicate, export, and delete with permission-aware enable/disable states. |
| Permissions | Source-aware editing | Source map exists. | Builder, dashboard edit, export, and delete actions enforce KPI Studio roles and dataset access; Zoho credentials are never required. |

### Gaps

| Area | Gap | Why it matters before cancellation | Dev notes |
| --- | --- | --- | --- |
| Formula | Token-aware formula editor | Users need to replace Zoho calculated fields without returning to Zoho. | Add Monaco or CodeMirror-style editor, autocomplete, signatures, examples, dataset column insertion, and parse/type validation. |
| Formula | Full function compatibility decision | Captured Zoho function lists are larger than current proved runtime support. | Categorize each function as supported, alias, unsupported, or deferred; document replacement syntax for unsupported Zoho functions. |
| Filter | Server-side filter evaluator parity | Saved filter metadata is not enough if dashboards ignore it. | Add tests that text, number, date, relative date, null, range, and top/bottom operators change returned KPI rows. |
| Dashboard | Dashboard tabs | Zoho dashboards can use tabs; cancellation requires equivalent dashboard organization if current Zoho boards depend on it. | Implement tab widget or dashboard section tabs with persisted tab membership and viewer state. |
| Dashboard | Export behavior | Zoho users will expect image/PDF/CSV export paths. | Implement KPI Studio-native export from dashboard/tile data. Do not proxy through Zoho. |
| Permissions | Share/admin model | Zoho sharing cannot survive cancellation. | Define owner/editor/viewer roles, dataset restrictions, dashboard sharing, and audit trail in KPI Studio. |
| Menu | Bulk menu/action coverage | Operators need dashboard maintenance without editing raw metadata. | Add route or component coverage for duplicate, delete, export, view data, add filter, and chart-type swap. |
| Builder | Query contract documentation | Devs need a stable target when wiring shelves/filters/formulas. | Document saved tile config fields, runtime query request shape, and render response shape in source-map docs or API docs. |

### Intentionally Deferred

| Area | Deferred item | Reason |
| --- | --- | --- |
| AI insights | ANA/Zia-style natural language report assistant | Optional AI extension. Manual KPI Studio builder must work without model-backed behavior. |
| Collaboration | Real-time collaborative cursors | Useful enhancement but not required to replace Zoho dashboards before cancellation. |
| Workflow automation | Automatic Task Master task creation from threshold breach | Operational cognition layer is separate from Zoho parity; keep metadata, defer runtime automation unless separately prioritized. |
| Future connector | Clinic Logix live connector | Future source target, not required for Zoho reference cancellation. |
| Visual extras | Non-Zoho theme pack and advanced animations | Replacement can ship with stable accessible themes first. |

## Area-Specific Acceptance Notes

### Builder And Editor

- Builder controls must bind to KPI Studio datasets from `/api/studio/source-map`, not Zoho workspaces.
- A saved tile must round-trip through save, dashboard render, edit, and save again without losing chart type, shelves, aggregations, date granularities, filters, formulas, and visual settings.
- Advanced chart families may use a fallback renderer only when the dev note states the fallback and the chart still reflects real KPI Studio data.
- The tile editor should converge on one tab vocabulary. Keep captured Zoho terms where they help users migrate, but prefer KPI Studio labels when they are clearer.

### Filters

- Operators must be data-type-aware: text, number, date/time, boolean, and null/blank cases.
- User filters and hard filters must be stored separately so dashboard viewers cannot remove required business constraints.
- Relative dates must resolve in KPI Studio at query time, using the dashboard timezone/config, not the developer machine clock.
- Filter state must be visible in the tile query summary or an equivalent debug surface so devs can verify behavior before Zoho is gone.

### Formula

- Zoho formula docs are compatibility references, not runtime code.
- KPI Studio should own the grammar, validator, and evaluator. Any unsupported Zoho function needs a documented replacement or explicit deferral.
- Formula save must include expression text, referenced columns, output type, validation status, and enough metadata to re-open the editor without re-parsing from scratch.

### Dashboard

- Dashboard layout metadata must be KPI Studio-owned: widget id, type, dataset/tile binding, grid coordinates, tab/section membership, filter links, theme, and permissions.
- Dashboard filters must broadcast to linked tiles and allow tile-level opt-out where required.
- Dashboard edit mode and viewer mode must not depend on Zoho screenshots, browser sessions, or API calls.

### Menus And Permissions

- Menus should be permission-aware. Viewers can inspect/export only when policy allows; editors can edit, duplicate, add filters, and change chart type; owners/admins can delete/share.
- Exported files must be generated from KPI Studio stored data and visible dashboard state.
- Do not store or expose Zoho session cookies, browser capture credentials, or PHI in docs, logs, screenshots, or exported replacement artifacts.

## Reference Artifacts Already In Repo

| Artifact | Purpose |
| --- | --- |
| `CODEX_BRIEF_zoho_parity_2026-05-20.md` | Original parity target and source inventory. |
| `CODEX_PROGRESS_zoho_parity_2026-05-20.md` | Implementation progress and known gaps. |
| `zoho-parity-builder.png` | Builder parity screenshot. |
| `zoho-filter-operators-builder.png` | Filter operator parity screenshot. |
| `docs/design-reference/manus-kpi-studio-20260519/` | KPI Studio design reference captures for builder, dashboard canvas, filter modal, and tile context menu behavior. |

## Implementation Order

1. Keep the manual builder/data path working without AI.
2. Confirm every dashboard tile source through `/api/studio/source-map`; missing sources must be ingested or explicitly deferred before migration sign-off.
3. Complete server-side query evaluation for shelves, aggregations, filters, and formulas that already have UI controls.
4. Finish dashboard grid/tabs/widget/menu behavior needed by current Zoho dashboards.
5. Add KPI Studio-native permissions and export behavior.
6. Keep ANA, Zia-like suggestions, collaboration, and future connectors outside the cancellation-critical path unless separately assigned.