inter-hub/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

inter-hub is the reference implementation of the Interaction Hub Framework (IHF) — a governed, observable interaction substrate for hub-based AI-enabled software systems. It treats every UI element as a governed artifact, creating a full traceability chain from rendered widget → user interaction → structured feedback → requirement candidate → decision record → implementation change → observed outcome.

Current state: Phases 1–12 complete. IHF v0.2 specification fully implemented. GAAF scorecard at 3.68 (Strong). The full learning loop is closed: Widget → Annotation → RequirementCandidate → Requirement → DecisionRecord → DeploymentRecord → OutcomeSignal → OutcomeCorrelation / PatternPerformanceRecord / InstitutionalKnowledgeEntry → AdaptiveThresholdConfig → improved routing and triage.

For situational context, read SCOPE.md. For architecture depth, read specs/InteractionHubFrameworkSpecification_v0.1.md.

Stack

• IHP (Integrated Haskell Platform) v1.5 — full-stack Haskell web framework, server-rendered + optional realtime
• Haskell (GHC 9.10) — strongly typed, functional
• PostgreSQL — canonical datastore, managed via Nix (no manual DB setup)
• Nix / devenv — reproducible environment
• Tailwind CSS — see specs/TailwindForInteractionHubs_v0.2.md for IHF-specific conventions

Development Setup

Requires Determinate Nix + direnv:

# One-time environment setup
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh
nix profile install nixpkgs#ihp-new
nix profile add nixpkgs#direnv

# Bootstrap IHP project (Phase 1, Task T01)
ihp-new inter-hub
cd inter-hub
devenv up

After devenv up:

• App server: http://localhost:8000
• IHP IDE + Schema Designer: http://localhost:8001

Key Commands

devenv up          # Start dev environment (app + postgres + file watchers)
migrate            # Run pending migrations
test               # Run tests (auto-creates temp Postgres DB)
make static/prod.js static/prod.css   # Production asset bundle
deploy-to-nixos production            # NixOS deploy

Schema editing: use the IHP IDE at localhost:8001 or edit Application/Schema.sql directly. Code generation via localhost:8001/Generators.

Compilation Layers

IHP compiles ~180 Haskell modules as one GHC target. Module changes are incremental — only changed modules and their dependents recompile. Never modify Layer 1 during error-fix loops — a change to Web/Types.hs or Generated/Types.hs invalidates all 59 controllers and 120 views simultaneously.

Layer 1 — stable core (compile once):
  build/Generated/Types.hs      IHP auto-generated from Schema.sql
  Web/Types.hs                  controller type definitions

Layer 2 — helpers (only touch if Layer 1 is clean):
  Application/Helper/*.hs       12 helper modules

Layer 3 — working surface (most errors live here):
  Web/Controller/*.hs           59 controllers
  Web/View/**/*.hs              120 views

Layer 4 — wiring (fix last):
  Web/FrontController.hs
  Web/Routes.hs

Compile tools (run inside devenv shell):

scripts/compile-check          # full build via ghcid (all layers), log → /tmp/ihub-compile-errors.txt
scripts/compile-check --bg     # same, background-friendly (no colour/title)
scripts/compile-check-core     # Layer 1+2 only — verify clean base before touching Layer 3

GHC compilation mode: IHP uses -fbyte-code — GHCi compiles modules to bytecode in memory, not to persistent .o files. The -fwrite-interface flag writes .hi type-info files alongside source modules; these survive session restarts and skip re-type-checking of unchanged modules. Each ghcid restart regenerates bytecode for the full module graph. Expect 20–60 min on first build; restarts are somewhat faster due to .hi caching but not dramatically so. .hi files are written next to their source files (e.g. Web/Controller/Sessions.hi).

Error-fix discipline: fix bottom-up (Layer 1 → 4). Fix one module at a time; wait for ghcid to reload before moving on. See workplans/IHUB-WP-0016-build-infrastructure-and-error-loop.md for the full SOP.

Architecture

Core Domain Model (Phase 1)

Entity	Role
Hub	Bounded domain of responsibility (Dev Hub, Ops Hub, etc.)
Widget	Smallest semantically governable interaction unit with stable ID
WidgetVersion	Version history of widget definitions
InteractionEvent	Recorded user/agent interaction (viewed, clicked, submitted, etc.) — append-only (enforced by PostgreSQL trigger)
Annotation	Structured comment attached to a widget with category
ViewContext	Logical location in the UI
CapabilityReference	Link to hub capability

Traceability Chain

Widget → InteractionEvent / Annotation
       → RequirementCandidate (Phase 2)
       → DecisionRecord (Phase 3)
       → ImplementationChange → DeploymentRecord → OutcomeSignal

