Overview

:::info Source Sourced from services/catalog-service/SERVICE_OVERVIEW.md in the documentation repo. :::

Companion: DOMAIN_MODEL · API_CONTRACTS · EVENT_SCHEMAS · ../../docs/03-microservices/catalog-service.md

1. Purpose (1-paragraph)

The catalog-service owns the published, immutable view of courses on the Ghasi-edTech platform. It projects Course and CourseVersion aggregates that downstream services (search, marketplace, enrollment, delivery) consume as the single source of truth for "what can be discovered, enrolled in, and played." It is read-mostly, has no editing surface (authoring-service owns drafts), and acts as a domain projection over the content-packaging pipeline. It also owns the tenant-scoped taxonomy tree used for browsing and search facets.

2. Scope Boundaries

In scope	Out of scope
Published Course aggregate (metadata, slug, visibility, status)	Course drafts, block authoring → authoring-service
Immutable CourseVersion snapshot (duration, locales, PlayPackage ref)	PlayPackage building, offline bundles → content-service
Taxonomy / tag trees (per tenant + global)	Full-text search indexing → search-service (subscribes to catalog events)
Visibility rules: private / org / marketplace / public	Pricing, SKUs, listings → marketplace-service
Version lifecycle: published → deprecated → withdrawn	Learner enrollment, assignment → enrollment-service
Locale availability per version	Media storage → media-service (resolved via MediaRef)
Read APIs for browse/detail/facets	Certification templates → certification-service

3. Architectural Position

 ┌────────────────┐     content.play_package.built.v1     ┌─────────────────┐
 │ authoring-svc  │──────────────────────┐                │ content-service │
 └────────────────┘                      ▼                └─────────────────┘
           authoring.course_draft.published.v1                       │
                                         │                           │
                                         ▼                           │
                                ┌─────────────────┐                  │
                                │ catalog-service │◀─────────────────┘
                                │  (projection)   │   content.play_package.built.v1
                                └────────┬────────┘
                                         │ catalog.course_version.published.v1
                ┌────────────────────────┼───────────────────┬─────────────┐
                ▼                        ▼                   ▼             ▼
        search-service        marketplace-service     enrollment-svc   delivery-svc

• Upstream: authoring-service, content-service (events).
• Downstream: search-service, marketplace-service, enrollment-service, delivery-service, progress-service (all projection consumers).
• Peers: media-service (resolved cover image URLs via signed URL API), tenant-service (visibility rules).

4. Key Capabilities

1. Course registration — creates a Course record on first authoring.course_draft.published.v1.
2. Version publication — creates an immutable CourseVersion on content.play_package.built.v1.
3. Version lifecycle — deprecate (soft, still playable) and withdraw (hidden from catalog, read-only history).
4. Metadata management — slug, title, description, cover, taxonomy refs (mutable on the Course, immutable on the Version).
5. Visibility enforcement — cross-tenant reads gated on visibility in {marketplace, public}.
6. Taxonomy management — hierarchical tree(s) per tenant + a platform-wide default namespace (ghasi:subjects).
7. Locale surface — which locales a specific version is playable in.
8. Read API — paginated, filterable, ETag-cached browse endpoints.

5. Non-Goals

• No write API for course content (blocks, lessons, assessments).
• No per-learner state (progress, completion, scores).
• No pricing, discounts, or commerce logic.
• No full-text search — emits events for search-service.
• No AI generation of courses — consumes already-authored and already-packaged artifacts.

6. Slices & Readiness

Slice	Milestone	Content
S1	M1	Course + CourseVersion CRUD projections; minimal API; no taxonomy
S2	M2	Taxonomy tree, tags, browse facets, search-service integration
S3	M3	Visibility (marketplace, public) + marketplace-service integration
S4	M4	Full versioning: deprecate/withdraw, multi-version playback, locale surface
S5	M5	Multi-tenant taxonomy overlays, AI localization assist (delegated)

Readiness targets: L2 by M1 (single-tenant happy path), L4 by M4 (multi-region, multi-tenant, full lifecycle, offline-aware).

7. Service Vital Stats

Attribute	Value
Language / runtime	Node.js 20 LTS + TypeScript 5.x
Framework	Fastify 4.x
DB	Postgres 15 (RLS) schema catalog
Event bus	NATS JetStream, streams CATALOG, consumers on AUTHORING, CONTENT
Cache	Redis 7 (read-through; ETag key)
Observability	OpenTelemetry SDK, OTLP → collector
Tenancy model	RLS + X-Tenant-Id; soft visibility rules layered above
Data class	operational retention (30 d hot / 13 mo cold)
On-call tier	Tier 2

8. Consumers (SLO Perspective)

Consumer	Read pattern	Latency SLO	Staleness tolerance
search-service	Event-driven projection	n/a	≤ 5 s after publish
marketplace-service	Event-driven + read-back	p95 100 ms	≤ 10 s
enrollment-service	Read at enroll time	p95 50 ms	fresh
delivery-service	Read at launch	p95 50 ms	fresh
Web clients (browse)	ETag + max-age 300 s	p95 150 ms	5 min

9. Ownership

• Team: Learning Platform · Content squad.
• Escalation: platform-oncall → content-oncall.
• Design reviewers: domain architect (catalog), search architect, marketplace architect.

10. Related Docs

• 02 DDD & Bounded Contexts §4.3
• 04 Event-Driven Architecture
• 05 API Design
• 12 Data Models §5
• 13 Security & Tenancy