Developer Tutorial
How IHF works from a developer perspective — widget lifecycle, governance flow, outcome loop.
1 Hubs and Widgets
A Hub is a bounded domain of responsibility (e.g. Dev Hub, Ops Hub, Fin Hub). Hubs own Widgets — the smallest semantically governable interaction unit. Each widget has a widget_id (stable UUID), a widget_type (from the registry), and a version history.
The envelope injects data-widget-id and data-view-context attributes, enabling client-side event capture without coupling to implementation.
2 Interaction Events
When a user or agent interacts with a widget, an InteractionEvent is recorded — clicked, viewed, submitted, dismissed, etc. Events are append-only: a PostgreSQL trigger prevents UPDATE and DELETE on the interaction_events table.
POST /api/v2/interaction-events
Events flow into Annotations (human/agent commentary with category) and eventually surface as RequirementCandidates.
3 Governance Flow
RequirementCandidates go through a triage lifecycle: open → triaged → reviewed → promoted or dismissed. Phase 5 agents can draft Requirements from widget clusters using the Anthropic API. Promoted candidates become Requirements, which are linked to DecisionRecords.
4 Deployment and Outcomes
A DecisionRecord links to a DeploymentRecord. After deployment, OutcomeSignals are recorded (also append-only) and evaluated via ChangeEvaluations. Outcome feedback flows back to the DecisionRecord, closing the governance loop.
5 Continuous Learning (Phase 12)
Phase 12 layers a learning engine on top of the governance loop:
- OutcomeCorrelations — compute correlation scores between widget patterns and outcomes
- PatternPerformanceRecords — rank widget patterns by observed outcome quality
- AdaptiveThresholdConfigs — auto-calibrate friction and triage thresholds per hub
- InstitutionalKnowledgeBase — GIN full-text search over all governance decisions
- LearningInsights — actionable recommendations surfaced in the Learning Dashboard
6 Hub Federation
Multiple hubs interact via routing rules, stewardship roles, and federated policy overlays. Cross-hub propagation patterns are detected automatically. The GAAF compliance layer enforces type registry discipline and contract stability across hub boundaries.