authoring-content-worker — business features

1. What it is

When an admin turns a document or a prompt into a training module, something has to write the actual teaching material — the screens, the explanatory text, the quiz questions. This worker does that: it takes one lesson (or one concept) at a time, asks a large language model to write it against Oper's authoring framework, checks the result, and saves it straight into the draft the admin is looking at. It also rewrites a single block when an admin clicks "regenerate", and translates a published module into another language.

2. Feature map

flowchart LR
  ADMIN["Admin (authoring UI)"] --> AV2[authoring-service-v2]
  AV2 --> F1["Write a lesson (v3)"]
  AV2 --> F2["Write a concept (v1 / v2)"]
  AV2 --> F3["Rewrite one block"]
  AV2 --> F4["Translate a module"]
  F1 --> C3["authoring.content.generation.requested.v3"]
  F2 --> C1["authoring.content.generation.requested(.v2)"]
  F3 --> C4["authoring.content.regenerate.requested"]
  F4 --> C5["authoring.content.translate.requested"]
  C3 --> DRAFT["writes drafts.state + .ready event"]
  C1 --> DRAFT
  C4 --> DRAFT
  C5 --> ML["micro-learning translation store"]

3. Features

Admin

Employee (mobile)

None. Employees never reach this worker; they read the finished module from micro-learning.

Internal (other services)

Background

4. API reference

There is no business API. Both routes exist for Kubernetes.

5. Async contracts

Consumes

Publishes

Background jobs

No cron, no CronJob, no polling loop: every unit of work arrives as a NATS message.

6. Data it owns

This worker owns no database. It points at authoring-service-v2's database (authoring_service_v2_db, k8s/secret.yaml:15) and writes the admin's draft in place with raw SQL: it loads drafts.state under SELECT … FOR UPDATE, merges the generated screens into the JSON tree, and writes it back. That row lock is the only thing serialising two lessons of the same run. This is one of the platform's two-writer couplings recorded in ARCHITECTURE.md §3.4 — a schema change to drafts in authoring-v2 breaks this worker silently, and the shared-table write is exactly why merging these two services is on the consolidation list.

7. Dependencies

flowchart LR
  AV2[authoring-service-v2] -. NATS requests .-> CW[content-worker]
  CW -. ready / failed / progress / usage .-> AV2
  CW -- "SQL: drafts.state FOR UPDATE" --> DB[("authoring_service_v2_db")]
  CW -- "HTTP H6: context blob" --> RAG[rag-context-worker]
  CW -- "HTTP H7: translations" --> ML[micro-learning-service-v2]
  CW -- LLM calls --> OR[OpenRouter]

8. Dead-code verdicts

Every entry point with no in-repo caller. Deleting is a separate decision — see the hub roll-up.

Everything else on this page has a named in-repo publisher, consumer or kubelet probe.

9. Sources

• authoring-content-worker/README.md — NATS contract table, stream rules, scaling note
• authoring-content-worker/TODO.md — known contract drift and the replicas/max_ack_pending constraint
• docs/screen-archetypes.md, docs/agent-orchestrator-architecture.md, docs/agent-orchestrator-langgraph.md
• bug-hunt-reports/authoring-content-worker.md — 7 findings; #1 (lost concept on hard crash) and #4 (unwrapped regenerate publish) fixed
• ARCHITECTURE.md §3.1 (spoke topology), §3.2 (H6, H7), §3.3 (streams and the doc→module flow), §3.4 (shared-DB writers)
• authoring-service-v2/docs/worker-integration.md §4.3 — the contract this worker implements
• Scan output tools/feature-docs/out/authoring-content-worker.json