service-delegation

name

service-delegation

description

When computing a value, status, or derived property of a domain entity (KPI, metric, alert, chart, dashboard, etc.) from outside that entity's own service module, ask the owning service instead of rebuilding the logic. Use when writing a feature that touches another domain's data, fixing a bug whose root cause is parallel implementations drifting, or reviewing code that copies SQL/query-builder patterns from another module.

Service Delegation — Single Source of Truth per Entity

Every domain entity in DDP_backend/ has one service module that owns its business logic (MetricService, KPIService, AlertService, ChartsService, etc.). When code in service A needs a value or derived property that belongs to entity B, ask B's service. Don't rebuild B's logic in A.

This prevents the bug class where parallel implementations of "what is a KPI worth right now" drift over time — a fix lands in one place but not the other, and users see the value as X on the dashboard but the alert fires on Y.

When this applies

Trigger this skill when about to:

• Write code in core/alerts/, core/reports/, core/dashboard/, etc. that computes a Metric value, KPI current value/RAG status, Chart preview, or any other entity's domain output.
• Copy a SQL builder or query-construction block from a sibling service module.
• Write a docstring that says "Mirrors X in YService" — that phrase is the giveaway.
• Import a service's pure helper (e.g. compute_rag_status) next to a locally-built query for the same entity.
• Fix a bug where two views of the same value disagree.

Skip for: cross-cutting helpers owned by no entity (timezone, logging), explicit pure-function helpers designed for reuse (compute_rag_status itself), and plain ORM attribute reads (metric.column, kpi.target_value).

The procedure

1. Find the owning service. Look in ddpui/core/<entity>/<entity>_service.py or ddpui/services/<entity>_service.py. If a <Entity>Service class exists, it owns the entity's logic.

2. Check if it already exposes what you need. Grep for compute_*, get_*, preview_*, evaluate_*. If a method returns the value, call it.

3. If it doesn't return enough, extend the service. Add a sibling method that builds on the existing one. The existing method stays unchanged; the new one exposes the richer return shape (e.g., add compute_metric_value_with_sql alongside compute_metric_value when you need the SQL string for an audit log).

4. Keep caller-specific concerns in the caller. Delegation ≠ "everything moves." Audit log shape, alert scheduling, delivery channels, template rendering — those stay in core/alerts/ because no other entity needs them. Rule: if no other domain needs the concept, it belongs in the caller; if it's "what is entity X worth," it belongs in X's service.

5. Verify imports point the right way. The caller imports the service (MetricService, KPIService). It should NOT import the service's internal building blocks (AggQueryBuilder, apply_time_grain, TIME_GRAIN_TO_SQL) for the delegated path — those are implementation details of the service.

Detection patterns to refactor on sight

Code smell	Likely root cause
AggQueryBuilder() + fetch_from(metric.table_name, ...) outside metric_service.py	Reinventing MetricService.compute_metric_value
apply_time_grain + TIME_GRAIN_TO_SQL outside kpi_service.py	Reinventing KPIService._compute_trend
Docstring says "Mirrors X"	Author knew it was duplicate
Importing a service's helper next to locally-built same-entity query	Surrounding logic also belongs in the service
Bug: "alert fires on wrong value" / "dashboard shows X but report shows Y"	Two implementations drifted

Anti-patterns

Don't copy-and-tweak when the service "doesn't quite return what I need." Extend the service instead.

Don't import-and-rebuild — using compute_rag_status while reimplementing the surrounding KPI query is a half-measure. If you're reaching for a service's helper, the surrounding logic likely belongs in that service.

Don't add an entity-domain method to the caller module — _compute_kpi_latest_value(...) in alert_query.py belongs in KPIService. The method belongs to the entity it's about.

Quick reference

Situation	Do
Computing entity X's value outside X's service	Ask XService
XService doesn't return what you need	Extend XService with a sibling method
Service returns value but you need audit SQL too	Add *_with_sql variant on the service
Operation is genuinely caller-specific (e.g. alert's standalone case)	Keep it in the caller
Pure helper (e.g. compute_rag_status) needed	Import and use; don't rebuild around it
Copy-pasting an AggQueryBuilder chain	Stop — delegate instead