generated from coulomb/repo-seed
Bernd Worsch
3cac021213
Some checks failed
Test / test (push) Has been cancelled
Delivers the full Phase 9 external API layer: - Versioned REST API (/api/v2/) with OpenAPI 3.1 spec; enum arrays for widget_type, event_type, annotation category drawn live from registry tables - OAuth 2.0 client credentials flow (/api/v2/token); hub:*:write scopes gated on active HubCapabilityManifest FK - API key management: SHA256-hashed tokens, key_prefix for display, one-time reveal on creation, revocation support - TypeScript and Python consumer SDKs generated from registry tables (/api/v2/sdk/ihf-client.ts, /api/v2/sdk/ihf-client.py) - Webhook delivery: HMAC-SHA256 signing, append-only webhook_deliveries, fire-and-forget dispatch via forkIO, 3-retry logic - Admin API dashboard with 24h stats (request count, error rate, last seen) - Rate limiting (per-minute) and daily quota enforcement via api_request_log - Schema migration: api_consumers, api_keys, webhook_subscriptions (CHECK constraint on 6 framework lifecycle topics), webhook_deliveries (append-only trigger), api_request_log - ARCHITECTURE-LAYERS.md scorecard: 3.34 → 3.41 (approaching Strong) - contracts/functional/interaction-reporting-v1.md extended with Phase 9 endpoint catalogue and 422 validation error format GAAF: no bare TEXT discriminators; webhook event_type uses CHECK constraint over 6 allowed framework lifecycle topic strings (not widget event types). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
150 lines
7.6 KiB
Markdown
150 lines
7.6 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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 10 (Hub Registry and Widget Marketplace) is the next target. Create workplan `workplans/IHUB-WP-0011-ihf-phase10-hub-registry.md` when ready. Use `/ralph-workplan` to drive implementation.
|
||
|
||
Phase 10 builds directly on `HubCapabilityManifest` (from WP-0009) — the hub registry IS that table with a public-facing discovery UI. No new hub registry table is required.
|
||
|
||
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).
|
||
|
||
## 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
|