Work log — 22 July 2026

What we built and verified today on FOSA Smart Advisor (TypeScript hexagonal rewrite on one port).

Prior JS prototype remains under backup/v1-2026-07-22-pre-rewrite/.

---

Goals for the day

1. Replace the old prototype with a strict plugin / ports-and-adapters backend.
2. Ship each pipeline step as its own testable HTTP API.
3. Wire QueryCraft (auth + NLP) and OpenAI (classify + investigate).
4. Serve docs + Redoc + APIs on a single process (default port 3040).
5. Prove a live end-to-end diagnosis on a real restaurant (shop 11).

---

Architecture shipped

Layer	What landed
Domain	Session, Diagnosis, Tenant, typed errors
Ports	Auth, Tenant, Query, Llm, Catalog, SessionStore, Notify, EventBus
Adapters	mock / QueryCraft / OpenAI / YAML catalog / memory
Application	classify, agent tool loop, start/resume session
HTTP	Express /api/* + /docu + /redoc + OpenAPI YAML

Swap backends with env (AUTH_ADAPTER, QUERY_ADAPTER, LLM_ADAPTER, CATALOG_ADAPTER, …). Third parties gated by *_ENABLED + credentials.

---

API surfaces completed

Step	Endpoints	Status
Discovery	GET /api/steps, GET /api/health	ready
Auth	POST /api/auth/login, GET /api/auth/me	ready (QueryCraft or mock)
Catalog	GET /api/catalog/playbooks, .../{id}, .../recommendations/{recId}	ready (YAML)
Classify	POST /api/classify	ready
Query	POST /api/query/ask	ready (QueryCraft NLP or mock)
Advisor	POST/GET /api/advisor/sessions, POST .../answers	ready

Agent tools (investigate loop)

query_data · ask_manager · update_hypothesis · select_playbook · conclude_diagnosis

Caps (defaults): max 8 queries, 3 manager asks, 24 LLM turns per run.

Knowledge pack

• diagnostics/playbooks/*.yaml (5 playbooks)
• diagnostics/recommendations/catalog.yaml
• diagnostics/registry/data-domains.yaml

---

Docs & Redoc work today

Deliverable	Path / URL
Docusaurus site	/docu (website/, baseUrl: /docu/)
Quick start, architecture, pipeline, sessions	website/docs/*
Testing, Postman, tweaking guides	same
Live test run (principle + shop 11 walkthrough)	/docu/docs/live-test-run
This work log	/docu/docs/work-log-2026-07-22
OpenAPI v0.2.0 (detailed descriptions/examples)	openapi/advisor.openapi.yaml → /openapi/...
Redoc UI	/redoc (Swagger UI removed by design)
README updated for URL map + plugins	repo root

---

Live verification (same day)

Against https://querycraft.ncrts.pro + OpenAI, restaurant principalId = 11:

1. Auth — login / me OK.
2. Classify — "sales are down across the board" → demand-decline (OpenAI).
3. Query ask — “total sales yesterday” → $41.48 (~25s after timeout raise).
4. Advisor start — ~260s, 4 live QueryCraft tool calls → awaiting_manager.
5. Resume answers — concluded with confirmed acquisition_dried_up, action local-visibility-audit, verify_after 2026-08-19.

Session id from that run: 0mrw7fpnsf70b794c05585ce7f (see Live test run).

Fix applied during testing

Issue	Change
QueryCraft aborted at ~15s	QUERYCRAFT_TIMEOUT_MS 15000 → 120000 (.env + .env.example)
Mock LLM hid real Advisor behavior	Switched run to LLM_ADAPTER=openai, OPENAI_ENABLED=true

---

Tests & tooling

• Automated suites: container smoke, QueryCraft auth/NLP, YAML catalog, classify, pipeline routes, advisor sessions.
• Scripts: npm run dev (docs build + nodemon), docs:build, test, typecheck.
• Offline path still available: all *_ADAPTER=mock + CATALOG_ADAPTER=yaml.

---

Explicitly not done (still stubbed)

Item	Notes
Verification cron / batch	verifySessionsStub / follow-up job not implemented
Notify on verify-due	Webhook adapter exists; not driven by session lifecycle
SSE streaming	Tool events are sync JSON only

---

How to re-read today’s work

1. Architecture — layout
2. Pipeline — test each step
3. Sessions — API shapes
4. Live test run — worked example
5. Tweaking — prompts / YAML / models
6. Redoc — contracts

---

Logged: 2026-07-22 · FOSA Smart Advisor rewrite day