authoring-service-v2 — business features

1. What it is

This is where courses get made. An author works in the admin web app — typing a prompt, uploading a document, or editing a tree of sections and lessons by hand — and this service turns that into a module, farming the expensive AI work out to six background workers and collecting their results as they land.

It is a hub: all six pipeline workers (content, image, extraction, research, suggest, rag) talk only to it and never to each other (ARCHITECTURE.md §3.1). Nothing a learner sees lives here — publishing hands the finished module to micro-learning-service-v2, which serves it to the mobile app.

2. Feature map

flowchart LR
  ADM["Author in the admin web app"] --> CHAT["Creation chat"]
  ADM --> BUILD["The builder: 27 tools"]
  ADM --> RUNS["Generation runs, review gate, estimates"]
  ADM --> MKT["Marketplace: browse, copy, curate"]
  ADM --> CRED["AI credits and budget"]
  CHAT --> HTTP["48 routes under /v1/admin/authoring"]
  BUILD --> TOOLS["POST /tools/{tool_name}"]
  RUNS --> WS["WS /v1/admin/authoring/ws"]
  MKT --> HTTP
  CRED --> HTTP
  SVC["micro-learning, users-auth"] --> INT["16 routes under /internal/v1"]
  WORK["6 pipeline workers"] -.-> EVT["31 consumed NATS subjects"]
  EVT -.-> RUNS
  LOOPS["In-process loops"] --> JOBS["6 background jobs"]

3. Features

Admin

Employee (mobile)

None. A learner never reaches this service. Published modules are served by micro-learning-service-v2; this service only hands them over at publish (H1).

Internal (other services)

Background

4. API reference

All 67 routes from the scan. Every /v1/admin/authoring/* route has an in-repo caller by construction: users-auth proxies the entire prefix verbatim through one catch-all (users-auth-service/app/routes/oper_authoring.py:369-398, ARCHITECTURE.md §3.2 H22), and the listed frontend doc names the specific path. The admin web app itself is not in this repo.

5. Async contracts

Consumes

33 registrations over 31 subjects. Streams are owned by the workers except AUTHORING_CORE, which this service creates (app/consumers/manager.py:42-55). Durable names are derived mechanically as asv2-<subject-with-dashes> (manager.py:68-71).

Publishes

Three more subjects leave this service through a variable the scanner cannot resolve, so they are not in the JSON: the eight async catalog tools publish their own subjects via tool.nats_subject (app/services/tool_dispatcher.py:287, libs/oper-tools/oper_tools/catalog.json) — authoring.image.job.requested, authoring.content.regenerate.requested, authoring.suggest.suggestions.requested among them — and budget alerts publish authoring.usage.quota_warning / authoring.usage.quota_exceeded (app/services/budget_service.py:35-36,281), which nothing consumes (§8).

Background jobs

All five loops are created in the lifespan (app/main.py:186-195) and cancelled on shutdown; _pull_loop tasks are created by consumer_manager.start() (app/main.py:185, app/consumers/manager.py:220). There is no CronJob — every job is in-process, and with replicas: 1 there is exactly one of each.

6. Data it owns

Postgres authoring_service_v2_db, 29 alembic revisions (migrations/versions/0001…0029). frameworks and module_framework_outlines were dropped in 0029_drop_frameworks; industry_taxonomy became category_synonyms and per-tenant categories were unified in 0028_tenant_categories_one_vocabulary.

7. Dependencies

flowchart LR
  UA["users-auth-service: admin proxy H22"] --> AV2
  ML["micro-learning: recent modules H14"] --> AV2
  WK["6 pipeline workers"] -.-> AV2
  AMIN["asset-manager: upload completed"] -.-> AV2
  AV2["authoring-service-v2"] --> MLO["micro-learning: ingest, publish, translate"]
  AV2 --> UAO["users-auth: tenant, profiles, credit debit"]
  AV2 --> SPW["suggest-pipeline-worker"]
  AV2 --> AM["asset-manager"]
  AV2 --> RAG["rag-context-worker"]
  AV2 --> STT["stt-service"]
  AV2 -.-> WK
  AV2 -.-> NW["notification-worker"]
  AV2 --> PG["Postgres authoring_service_v2_db"]
  AV2 --> RD["Redis db 9"]

Solid = HTTP, dotted = NATS. Outbound HTTP edges H1-H5 plus stt-service; inbound H14 and H22 (ARCHITECTURE.md §3.2).

8. Dead-code verdicts

Every entry point with no in-repo caller. Deleting is a separate decision — see the hub roll-up. Tests are not callers. The admin web app is not in this repo, so an admin-facing route with no in-repo caller would be suspect; in practice none are, because users-auth proxies the whole admin prefix.

9. Sources

• tools/feature-docs/out/authoring-service-v2.json — the scanned entry points this page is checked against.
• ARCHITECTURE.md §2 (inventory), §3.1 (hub shape), §3.2 (HTTP edges H1-H5, H14, H22 and the /internal/v1 prefix trap), §3.3 (streams), §3.4 (shared database writers), §3.5 and §4.1(6) (Redis DNS), §4.2 (broken CI referencing the retired v1 Deployment).
• bug-hunt-reports/authoring-service-v2.md — 14 findings; #1, #2, #6, #7, #8, #11, #12 fixed, #3, #4, #5, #9, #10, #13, #14 deferred.
• authoring-service-v2/docs/API_ENDPOINTS.md — route-by-route reference, incl. §8 internal ops API and §10 categories.
• authoring-service-v2/docs/frontend-integration.md — tool dispatcher contract, read endpoints, WebSocket topics.
• authoring-service-v2/docs/worker-integration.md — the subject-by-subject worker contract.
• authoring-service-v2/docs/fe-creation-chat.md, fe-research-module.md, fe-import-estimate.md, fe-progress-integration.md, fe-voice-dictation.md, fe-module-lifecycle.md, fe-image-status.md, fe-divider-block.md, fe-quiz-select-word-block.md, module-translations-fe.md, create-draft-module.md, frontend-authoring-flow.md — frontend integration guides; each names the paths its screen calls.
• authoring-service-v2/docs/marketplace-plan.md — catalogue, office curation, copy in/out.
• authoring-service-v2/docs/ai-cost-usage-plan.md and ai-cost-monitoring.md — usage ledger, budgets, reconciliation, alert runbook.
• authoring-service-v2/docs/SDD-OPER-course-extraction-updated.md and its -ADDENDUM-language / -ADDENDUM-integration — the extraction engine and its review gate.
• New-Design/SDD-composer-engine.md, New-Design/SDD-creation-chat.md, New-Design/PLAN-doc-creation-chat.md, New-Design/SDD-authoring-service.md, New-Design/SDD-authoring-chat-worker.md, New-Design/SDD-multi-admin.md, New-Design/SDD-admin-notification-centre.md — product naming and the tool/scope model.
• authoring-service-v2/README.md, READINESS.md, LIVE_TEST_GAPS.md, TODO.md (E23 — the chat-worker publisher that does not exist yet).