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–4 complete. Phase 5 (Agent-Assisted Distillation and Suggestion) is the active implementation target.

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.

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

Phase 9 (External API) work is tracked in workplans/IHUB-WP-0010-ihf-phase9-external-api.md. Use /ralph-workplan workplans/IHUB-WP-0010-ihf-phase9-external-api.md to drive implementation loops.

Phase 9 entry gates (all satisfied by IHUB-WP-0009):

• Four type registries seeded and validated in controllers ✓
• HubCapabilityManifest table and activation workflow operational ✓
• /contracts/ directory with Core and Functional contract artifacts ✓
• ARCHITECTURE-LAYERS.md scorecard at ≥3.3 ✓ (actual: 3.34)
• Architectural fitness functions in CI ✓
• docs/domain-hub-extension-guide.md published ✓

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).

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