HocTapAZ Service Responsibility Matrix

Status: canonical responsibility map for Go microservices

This document is the source of truth for service ownership. Frontend apps call only api-gateway or an approved BFF. Services own their own databases and must not read each other's databases.

The current Go platform intentionally splits attempt-service out of the broader exam domain and analytics-service out of operational/admin reporting. They are canonical service rows for implementation and dispatch, even though earlier high-level sketches grouped attempts under exam and dashboards under admin/operations.

Canonical Map

Service	Current implementation	Owns	Main APIs/workflows	Does not own
api-gateway	services/api-gateway	public entrypoint, route state, JWT verification, CORS, request IDs, rate limits, reverse proxy, docs/openapi surface	/api/*, /v1/routes, route rehearsal, auth/header adapters	business writes, service DBs, payment, IAM credential/session, or profile storage
bff-service	services/bff-service foundation	frontend-specific aggregation, dashboard composition, and bounded owner-service composition previews without primary DB	web/admin screen shells, source status, route metadata, weak-topic dispatch preview	canonical domain writes, replacing owner services, hiding domain logic
iam-service	services/iam-service	accounts, credentials, sessions, refresh tokens, JWT/JWKS, roles, permissions, org membership for access control, invites, auth/security audit	register/login/logout/refresh/me, role/permission APIs, permission check, membership access context	avatar/profile details, subscription, wallet, payment, learning data
profile-service	services/profile-service	education profiles, display fields, avatar, phone, DOB, gender, student/teacher/parent/staff metadata, parent-child read models, teacher KYC storage/review, public profile views	profile create/read/update, role-specific profile views, public profile, parent-recipient resolve, teacher KYC self-service/admin review	login, password, JWT, roles, permissions, payment, usage quota
organization-service	services/school-service alias	schools, centers, campuses, org units, tenant metadata, academic-year calendar/configuration, tenant resolve/validate; member rows only as IAM-synchronized read models with ordering/tombstones	organization/unit CRUD, future academic-year lifecycle, tenant validation, member read/metadata adapters	login, profile details, subscriptions, class content, permission-bearing organization membership writes
classroom-service	services/classroom-service	classrooms, class members, teacher assignments, classroom progress/read models	class CRUD, join, student/member management, progress summaries	account creation, question source of truth, exam grading
course-service	services/course-service	courses, modules/sections, lessons, course materials metadata, enrollments, progress	authoring, public course catalog, student course/progress APIs	question bank, exam attempts, file bytes, wallet purchases
question-service	services/question-bank-service alias	questions, answers, solutions, versions, tags, taxonomy refs, question type definitions	question CRUD/read projections, type definitions, AI classify apply, import ingest	exam sessions, attempt scoring, import parser state
exam-service	services/exam-service	exams, sections, exam question snapshots, publish workflow, access links, assignments	exam authoring, publish, snapshot APIs	source question editing, answer attempts, parser/import state
attempt-service	services/attempt-service	attempt sessions, attempt-owned question snapshots, answers, grading, events, results	start/save/submit/events/result	exam authoring, live question reads, profile/org source of truth
file-service	services/document-service alias	files, media assets, object metadata, signed URLs, teaching documents, actor-scoped import-source assets	upload/presign, media metadata/content, owner-scoped OCR/MathType source upload and internal read	parsing document content, credit charging, question persistence
import-service	services/docx-import-service alias	import jobs, DOCX/PDF/OCR parse orchestration, preview/drafts, review state, approval saga checkpoints	DOCX fast jobs, owner-scoped OCR/MathType job create/reprocess, events/SSE, review save, approve to question/exam, explicit usage preflight/consume calls	canonical questions after approval, file object store, quota policy/counters, wallet ledger
formula-docx-service	runtimes/go-formula-docx runtime behind docx-import-service; do not create services/formula-docx-service unless a later ADR promotes it	DOCX/formula/table conversion runtime and parser metrics	internal parse/convert endpoints through import adapters	import review, question/exam writes, payment/quota, public frontend routes
ai-service	services/ai-classifier-service alias	AI provider adapters, AI requests/jobs, prompt context, model usage, AI results	classify/generate/explain/grade foundations, provider settings	quota decisions, wallet debits, canonical question/exam writes outside explicit APIs
billing-service	services/billing-service foundation	plans, prices, subscriptions, invoices, plan entitlements	plan catalog, subscription lifecycle, invoice state, payment-outcome activation	provider webhooks, wallet ledger, usage counters, identity/profile
wallet-service	services/wallet-service foundation	AZ Credits, wallet balances, immutable ledger, grants/debits/refunds	balance, debit/credit/refund, ledger read	subscription lifecycle, provider reconciliation, login/profile
usage-service (entitlement-service alias)	services/usage-service foundation	feature gates, usage counters, quota periods, limit overrides, materialized billing entitlements	entitlement sync, entitlement lookup, check/consume quota, counter listing/reset, override upsert	money movement, subscription lifecycle, AI/import/file/question execution, payment webhooks
payment-service	services/payment-service foundation	payment orders, provider transactions, webhooks, reconcile/idempotency	create payment order, webhook ingest, reconcile	subscription activation without billing, wallet source of truth
notification-service	services/notification-service	notifications, templates, preferences, delivery/read/delete state, notification events, provider delivery orchestration and attempts	inbox, templates, preferences, parent alerts, event fanout, provider dispatch/retry/DLQ	user lookup, parent-student resolution, OTP issuance/verification, provider secrets, audit logs
search-service	services/search-service foundation	rebuildable search indexes, sync checkpoints, projection replay receipts and version tombstones	index document upsert/delete, full-text search, filters, source sync state, replay-safe copied projection changes	canonical business data, public route rules, owner-service writes
audit-service	services/audit-service foundation	compliance/security append-only event history, source idempotency, retention/legal-hold metadata, legacy audit projection/backfill target	append/list audit events, security event queries	domain decisions, feature maintenance, public admin audit compatibility until a route migration is proven
analytics-service	services/analytics-service	dashboards, result/progress/mastery projections, weak topics	analytics results, event snapshots, summaries	canonical exam/attempt/course/question/profile data
admin-service	services/admin-service	feature maintenance, admin read models, moderation/ops controls, current public/admin audit compatibility	feature maintenance, admin audit list/create compatibility, operational dashboard APIs	wallet/payment ledger, IAM credentials, profile storage, compliance-grade audit ledger

Deprecated Compatibility Scaffold

Scaffold	Current implementation	Purpose	Must not own
user-service	services/user-service	Deprecated compatibility scaffold for temporary profile routes while IAM/Profile cutover evidence is completed. Use docs/agents/service-tasks/user-service-retirement.md for quarantine/removal work only.	New identity/profile work, credentials, roles, permissions, payments, learning data, or any canonical service ownership.

MVP Sequence

1. Gateway/BFF, IAM, Profile, Organization, Classroom.
2. Question, Exam, Attempt, File, Import, Formula DOCX, Search.
3. AI, Billing, Wallet, Usage, Payment.
4. Notification, Audit, Admin, Analytics.

Domain Groups

Domain	Canonical services
Entry/API	api-gateway, bff-service
Identity	iam-service
User/Profile	profile-service
School/Organization	organization-service, classroom-service
Learning Content	course-service, file-service
Question/Exam Runtime	question-service, exam-service, attempt-service
Document AI Import	import-service, formula-docx-service, ai-service
Monetization	billing-service, wallet-service, usage-service, payment-service
Operations	notification-service, search-service, audit-service, admin-service, analytics-service

Boundary Rules

• Frontend never calls service hostnames directly.
• auth-service is not a Go-platform service boundary. /api/auth* and /v1/auth* are compatibility namespaces backed by iam-service; do not create an auth-service task pack, API doc, OpenAPI contract, deployment, or runtime directory.
• Do not create duplicate implementation directories for alias names: organization-service uses services/school-service, question-service uses services/question-bank-service, file-service uses services/document-service, import-service uses services/docx-import-service, and ai-service uses services/ai-classifier-service.
• Every service task must cite legacy evidence or explicitly state there is no legacy equivalent.
• Gateway adapters can shape responses but cannot hide business logic that belongs in a service.
• AZ Credits and subscriptions must use Billing/Wallet/Usage/Payment service boundaries; do not add them to IAM/Profile.
• Import creates draft/preview state. Approved questions become question-service state through an explicit API.
• DOCX Question Bank approval may call usage-service for the reviewed questions entitlement, using an approval-owned idempotency key after Question Bank ingest. It never owns a usage counter or wallet ledger; legacy parity does not add an AZ Credit debit to this approval path.
• Browser OCR/MathType uploads pass through a non-default Gateway route to file-service, receive only an opaque sourceAssetId, and are reopened by import-service with exact organization, actor, purpose, and source-kind checks. Neither service exposes source object keys to the frontend.
• Exam and attempt store snapshots by value; they do not join the question DB.