asset-manager-service — business features

1. What it is

asset-manager-service is the platform's file desk. No other service touches the storage bucket directly: they ask asset-manager for a short-lived upload ticket, the bytes go straight from the uploader to S3, and asset-manager keeps the record of what was stored, for which company, and whether it is public or private. When a file is public it is served from cdn.useoper.com; when it is private, readers get a signed link that expires.

2. Feature map

flowchart LR
  ASV2["authoring-service-v2"] --> TICKET["Get an upload ticket"]
  IW["authoring-image-worker"] --> TICKET
  ML["micro-learning-service-v2 (TTS, certificates, media)"] --> TICKET
  ASV2 --> LOOKUP["Look up an asset"]
  IW --> LOOKUP
  ML --> LOOKUP
  ASV2 --> COPY["Re-host under another tenant"]
  TICKET --> R1["POST /api/v1/create-upload-url"]
  TICKET --> R2["POST /api/v1/assets/{id}/mark-uploaded"]
  R2 --> EV["publish authoring.asset.upload.completed"]
  LOOKUP --> R3["GET /api/v1/assets/{id}"]
  LOOKUP --> R4["GET /api/v1/assets/{id}/url"]
  COPY --> R5["POST /api/v1/assets/copy"]
  ADMINOPS["Housekeeping (no in-repo caller)"] --> R6["GET /api/v1/assets"]
  ADMINOPS --> R7["DELETE /api/v1/assets/{id}"]

3. Features

Internal (other services)

4. API reference

Auth on every business route is internal_auth_middleware: either X-Oper-Key + X-Tenant-Id (service-to-service) or a Bearer JWT validated against JWKS and bound to the X-Tenant-Id header (app/core/auth.py:60). All in-repo callers use the internal key.

5. Async contracts

Consumes

Publishes

Two properties worth knowing, both deliberate and documented in app/core/nats_publisher.py:1-17: the publish happens after the HTTP response is sent, so a cold or unhealthy NATS connection cannot be billed to the caller's latency; and it is fire-and-forget with no flush(), so a dropped event is logged and the authoring run is re-kicked rather than the upload being failed. It is also conditional — only object keys containing /authoring-service-v2/ publish anything (app/api/v1/assets.py:51), so image, audio and certificate uploads are silent by design.

Background jobs

6. Data it owns

Postgres logical DB tools; asset-manager is the only writer (ARCHITECTURE.md §3.4).

No cross-service writes: nothing else writes tools, and asset-manager writes no other service's database. The real state it guards is outside Postgres — the oper-assets bucket, whose public-read policy is scoped to the CloudFront distribution's ARN (terraform/main.tf:121-131) and whose CORS rules exist specifically so browsers can PUT directly to a presigned URL (terraform/main.tf:55-62).

7. Dependencies

flowchart LR
  ASV2["authoring-service-v2"] --> AM["asset-manager"]
  IW["authoring-image-worker"] --> AM
  ML["micro-learning-service-v2 + TTS worker"] --> AM
  K8S["kubelet probes"] --> AM
  AM --> PG[("Postgres tools")]
  AM --> S3[("S3 oper-assets")]
  AM --> CDN["CloudFront cdn.useoper.com"]
  AM --> NATS["NATS core"]
  NATS --> ASV2B["authoring-service-v2 asset consumer"]

ARCHITECTURE.md §3.2 records three inbound HTTP edges (H2 authoring-v2, H8 image-worker, H9 tts-worker-v2). The TTS worker's code lives inside micro-learning-service-v2/app/tts_worker/, and the same service also calls asset-manager from its certificate issuer, media routes and admin audio routes — so the micro-learning image is a caller in its own right, not only through the TTS worker.

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 caller. There are no dead NATS consumers here because there are no consumers at all, and the single published subject has a verified subscriber.

9. Sources

• asset-manager-service/docs/api_endpoints.md — request/response shapes and constraints per endpoint.
• asset-manager-service/spec/spec-driven.md — the original design for object-key layout, visibility and lifecycle.
• bug-hunt-reports/asset-manager-service.md — six findings; #1 (list IDOR), #2/#3 (auth fail-open) fixed, #4–#6 open.
• ARCHITECTURE.md §3.2 (edges H2, H8, H9), §3.3 (AUTHORING_CORE), §3.4 (the tools DB), §3.5 (Redis map), §3.6 (external egress).
• Code read directly: app/main.py, app/api/v1/assets.py, app/api/v1/upload.py, app/api/health.py, app/core/auth.py, app/core/nats_publisher.py, app/core/s3_client.py, app/config.py, migrations/versions/, terraform/main.tf, terraform/variables.tf, k8s/.
• Caller verification: authoring-service-v2/app/core/http.py, authoring-service-v2/app/consumers/register.py, authoring-image-worker/app/asset_client.py, micro-learning-service-v2/app/tts_worker/pipeline.py, .../app/services/certificate_service.py, .../app/routes/media_routes.py, .../app/routes/admin_audio_routes.py, .../app/utils/asset_manager.py, global-configs/k8s/global-configmap.yaml.