Architecture

Hexagonal layout

HTTP (/api/*)  →  application use-cases  →  ports
                         ↑
                    adapters (plugins)

Layer	Role	Examples
Domain	Pure types	Session, Diagnosis, AuthSubject
Ports	Interfaces	AuthPort, QueryPort, LlmPort, CatalogPort
Adapters	Implementations	QueryCraft, OpenAI, YAML catalog, mock_*
Application	Use-cases	classifyProblem, startSession, agent loop
HTTP	Delivery	Express routers under /api

Swap backends with env (AUTH_ADAPTER, LLM_ADAPTER, …) — see Tweaking.

Diagnosis flow

Owner problem
    │
    ▼
Auth (Bearer) ──► restaurant principalId
    │
    ▼
Classify ──► playbook_ids (1–2)
    │
    ▼
Agent loop (investigate model + tools)
    │     query_data ──► QueryCraft / mock
    │     ask_manager ──► pause (awaiting_manager)
    │     update_hypothesis / select_playbook
    │     conclude_diagnosis ──► Diagnosis
    ▼
Session status: concluded | awaiting_manager

Prompt blocks (agent)

Block	Content	Source
A	Method + hard rules (static)	src/application/agent/block-a.ts
B	This restaurant’s data availability	prompt.ts + tenant + data-domains.yaml
C	Selected playbooks + session board	playbooks YAML + session state

Knowledge pack on disk

Path	Purpose
diagnostics/playbooks/*.yaml	Problem types, hypotheses, probes
diagnostics/recommendations/catalog.yaml	Shared actions (rec_id)
diagnostics/registry/data-domains.yaml	What QueryCraft domains mean

Loaded by Catalog (CATALOG_ADAPTER=yaml).