Editor

The editor module is the editor-facing surface of the platform — the interface a newsroom editor would actually use to tune the recommender’s behaviour. It is deliberately ordinary: server-rendered HTML with HTMX for partial-page updates, no SPA framework, no JavaScript build pipeline for its UI layer.

The shape decisions are recorded in two ADRs:

• ADR-0005: TypeScript + Express, swappable by design — the swap is the architectural argument, not the editor itself.
• ADR-0011: SSR + HTMX, no SPA. The aesthetic should match real CMS admin panels, not flashy demos.

The whole TypeScript half of the tutorial lives under editor/.

What an editor sees

The editor interface presents a configuration to the editor: sliders for the three soft constraints (diversity, recency, sentiment), toggles + a threshold for the sensitive-topic guard, and a list management UI for editorial promotion. A preview pane shows the recommendation list a sample user would see under the current configuration. Moving any control issues an HTMX hx-post to /preview, which refreshes the preview pane in place — no page reload, no JavaScript framework.

That live-preview shape is the operational form of editorial accountability: an editor sees the effect of a change before they commit the change.

How the code is laid out

• src/server.ts wires the Express app together.
• src/routes/ contains one file per editor surface — recommendations, configurations, preview, change-explainer partial.
• src/configurations/, src/recommendations/, and src/articles/ are typed thin shells over the FastAPI client: repository + view + types.
• src/schemas.ts is where Zod schemas validate every form post.

The TypeScript client types are generated from the OpenAPI file the FastAPI serving module publishes (ADR-0006). That means a contract change makes the editor fail at compile time, not in production.

Tests cover the surface

editor/tests/ holds 76 Vitest tests, all passing. Render tests confirm the HTML output shape; repository tests confirm the API integration; route tests confirm form submission flows. The HTMX partials are tested by asserting the returned HTML fragment shape.

Type safety end-to-end

The Express side uses strict TypeScript, the generated OpenAPI client preserves types from FastAPI’s Pydantic schemas, and the Zod validators at form boundaries ensure even editor-input data is checked before it reaches the API. That gives a single type system from FastAPI’s request models all the way to the rendered HTML — which is the production-realism payoff of ADR-0005’s TypeScript choice.

After this module

The assistants module hangs its UI partials inside the editor — when an editor changes a slider, the recommendations partial refreshes and an HTMX hx-get triggers the change-explainer partial to describe why the list moved.