Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Feature ID: GR-13
Feature Status: ✅ Complete | Downstream Integrations: 📝 Planned Last Updated: 2026-03-07
Owning Core: GR (Governance & Compliance)
Constitution Reference: §1 Architecture — no direct core-to-core imports; cross-core via Platform Integration Layer and events.

​
Overview

GR-13 provides read-only procedure execution analytics layered on top of GR-11 (Procedures Management) data. It integrates downstream with GR-07 (Quality Improvement) for gap export and PF-12 (Reporting) for accreditation report generation. Architectural pattern: GR-13 is analytics-only (reads data within the GR core boundary, emits a single event for GR-07). It does not own any business entity tables; it creates one materialized view and one SECURITY DEFINER wrapper function. Related documents:

​
Integration Summary

IntegrationPatternFrom → ToStatus
GR-11 execution dataData (same core, DB read)GR-13 reads gr_procedure_executionsImplicit
GR-03 regulatory domainsData (same core, DB read)GR-13 reads gr_regulatory_requirementsImplicit
GR-07 QI project creationEvent (fw_domain_events) → Edge FunctionGR-13 → GR-07 (via gr-procedure-gap-consumer)✅ Complete (GR-13-EN-01, 2026-04-19)
PF-12 report exportPlatform LayerGR-13 → @/platform/reports📝 Planned
PF-10 notificationsPlatform LayerGR-13 → @/platform/notifications📝 Planned
PF-30 permissionsPlatform LayerGR-13 checks gr.procedure-analytics.*📝 Planned

​
Events Published by GR-13

​
procedure_gap_identified

  • Channel: gr_events
  • Publisher: GR-13 (triggered when user clicks “Export to QI” in the analytics dashboard)
  • Subscribers: GR-07 (create QI project candidate) — consumer shipped in GR-13-EN-01 (2026-04-19)
  • Purpose: Notifies GR-07 that a procedure execution gap was identified and a QI project should be created.
  • Status: ✅ Complete (publisher + consumer)
Payload Schema: 
{
  organization_id: string;       // UUID — required for tenant routing
  procedure_id: string;          // UUID — GR-11 procedure
  procedure_title: string;       // Human-readable name
  category: string;              // Procedure category (from gr_procedures.category)
  completion_rate_pct: number;   // 0.0–100.0 — computed from materialized view
  overdue_count: number;         // Count of overdue executions
  exported_by: string;           // UUID — auth.uid() of acting user
  exported_at: string;           // ISO 8601 timestamp
}
Security note: Payload contains no PHI/PII. Payload is procedural data only (organizational records, not patient records).

​
Events Consumed by GR-13

None. GR-13 is analytics-only and does not consume events from other cores.

​
API Contracts

​
SECURITY DEFINER Wrapper Function (Internal)

Function: gr_get_procedure_execution_summary(p_org_id UUID)
Pattern: Direct DB RPC (not HTTP API)
Auth: SECURITY DEFINER — validates pf_has_org_access(p_org_id, auth.uid())
Returns: SETOF gr_procedure_execution_summary
Consumers: GR-13 frontend hooks via Supabase rpc() 
// Usage in hook
const { data } = await supabase.rpc('gr_get_procedure_execution_summary', {
  p_org_id: orgId
});

​
Edge Function (Internal Cron)

Function: gr-refresh-procedure-analytics
Pattern: HTTP POST — internal cron via pg_cron
Auth: Service role key (internal only; verify_jwt=false)
Schedule: 0 2 * * * (2 AM UTC daily)
Purpose: REFRESH MATERIALIZED VIEW CONCURRENTLY gr_procedure_execution_summary
Security: This function MUST NOT be exposed to public callers. The verify_jwt=false setting is intentional for cron invocation; the service role key is required in the Authorization header.

​
Platform Integration Layers Used

LayerImport PathUsage
PF-10 Notifications@/platform/notificationsOverdue count alert when threshold exceeded
PF-12 Reports@/platform/reportsProcedure compliance effectiveness PDF/CSV export
PF-30 PermissionsuseHasPermission from @/platform/permissionsGuards analytics dashboard and export actions
PF-01 OrganizationsuseCurrentUser from @/platform/authProvides organization_id for all queries

​
GR-07 Integration Detail

The “Export to QI” action in the GR-13 analytics dashboard triggers an interaction with GR-07 (Quality Improvement). Per architecture rules, GR-13 does not import GR-07 directly; it uses @/platform/workflow to launch the GR-07 new-project creation sheet. Pre-fill contract (GR-13 → GR-07 new project sheet): 
interface GR07QIProjectPreFill {
  name: string;              // "Improve: [procedure title]"
  category: string;          // Procedure category
  description: string;       // Auto-generated gap description with execution rate + overdue count
  priority: 'high' | 'medium' | 'low';  // 'high' if overdue > 0; 'medium' if rate < 60%; 'low' otherwise
  source_procedure_id: string; // UUID — traceability back to GR-11 procedure
}
Cross-core field note: source_procedure_id must be confirmed with GR-07 spec as a supported pre-fill field. If GR-07 does not yet accept source_procedure_id, this field is stored only in the procedure_gap_identified event payload and not in the GR-07 project record until GR-07 adds the field. Pending contract: See docs/architecture/integrations/PENDING_CONTRACTS.md — add row for GR-13 ↔ GR-07 source_procedure_id field when GR-07 spec is updated.

​
Tenant Isolation

  • All analytics queries routed through gr_get_procedure_execution_summary(p_org_id) SECURITY DEFINER function.
  • SECURITY DEFINER function calls pf_has_org_access(p_org_id, auth.uid()) before returning rows.
  • No direct client access to gr_procedure_execution_summary materialized view via PostgREST.
  • Organization ID is always sourced from useCurrentUser() in frontend hooks — never user-supplied.

​
Contract Validation Checklist

Per docs/architecture/integrations/CONTRACT_VALIDATION_CHECKLIST.md:
  • Integration patterns documented (Platform Layer, Event)
  • Event payload schema defined (no PHI confirmed)
  • SECURITY DEFINER function signature documented
  • Tenant isolation mechanism described
  • Edge function auth strategy documented (verify_jwt=false for cron; service role required)
  • GR-07 source_procedure_id field confirmed (pending GR-07 spec update — see PENDING_CONTRACTS.md)
  • PF-12 report template ID gr_procedure_compliance_effectiveness registered (pending Phase 3)