assignment-service — business features

1. What it is

assignment-service is the service that says who has to do which training module by when. An admin picks a module and an audience (one person, a group, or the whole company), gives it a due date, and this service turns that into one row per person, pushes "new training assigned" to their phone, chases them with reminders until they finish, tells admins who is late, and answers every other service's question about a learner's outstanding training.

2. Feature map

flowchart LR
  ADMIN["Admin web app"] --> ASSIGN["Assign training to people"]
  ADMIN --> TRACK["See who has done it"]
  EMP["Employee mobile app"] --> MINE["My assignments"]
  SVC["Other services"] --> ASK["Internal lookups"]
  SCHED["In-pod schedulers"] --> NUDGE["Reminders, escalation, digest"]
  ASSIGN --> R1["POST /v1/admin/assignments"]
  ASSIGN --> W1["expansion_worker (NATS)"]
  TRACK --> R2["GET /v1/admin/assignments/:id"]
  MINE --> R3["GET /v1/employee/assignments"]
  ASK --> R4["12 internal endpoints"]
  NUDGE --> W2["reminder + digest loops"]

3. Features

Admin

Employee (mobile)

Internal (other services)

Background

4. API reference

61 rows = every route in the scan JSON. dup in the Feature column marks the second mount of the shared router (see §1). Auth: admin JWT = tenant admin/manager bearer token plus the named scope; internal = X-Oper-Key or an internal-service JWT; employee JWT = a learner's token.

5. Async contracts

Everything runs on the one shared MICRO_LEARNING stream. All publishing goes through the one NATSClient.publish() helper (app/core/nats_client.py:116) and all subscribing through its subscribe() / pull_subscribe() delegates, so the subjects below are the ones the callers pass in.

Consumes

Publishes

Known defect: all of the above use core nc.publish, not js.publish, so the publisher never sees a JetStream ack and sets no Nats-Msg-Id — the stream's 120s duplicate window cannot help (to-be-reviewed AS-A9).

Background jobs

There are no k8s CronJobs for this service — every schedule above lives inside the single API pod (replicas: 1), so a rolling restart pauses reminders and the digest for the duration of the roll.

6. Data it owns

One logical Postgres DB, assignments, on the shared instance. 15 alembic revisions; head adds performance indexes (2026_08_30_add_perf_indexes.py). ARCHITECTURE.md §3.4 still lists a second writer, assignment-expansion-worker — that is stale: the merge landed (§6 M1, PR #501) and the repo directory now holds no source, so assignment-service is the only writer.

Tables this service writes in someone else's database: none. Tables in assignments written by anyone else: none.

7. Dependencies

flowchart LR
  ML["micro-learning-service-v2"] --> AS["assignment-service"]
  UA["users-auth-service"] --> AS
  NW["notification-worker"] --> AS
  AS --> UA
  AS --> ML
  AS --> NW
  AS -.-> JS["MICRO_LEARNING stream"]
  JS -.-> NW
  JS -.-> AS

Inbound HTTP: micro-learning (H13, mobile read path, 8 call sites), users-auth (H20, plus the GDPR CronJob H23), notification-worker (H26). Outbound HTTP: users-auth (H15 — groups, members, profiles, timezone), micro-learning (H16/H17 — progress and module validation), notification-worker (H18 — device check). Async both ways over the one shared stream. Numbering per 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.

9. Sources

• ARCHITECTURE.md — §2 (service inventory), §3.2 HTTP edges H13/H15-18/H20/H24/H26, §3.3 streams and consumer conventions, §3.4 shared databases, §4.1 live bugs, §5-§6 (M1 expansion-worker merge).
• assignment-service/docs/BUSINESS_LOGIC.md — creation / update / cancellation / listing flows, expansion, progress, notifications, worker inventory, endpoint summary.
• assignment-service/docs/ARCHITECTURE.md — module layout and the (partly stale) worker/endpoint tables.
• assignment-service/docs/streams.md — published/consumed event payload contracts (its training.assignments.expanded and progress.init_required entries are stale, see §8).
• assignment-service/docs/manual-reminders-fe-integration.md — the frontend contract for manual reminders, the notifications log, activity feed and assignee deliverability block; the strongest evidence that the admin assignment routes have a live caller.
• assignment-service/docs/assignment-details-api-gaps.md — what the detail screen shipped vs what was deliberately not built (reports have no CSV/PDF/email).
• assignment-service/docs/question-retry-settings.md — the admin → assignment → /v1/employee/assignments → mobile path for quiz overrides.
• assignment-service/README.md — original K1-K5 phase framing, auth modes, health endpoints.
• bug-hunt-reports/assignment-service.md — 24 findings; #14 (expansion never ran) and #7/#19 (event worker never committed) are fixed and their fixes are reflected here; #9, #20, #24 cited above. #8 is stale: it was rejected on the grounds that nothing publishes training.progress.*, but micro-learning does publish training.progress.assignment_progress (app/events/events.py:125, from app/routes/progress_mobile_routes.py:1344), and _handle_progress_event now commits — so that path is live, not dead (§3, §5, §8).
• to-be-reviewed/assignment-service.md + to-be-reviewed/README.md — the notification-engine review. Of its three broken notification paths, two are now fixed in code (A1 completion push via the training.module.completed consumer; escalation consumer added, plus the critical priority constraint widened) and the third, the disabled notification_event_worker, remains deliberately off. Two of its claims are superseded: AS-A12 (the in-pod expansion worker is dead) — the standalone worker was deleted and this one is now started; and AS-A10/AS-A8 (the training.progress.> consumer has no producer) — only its lesson_completed / assignment_completed branches do.
• global-configs/k8s/users-auth-ingress.yaml — the single app ingress; decides which of these routes the outside world can reach at all.
• assignment-service/k8s/deployment.yaml, k8s/configmap.yaml, alembic/versions/* (15 revisions), app/main.py, app/routes/*, app/workers/* — read directly for every claim above.