IHP Conventions

• Controllers live in Web/Controller/, views in Web/View/, types in Web/Types.hs
• Schema changes go in Application/Schema.sql, then generate with IHP IDE
• Use AutoRefresh for operator dashboards (server push on DB change) — not DataSync or Server-Side Components in Phase 1
• See docs/ihp-ihf-mapping.md for how IHP capabilities map to IHF requirements

Widget Envelope

Every rendered widget wraps its HSX in a widgetEnvelope helper (Task T08) that injects the stable widget-id and view-context attributes, enabling client-side event capture without coupling to implementation.

UI Conventions

All hub interfaces follow the Tailwind layer model in specs/TailwindForInteractionHubs_v0.2.md:

Semantic Role → Visual Primitive → Tailwind Token → Screen Composition

Key rules:

• Every interactive element belongs to a named semantic role (action-primary, nav-item, data-cell, etc.)
• Use spacing rhythm from the spec; do not invent ad-hoc spacing
• State cues (hover, active, disabled, error) follow the defined color roles

Required Environment Variables

Variable	Purpose
IHP_SESSION_SECRET	Session encryption key
DATABASE_URL	Postgres connection string
IHP_BASEURL	External URL (e.g., https://example.com)
IHP_ANTHROPIC_API_KEY	Anthropic API key for Phase 5 agent-assisted distillation

Active Workplan

IHF v0.2 is complete. All 12 phases and the GAAF Compliance Foundation are implemented. No active workplan.

Completed workplans: IHUB-WP-0001 (Phase 1), IHUB-WP-0002 (Phase 2), IHUB-WP-0003 (Phase 3), IHUB-WP-0004 (Phase 4), IHUB-WP-0005 (Phase 5), IHUB-WP-0006 (Phase 6), IHUB-WP-0007 (Phase 7), IHUB-WP-0008 (Phase 8), IHUB-WP-0009 (GAAF Compliance Foundation), IHUB-WP-0010 (Phase 9 — External API Surface and Consumer SDKs), IHUB-WP-0011 (Phase 10 — Hub Registry and Widget Marketplace), IHUB-WP-0012 (Phase 11 — Advanced AI Federation), IHUB-WP-0013 (Phase 12 — Platform Memory and Continuous Learning).

GAAF Architecture Rules (enforced from IHUB-WP-0009)

These rules apply to all code written after Phase 8 completion:

1. Type discriminator columns (widget_type, event_type, category, policy_scope) must reference a registry table or carry a CHECK constraint. No bare TEXT for new type discriminators.
2. New hub-owned types must be declared in the hub's HubCapabilityManifest before use. Register via the Extensions admin UI.
3. Core tables (widgets, interaction_events, annotations, hubs, and their Phase 1–4 dependents) must not have new columns added without a corresponding update to /contracts/core/.
4. Append-only invariant on interaction_events and outcome_signals is permanent. Never propose a migration that removes or bypasses those triggers.

Key Reference Docs

File	Purpose
SCOPE.md	Situational guide — in/out of scope, terminology, entry points
ARCHITECTURE-LAYERS.md	GAAF-2026 layer map, scorecard, and compliance status
specs/InteractionHubFrameworkSpecification_v0.1.md	Full IHF spec (Phases 0–8, risks, design principles)
specs/InteractionHubFrameworkSpecification_v0.2.md	IHF extension spec (Phases 9–12) with GAAF foundation notes
specs/GoodSoftwareArchitectureFramework_2026.md	GAAF-2026 standard — the architectural compliance framework
specs/TailwindForInteractionHubs_v0.2.md	Agent-optimized Tailwind coding guide
contracts/README.md	Contract catalog — all IHF contracts by layer
docs/domain-hub-extension-guide.md	How to register a new domain hub (dev, ops, fin, sec)
docs/functional-modules.md	Functional module maturity register
docs/ihp-overview.md	IHP v1.5 fundamentals and dev workflow
docs/ihp-data-and-queries.md	Schema design, auto-generated types, query builder, migrations
docs/ihp-controllers-views-forms.md	Controller patterns, HSX, forms, validation, auth
docs/ihp-realtime.md	AutoRefresh vs DataSync vs HTMX decision guide
docs/ihp-ihf-mapping.md	IHP capability → IHF requirement mapping with schema templates

Related Repositories

• hub-core — planned shared Haskell library for domain hub bootstrapping; HubCapabilityManifest in inter-hub provides the DB-side registration contract until hub-core is implemented
• the-custodian — State Hub (decision records, workstreams) that IHF governance integrates with
• Downstream consumers: dev-hub, ops-hub, fin-hub, sec-hub — must register via HubCapabilityManifest before creating hub-owned type discriminators