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: Phase 0 (specification) is complete. Phase 1 (Minimal Interaction Core) is the active implementation target. No application code exists yet.

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)

Active Workplan

Phase 1 work is tracked in workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md (12 tasks, T01–T12). Use /ralph-workplan workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md to drive implementation loops.

Phase 1 exit criteria:

• Widgets can be addressed and annotated reliably
• Interaction data is captured with actor attribution and view context
• Hub-level inspection of interaction signals is possible via a dashboard

Key Reference Docs

File	Purpose
SCOPE.md	Situational guide — in/out of scope, terminology, entry points
specs/InteractionHubFrameworkSpecification_v0.1.md	Full IHF spec (8 phases, risks, design principles)
specs/TailwindForInteractionHubs_v0.2.md	Agent-optimized Tailwind coding guide
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 base package for domain/capability registration
• the-custodian — State Hub (decision records, workstreams) that IHF governance integrates with
• Downstream consumers: dev-hub, ops-hub, fin-hub