Encore OS — Documentation

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:

GR-INTEGRATION.md — GR module integration anchor
CROSS_CORE_INTEGRATIONS.md — integration matrix
EVENT_CONTRACTS.md — event payload schemas

Integration Summary

Integration	Pattern	From → To	Status
GR-11 execution data	Data (same core, DB read)	GR-13 reads `gr_procedure_executions`	Implicit
GR-03 regulatory domains	Data (same core, DB read)	GR-13 reads `gr_regulatory_requirements`	Implicit
GR-07 QI project creation	Event (`fw_domain_events`) → Edge Function	GR-13 → GR-07 (via `gr-procedure-gap-consumer`)	✅ Complete (GR-13-EN-01, 2026-04-19)
PF-12 report export	Platform Layer	GR-13 → `@/platform/reports`	📝 Planned
PF-10 notifications	Platform Layer	GR-13 → `@/platform/notifications`	📝 Planned
PF-30 permissions	Platform Layer	GR-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

Layer	Import Path	Usage
PF-10 Notifications	`@/platform/notifications`	Overdue count alert when threshold exceeded
PF-12 Reports	`@/platform/reports`	Procedure compliance effectiveness PDF/CSV export
PF-30 Permissions	`useHasPermission` from `@/platform/permissions`	Guards analytics dashboard and export actions
PF-01 Organizations	`useCurrentUser` from `@/platform/auth`	Provides `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)

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Procedure Analytics & Compliance Effectiveness — Integration Contracts

Overview

Integration Summary

Events Published by GR-13

`procedure_gap_identified`

Events Consumed by GR-13

API Contracts

SECURITY DEFINER Wrapper Function (Internal)

Edge Function (Internal Cron)

Platform Integration Layers Used

GR-07 Integration Detail

Tenant Isolation

Contract Validation Checklist

​Overview

​Integration Summary

​Events Published by GR-13

​procedure_gap_identified

​Events Consumed by GR-13

​API Contracts

​SECURITY DEFINER Wrapper Function (Internal)

​Edge Function (Internal Cron)

​Platform Integration Layers Used

​GR-07 Integration Detail

​Tenant Isolation

​Contract Validation Checklist

Overview

Integration Summary

Events Published by GR-13

`procedure_gap_identified`

Events Consumed by GR-13

API Contracts

SECURITY DEFINER Wrapper Function (Internal)

Edge Function (Internal Cron)

Platform Integration Layers Used

GR-07 Integration Detail

Tenant Isolation

Contract Validation Checklist