# Source Map For Devs

Use the live endpoint first:

`GET /api/studio/source-map`

This endpoint is the canonical application-readable map of what is connected, what is missing, and which datasets feed which KPI surfaces. This document is the human handoff for developers replacing Zoho Analytics behavior with KPI Studio-native sources.

Zoho is reference-only. Do not add code that reads Zoho as a production value source, requires an active Zoho session, or treats captured Zoho files as current operational truth.

## Source State Rules

| State | Meaning | Allowed for builder/dashboard values? |
| --- | --- | --- |
| `ready` | KPI Studio has a controlled local/stored dataset available. | Yes. |
| `missing` | Expected source is not stored locally yet. | No. Build ingestion or show missing-source state first. |
| `reference` | Source exists only to document behavior or migration semantics. | No for KPI values. Yes for dev reference docs/UI parity. |
| `future` | Future connector or integration target. | No. Keep behind roadmap/future-copy. |

## Current Expected Entries

| Source ID | Meaning | Expected state today | Dev usage |
| --- | --- | --- | --- |
| `prognocis.charges` | PrognoCIS charge CSV pull, with calculated `service_category`. | `missing` until CSV export lands locally. | Revenue, AR, charges, payer, location, provider, and service-category dashboards once ingested. |
| `prognocis.appointments` | PrognoCIS current/future appointment CSV pull. | `missing` until CSV export lands locally. | Schedule, no-show, cancel, provider utilization, appointment status, and upcoming visit dashboards once ingested. |
| `case-manager.day1` | Case manager Day 1 workflow audit. | `ready` | Day 1 workflow, intake, missing step, and case-manager operational tiles. |
| `case-manager.bv` | Benefit verification audit derived from Day 1 workflow. | `ready` | BV aging, incomplete verification, payer/workqueue tiles. |
| `case-manager.pa` | Prior authorization aging audit. | `ready` | PA aging, pending authorization, blocked care-plan, and follow-up tiles. |
| `case-manager.starts` | Care plan starts and start reconciliation. | `ready` | Starts, start conversion, missing start reconciliation, and care-plan launch dashboards. |
| `case-manager.dol` | DOL pending / ROF follow-up audit. | `ready` | DOL pending, ROF follow-up, aging, and owner queue dashboards. |
| `marketing.sheet` | Marketing/referral sheet. | `missing` until canonical sheet/export is stored. | Referral and marketing dashboards only after controlled import. |
| `zoho.reference` | Zoho replacement reference artifacts: manuals, screenshots, captures, formula/filter notes, and parity progress. | `reference` | Use only to copy behavior into KPI Studio-native UI/query semantics. Never bind KPI values to it. |
| `drive.source-report-cache` | Drive report cache for source-report lookup. | `missing` unless local cache exists. | Lookup/reference support only after cache is materialized locally. |
| `clinic-logix.future` | Future Clinic Logix connector. | `future` | Do not build cancellation-critical dashboards against this source. |

## Mapping Rule

Before adding or changing a dashboard tile:

1. Identify the data source in `/api/studio/source-map`.
2. Confirm `state` is `ready` for production values.
3. Use the listed `datasetIds` for Builder and dashboard bindings.
4. If the source is `missing`, update the source map or ingestion path first and render an honest missing-source state.
5. If the source is `reference`, use it only for UX/behavior semantics, not values.
6. If the source is `future`, keep it out of cancellation-critical work.

## Replacement Mapping By Area

| Area | Zoho reference input | KPI Studio source of truth | Developer action |
| --- | --- | --- | --- |
| Builder chart catalog | Captured Zoho chart names/families and docs | KPI Studio chart metadata and render adapters | Keep the chart menu familiar, but bind selected chart type to KPI Studio tile config and render from KPI Studio query results. |
| Builder shelves | Zoho X/Y/Color/Text/Size/Tooltip/Filter shelf behavior | Saved KPI Studio tile config plus dataset schema | Validate shelf choices against the selected KPI Studio dataset; unsupported shelves must not silently save dead metadata. |
| Aggregations | Zoho aggregation menu labels | KPI Studio query engine | Map each label to a server-side aggregate. If an aggregate is not supported, hide it or mark it deferred in the feature map. |
| Date granularities | Zoho date grouping labels | KPI Studio query engine/timezone config | Resolve date buckets in KPI Studio, including fiscal variants only after fiscal calendar config exists. |
| Filters | Captured Zoho operator lists | KPI Studio filter grammar and evaluator | Store required filters separately from user filters and evaluate them server-side for dashboards/exports. |
| Formulas | Zoho formula function catalog | KPI Studio formula grammar, validator, evaluator | Classify function compatibility, validate expressions against dataset schemas, and save expression metadata with tile/source config. |
| Dashboard layout | Zoho dashboard designer screenshots/docs | KPI Studio dashboard layout metadata | Persist grid coordinates, tabs/sections, widget types, theme, and filter link metadata in KPI Studio. |
| Tile menus | KPI Studio design reference plus Zoho behavior | KPI Studio routes/actions | Implement edit, chart-type swap, underlying data, drilldown, add filter, duplicate, export, and delete with role checks. |
| Permissions/share | Zoho role behavior as a reference | KPI Studio auth and sharing model | Enforce owner/editor/viewer/admin actions without Zoho accounts or credentials. |

## Dev Readiness Checklist

Use this checklist before marking a migrated dashboard or builder feature complete.

| Check | Required result |
| --- | --- |
| Source state | Every value-producing tile uses a `ready` source. |
| Dataset binding | Saved tile config stores dataset id/source id, not a Zoho workspace/report id. |
| Query path | Shelves, aggregations, filters, formulas, and drilldowns execute through KPI Studio query/runtime code. |
| Edit round trip | Tile can be saved, rendered, edited, and saved again without losing source/query metadata. |
| Missing source handling | Missing PrognoCIS/marketing/cache data shows a missing-source state instead of stale Zoho values. |
| Permissions | Menu actions are disabled or blocked according to KPI Studio role/dataset access. |
| Export | Export uses KPI Studio stored data and current dashboard filter state. |
| Reference hygiene | Docs and code do not expose PHI, credentials, Zoho cookies, or active Zoho API/session assumptions. |

## Known Source-Map Gaps To Close

| Gap | Owner action |
| --- | --- |
| Query contract for saved tile metadata | Document or type the request/response shape that consumes shelves, filters, formulas, and chart settings. |
| Missing source UX | Standardize the empty/error state for `missing` sources so dashboards do not look complete with absent data. |
| Formula function support map | Add a machine-readable list of supported/aliased/deferred Zoho reference functions. |
| Dashboard permissions matrix | Define owner/editor/viewer/admin capabilities for edit, duplicate, export, share, delete, and underlying-data access. |
| Export source audit | Ensure every export path logs or displays the KPI Studio source id and filter state used to generate the file. |