Praxis Dashboard Analytics
Overview
Use this skill to design dashboard APIs that stay native to praxis-metadata-starter instead of inventing ad hoc chart endpoints. Pair it with:
praxis-java-host-projectfor host/resource implementation.praxis-dto-annotationsfor DTO, filter,@Schema,@UISchema,@Filterable, and governance metadata.praxis-resource-entity-lookup-backendwhen chart filters useOptionSourceRegistry,RESOURCE_ENTITY,LIGHT_LOOKUP, orDISTINCT_DIMENSION.praxis-ui-product-designwhen dashboard visual quality or UX is in scope.praxis-charts-runtime-datawhen Angular must materializex-ui.chart,PraxisXUiChartContract,chartDocument,queryContext, or stats-backed chart data.praxis-charts-authoring-settingswhen dashboard chart documents are edited through@praxisui/chartsconfig editors or Settings Panel.praxis-charts-ai-validationwhen dashboard/chart semantics are exposed to AI authoring manifests, edit plans, or generated registry assets.praxis-charts-analytics-interactionsfor stats execution,queryContext, drilldown, cross-filter, point selection, and dashboard interaction contracts.praxis-charts-authoring-catalogsfor dashboard chart documents edited from governed resource, field, and target catalogs.praxis-charts-echarts-engine-boundaryfor adapter, option-builder, provider, and event-mapping safety in Angular chart rendering.praxis-charts-ai-handler-contractsfor AI chart operations, validators, handlers, and registry projections.praxis-core-resource-runtimewhen Angular chart/dashboard behavior depends on core analytics schema contracts, stats request builders, query context, capabilities, resource discovery, or metadata materialization.praxis-core-runtime-contractswhen the work touches shared core models, providers, tokens, public API, logging, or i18n.
Before changing this skill or implementing a dashboard, inspect the resolved starter/source for
StatsFieldRegistry, StatsFieldDescriptor, StatsSupportMode, stats request/response DTOs,
@UiAnalytics, UiAnalyticsOpenApiCustomizer, option-source descriptors, capabilities, export,
/schemas/filtered, /schemas/catalog, and a representative reference-host analytics resource
when available. The goal is to model what Praxis already publishes before adding custom dashboard
contracts.
Classification
Classify work before editing:
contrato-publico: adding/changing resource paths, dashboard paths, DTO fields,StatsFieldRegistry,@UiAnalytics,/schemas/filtered, option sources, capabilities, actions, surfaces, or export.arquitetural: deciding dashboard/resource boundaries, aggregate storage, query strategy, or starter extension.docs-apenas: planning or investigation only.local-pequena: private service/repository implementation with no public schema change.
For contrato-publico or arquitetural, map impacted consumers, OpenAPI, schemas, Angular runtime, security, test evidence, and breaking-change risk before patching.
Decision Rule
Prefer a Praxis read-only aggregate resource when the dashboard panel can be represented as one analytic dataset with fields, filters, dimensions, and metrics.
Use a custom dashboard endpoint only when the response composes several resources, expresses product layout, returns cross-resource KPIs, reports load status, or generates a composed executive artifact.
First inventory whether the need is already supported by resource /filter, /stats/*,
StatsFieldRegistry, @UiAnalytics, option sources, capabilities, collection export, surfaces, or
catalog/domain metadata. Classify the gap as already supported but missing in UX, supported but
poorly materialized, partial support, or a real contract gap. Only a real contract gap justifies a
new public dashboard endpoint or starter contract.
Default split:
| Need | Use |
|---|---|
| Chart drill-down over one aggregate dataset | @ApiResource + AbstractReadOnlyResourceController |
Ranking, composition, distribution, trend, or 2D heatmap (dimensions[]) |
resource /stats/* |
| Filtered table behind a chart | resource /filter |
| Chart filter options | resource option sources |
| Dashboard first fold with multiple cards | custom /api/dashboard/summary |
| UI catalog/layout for home cockpit | custom /api/dashboard/catalog |
| Cross-resource permissions | custom /api/dashboard/capabilities plus resource capabilities |
| Load freshness/status | custom /api/dashboard/loads |
| Tabular export of one dataset | resource export |
| Composed PDF with several panels | custom dashboard export |
Resource Pattern
Create aggregate read-only resources with stable paths and keys:
@ApiResource(
value = ApiPaths.Dashboard.VINCULOS_AGREGADOS,
resourceKey = "dashboard.vinculos-agregados"
)
@ApiGroup("dashboard")
public class VinculoAgregadoController extends AbstractReadOnlyResourceController<
VinculoAgregadoDTO,
String,
VinculoAgregadoFilterDTO> {
}
Do not add @RestController by reflex when the resolved starter's @ApiResource already supplies
the controller/request-mapping semantics. Keep extra stereotypes only when the target host version
or local base pattern explicitly requires them.
Expected resource operations:
POST /<resource>/filter
POST /<resource>/filter/cursor
POST /<resource>/stats/group-by
POST /<resource>/stats/timeseries
POST /<resource>/stats/distribution
POST /<resource>/stats/comparison
POST /<resource>/options/filter
GET /<resource>/options/by-ids
POST /<resource>/option-sources/{sourceKey}/options/filter
GET /<resource>/option-sources/{sourceKey}/options/by-ids
GET /<resource>/capabilities
GET /schemas/filtered?path=<path>&operation=<operation>&schemaType=<request|response>
Confirm exact paths by OpenAPI/runtime smoke for the target starter version before reporting them as verified.
For runtime /filter smoke on AbstractReadOnlyResourceController resources, send the FilterDTO itself as the JSON body and put paging/sort in the query string, for example:
POST /api/dashboard/vinculos-agregados/filter?page=0&size=10
Do not wrap the filter body as { "filter": ..., "page": ..., "size": ... }; that wrapper shape is for stats request DTOs and will fail on standard /filter endpoints.
When the host has a local base controller like the quickstart, use it to keep repeated @Operation examples for /stats/* in one place. Override concrete stats methods only when the resource needs @UiAnalytics, domain-specific summaries, or operation examples.
Stats Modeling
Override stats support deliberately:
@Override
public StatsSupportMode getGroupByStatsSupportMode() {
return StatsSupportMode.AUTO;
}
@Override
public StatsSupportMode getTimeSeriesStatsSupportMode() {
return StatsSupportMode.AUTO;
}
@Override
public StatsSupportMode getDistributionStatsSupportMode() {
return StatsSupportMode.AUTO;
}
@Override
public StatsSupportMode getComparisonStatsSupportMode() {
return StatsSupportMode.AUTO;
}
@Override
public StatsFieldRegistry getStatsFieldRegistry() {
return StatsFieldRegistry.builder()
.temporalTimeSeriesField("competencia", "competencia")
.categoricalGroupByBucket("situacao", "situacao")
.categoricalGroupByBucket("setor", "setor")
.numericDistributionField("valor", "valor")
.numericMeasureField("quantidade", "quantidade")
.numericMeasureField("valor", "valor")
.build();
}
Only register fields that are valid for the operation:
- dimensions: status, category, organization unit, month, rubrica group, frequency type, or temporal fields with
StatsDimensionExtraction(HOUR_OF_DAY,DAY_OF_WEEK,MONTH_OF_YEAR, etc.). - measures: amount, count, days, hours, percentage, average,
AVG_PER_CYCLE_OCCURRENCE, min/max when meaningful. - never register technical IDs, document numbers, codes,
ROWID, legacy locator fields, phone numbers, postal codes, or fiscal IDs as numeric measures. - treat legacy numeric codes as text/categorical dimensions unless users do arithmetic with them.
Use native requests:
{
"filter": {},
"field": "situacao",
"metric": {
"operation": "SUM",
"field": "quantidade",
"alias": "total"
},
"limit": 10,
"orderBy": "DESC"
}
For trends, use /stats/timeseries with a temporal field and DAY, WEEK, or MONTH granularity.
Support both single-metric and multi-metric requests when the frontend needs combo charts:
{
"filter": {},
"field": "competencia",
"granularity": "MONTH",
"metrics": [
{ "operation": "SUM", "field": "valorLiquido", "alias": "massaLiquida" },
{ "operation": "AVG", "field": "percentualDesconto", "alias": "mediaDesconto" }
],
"fillGaps": false
}
Validate aliases and multi-metric response shape; clients may use points[].values.<alias> for combo charts.
Analytics Metadata
Use @UiAnalytics and @AnalyticsProjection when the UI should discover chart intent instead of hardcoding it.
Model:
GROUP_BYfor ranking/composition/2D cross-tab by dimension.TIMESERIESfor trend lines and monthly evolution.DISTRIBUTIONfor histograms/terms distributions.RANKING,TREND,COMPOSITION,COMPARISON, orDISTRIBUTIONas chart intent.
Keep @UiAnalytics honest: declare projections only for operations backed by real stats support and tests.
@UiAnalytics publishes x-ui.analytics.projections on real OpenAPI operations. It is not a
dashboard manifest, not a second schema source, and not a place to invent metrics, SQL, filters, or
layout unavailable from the stats operation. Bind projection fields only to StatsFieldRegistry
fields and DTO semantics that are executable by the resource.
For chart-discoverable resources, assert that /schemas/filtered response schemas publish x-ui.analytics.projections with ids, bindings, defaults, presentation families, sort, drill-down, and granularity where applicable.
When an Angular dashboard needs an actual chart document, keep the boundary explicit:
x-ui.analytics.projectionsdescribes discoverable analytics intent and executable stats bindings.x-ui.chart/PraxisXUiChartContractdescribes a concrete chart materialization for@praxisui/charts.- a product
/api/dashboard/catalogmay choose official first-fold panels, layout, load policy, and chart documents, but it does not own the generic chart vocabulary. queryContextcarries runtime filters and cross-widget context; do not fold contextual filters into string-built stats paths or host-only field aliases.
If a projection can be materialized by AnalyticsChartConfigAdapterService, prefer that path before adding custom dashboard payloads. If the catalog publishes widget.chart, the Angular side should use the @praxisui/charts backend payload/schema mapper path rather than local ECharts options.
In praxis-metadata-starter 8.x (8.0.0-rc.24+), the first runtime resolution of grouped OpenAPI for /schemas/filtered response schemas can take extra time while the group document is initialized and cached. Use a smoke timeout of at least 60 seconds for the first analytics schema pass, then rely on cached calls for faster repeat checks.
Filters And Option Sources
Create a FilterDTO for dashboard filters instead of accepting raw maps.
Required rules:
- Use
@Filterablefor executable filters. - Use
@UISchemafor labels, controls, ranges, option endpoints, and presentation. - Use Bean Validation for date ranges, required bounds, and list sizes.
- Use option sources for chart dimensions and multiselects.
- Use
DISTINCT_DIMENSIONfor dimensions derived from the aggregate dataset. - Use
CATEGORICAL_BUCKETfor precomputed ranges or buckets such as salary ranges, percentage bands, age bands, SLA buckets, or absence ranges. - Use
LIGHT_LOOKUPfor small/catalog lookup sources. - Use
RESOURCE_ENTITYonly for real governed entities withby-ids, rich display, selection policy, and optional detail navigation. - Use
dependsOnanddependencyFilterMapwhen option values must cascade from other dashboard filters; test that the published schema contains the dependency metadata and that the runtime endpoint applies it.
Do not publish provider details, SQL, table names, internal package/procedure names, tenant context, or private bind parameters through x-ui, @UISchema.extraProperties, option source metadata, or OptionDTO.extra.
For AI-authored dashboards, do not route dashboard intent by keywords such as "ranking", "trend", or "pie" inside the host. Expose semantic resources, stats capabilities, analytics projections, catalog/domain metadata, and option-source contracts so the governed authoring flow can resolve the intent semantically and then ground it against executable stats operations.
Custom Dashboard Endpoints
Keep custom endpoints thin and compositional:
GET /api/dashboard/catalog
GET /api/dashboard/capabilities
POST /api/dashboard/summary
GET /api/dashboard/loads
POST /api/dashboard/exports/pdf
Guidelines:
catalogreturns dashboard layout, panel definitions, resource links, operation names, labels, refresh policy, and feature flags.capabilitiesconsolidates user permissions across resources and product panels.summaryreturns cross-resource KPI cards for the first viewport.loadsreturns aggregate freshness/status without stack traces or SQL.- composed PDF/export may remain custom when it crosses multiple resources.
Do not duplicate /stats/* or /filter behavior in custom dashboard endpoints unless a real product response shape requires it.
Custom dashboard endpoints may materialize product composition, first-viewport summaries, load freshness, or cross-resource capabilities, but they must link back to canonical resource paths, operation names, schema links, capabilities, and option sources. They should not hide unsupported stats or turn SQL/provider internals into public dashboard contract.
Legacy-Backed Hosts
For legacy-backed hosts:
- Resolve user, organization, permissions, tenant, and database context server-side (
resolveResourceFilterAccessScope()). - Do not accept company/user/profile/permission context in dashboard filter bodies unless the host has an explicit trusted admin use case.
- Do not query high-volume transactional legacy tables during login or dashboard first load.
- Use aggregate tables, views, materializations, or validated cockpit sources.
- Mark every indicator with source, refresh/version, period key, scope, and parity evidence.
- Keep details behind migrated resources or legacy drill-down links until individual-detail permission is proven.
Validation
Minimum validation for a dashboard resource:
- compile/test proof for DTO/controller/service changes;
- OpenAPI path exists;
/schemas/filteredfor request and response, including operation examples for stats operations when the host publishes them;/schemas/cataloghas resolvable schema links for stats operations when the host exposes the catalog;x-ui.analytics.projectionsappears for every operation annotated with@UiAnalytics;/filtersmoke with representative filters;/stats/group-by,/stats/timeseries, and/stats/distributionsmoke for every enabled stats support mode;- multi-metric stats smoke when combo charts or multiple measures are advertised;
- option-source filter and by-ids smoke for each chart lookup;
- option-source search,
includeIds, dependency filter, and by-ids order preservation when those policies are enabled; - capability behavior for allowed and denied users;
- no leaked private fields in schema, response, option metadata, or errors;
- aggregate parity check against the legacy/source dataset for at least one period.
Schema smokes can run against an isolated test context when they only assert OpenAPI,
/schemas/filtered, catalog links, x-ui.analytics, and option-source metadata. Content smokes
that expect non-empty buckets, points, or option lists require seeded fixture data or the approved
published/isolated Neon reference database.
When validation is partial, report exactly which endpoints were executed and which remain planned.
Reference
Read references/praxis-metadata-starter-8-rc24.md when you need baseline classes, methods, or endpoint families introduced in praxis-metadata-starter 8.0.0-rc.24+.
Read references/quickstart-dashboard-patterns.md when you need concrete reference-host patterns from praxis-api-quickstart, especially payroll analytics, @UiAnalytics, multi-metric stats, option-source dependencies, and smoke test shapes.
Treat references as versioned evidence, not the current source of truth. When local starter or quickstart source is available, prefer the current source/tests over older reference notes.