Service Boundaries

Phase: 1 Architecture Plan Status: pre-implementation contract

Boundary Rules

• A service owns its database, migrations, SQL queries, events, and domain invariants.
• A service may expose read APIs for other services, but consumers must not join across databases.
• Shared libraries may contain request IDs, auth context structs, OpenAPI helpers, error envelope helpers, and generated clients. They must not contain domain write logic.
• Legacy source remains a read-only reference. Copying behavior requires an evidence note in the implementing task.
• New source goes under go-platform/ only.

API Gateway

Owns:

• Public /api/* route compatibility.
• Legacy proxy routing.
• Native service routing.
• Auth token extraction and basic JWT compatibility.
• Request/correlation ID propagation.
• CORS and body limits matching legacy defaults.
• SSE pass-through.
• Public health and metrics compatibility.

Does not own:

• Domain writes.
• Per-service database migrations.
• AI/provider credentials beyond route-level policy.
• Business rules hidden inside gateway adapters.

Auth Service

Owns:

• Local login/register/refresh/logout.
• Refresh token persistence and revocation.
• Auth provider settings.
• User auth providers.
• Token payload compatibility fields used by current frontend and guards.

Depends on:

• user-service for profile creation/read contracts.
• school-service for default organization context when needed.

Must preserve:

• Bearer token and hoctapaz.accessToken cookie compatibility at gateway.
• Access token type=access.
• Refresh token type=refresh and jti.

User Service

Owns:

• User profile read/write after identity creation.
• Teacher, student, parent profile details.
• Teacher KYC data.
• Parent-student relationships.
• Student import jobs and rows when decoupled from school membership.

Does not own:

• Organization membership policy.
• Login credential verification once auth-service is live.

School Service

Owns:

• Organizations.
• Organization units.
• Organization members.
• Tenant membership validation.
• School-scoped student membership when imported from roster flows.

Must preserve:

• X-Organization-Id behavior.
• Admin bypass rules only through explicit policy, not implicit DB access.

Classroom Service

Owns:

• Classroom records.
• Classroom members.
• Announcements.
• Lessons created inside classrooms.
• Classroom materials and tuition records.

Phase 8 start:

• P8-004 implements only classroom records and classroom members.
• Lesson, material, announcement, tuition, dashboard, leaderboard, and exam-assignment behavior remains legacy-proxied until later slices.
• Organization, unit, subject, teacher, creator, and student identifiers are stored as public ids; validation and hydration stay behind gateway adapters and owning services.

Depends on:

• school-service for tenant and membership checks.
• document-service for media/document references.
• exam-service for exam assignment references.

Course Service

Owns:

• Course catalog records.
• Sections, lessons, materials.
• Enrollment and progress.
• Course quizzes as references to exam/question contracts.

Phase 8 start:

• P8-005 implements course records, sections, lessons, material metadata, enrollments, lesson/video progress, material views, and public course projections.
• Question links, quizzes, mastery, recommendation, reports, wallet purchase, and file streaming remain legacy-proxied until later adapters.
• Organization, subject, topic, instructor, creator, student, media, uploader, question, exam, and wallet identifiers are stored as public ids; validation and hydration stay behind gateway adapters and owning services.

Does not own:

• Question canonical content.
• Exam attempt grading.

Document Service

Owns:

• Media asset metadata.
• S3/MinIO object key policy.
• Presigned upload compatibility.
• Teaching documents, purchases, shares, and content serving.

Must preserve:

• Existing object keys where migrated.
• Formula/image variant serving used by import and question editor.
• MIME and size policy compatibility until a product change is approved.

DOCX Import Service

Owns:

• DOCX Fast jobs.
• OCR document conversion jobs.
• MathType -> Word Equation conversion jobs.
• Import review draft state.
• Import question segments and processing events.
• Import SSE event stream.

Depends on:

• document-service for object reads/writes and media metadata.
• question-bank-service for approval into questions.
• exam-service for approval into draft exams/templates.
• ai-classifier-service only through explicit classification API/event contracts.

Must preserve:

• docx-fast, mathtype-equation, ocr-document source values.
• Vietnamese labels such as Import Đề Thi Nhanh (VIP), MathType -> Word Equation, and OCR Tài Liệu.
• Manual question-type overrides from review/editor saves.
• Warning, timing, media, formula, table, and source-location fields.

AI Classifier Service

Owns:

• AI classify job creation/status/events/cancel/apply workflow.
• AI provider settings.
• AI provider usage events.
• Question solution history if generated by AI.

Depends on:

• question-bank-service for applying classification or solution output.
• admin-service for feature maintenance state if centralized there.

Must preserve:

• Read-only GET bypass behavior for feature maintenance where legacy allowed it.
• SSE snapshot/heartbeat/job update semantics.

Question Bank Service

Owns:

• Questions.
• Question versions.
• Question options.
• Question type definitions.
• Folders, groups, tags.
• Difficulty and taxonomy references unless centralized later.

Must preserve:

• Existing question types: SINGLE_CHOICE, MULTIPLE_CHOICE, TRUE_FALSE, TRUE_FALSE_GROUP, SHORT_ANSWER, SHORT_NUMERIC_ANSWER, ESSAY.
• Rich content JSON compatibility.
• Scoring rule semantics.
• Archive-vs-hard-delete behavior until explicitly changed.

Exam Service

Owns:

• Exam folders.
• Exam blueprints and generation runs.
• Exam paper templates and sections.
• Exam authoring, scheduling, assignments, access links.
• Exam question snapshots at publish time.

Depends on:

• question-bank-service for source question reads before snapshot.
• classroom-service for classroom assignment validation.

Must preserve:

• Draft-only edit rule.
• Publish snapshot refresh rule.
• Access password hash behavior.

Native snapshot boundary:

• exam-service stores exam question snapshots as its own persisted state.
• Callers must provide hydrated question payloads through service APIs; exam-service must not join the question-bank database.
• Snapshot payloads preserve content JSON, options, sub-items, answer keys, scoring rules, media/formula refs, option order, and section/order metadata for later attempt snapshots.

Attempt Service

Owns:

• Attempt creation.
• Attempt question snapshots.
• Answer saves.
• Optimistic answer versioning.
• Submission and grading.
• Attempt events and result visibility.

Depends on:

• exam-service for published exam snapshot/start policy.

Must preserve:

• Student-only start rule.
• Online/open/assigned/link access checks.
• Attempt snapshots independent from later question edits.
• clientVersion vs serverVersion conflict semantics.

Notification Service

Owns:

• Notifications.
• Notification preferences.
• Notification event fanout and delivery state.
• In-app delivery state for already-resolved recipients.

Consumes:

• Exam published/assigned/submitted events.
• Import completed/failed events.
• Admin or support ticket events if retained.

Does not own:

• User search, role broadcast resolution, or parent/student relationship lookup. These come from user-service/gateway adapters.
• Admin audit logs. Those belong to admin-service.
• Support ticket storage. That stays legacy-proxied until an admin/support slice owns it.
• Email/SMS provider delivery in P9-001.

Analytics Service

Owns:

• Read models for dashboard, weak topics, progress, mastery, and result analytics.
• Event-derived aggregates.
• Attempt-result projections ingested from already-hydrated attempt/event payloads.
• Service-local analytics/audit event capture that is not admin audit history.

Does not own:

• Canonical exam, attempt, course, or question state.
• Parent-child relationships or user profile hydration.
• Classroom membership validation.
• Notification unread rows used in full parent progress.

Admin Service

Owns:

• Feature maintenance registry state and public active-feature payloads.
• Admin audit logs.
• Admin dashboard and operational controls in later slices.
• Support/admin workflow storage only after an explicit audited task.

Consumes:

• Audit events emitted by other native services or gateway adapters.
• Operational projections produced by service-specific APIs/events.

Does not own:

• Wallet/AZ Credit ledger or payment rails in P9-003.
• User credentials, profile, KYC storage, or tenant membership.
• Queue retry, AI provider settings, support tickets, or admin dashboard aggregation in the feature-maintenance/audit foundation slice.

Must preserve:

• Exact feature maintenance keys and Vietnamese labels from the legacy shared registry.
• Public status payload { items, activeFeatureKeys, generatedAt }.
• Read-only AI classification job GET bypass during maintenance.
• Audit action/entity keys so the existing Vietnamese admin operation labels keep working through adapters.
• CSV/XLSX classroom report export in P9-002.

Admin Service

Owns:

• Feature maintenance.
• Audit logs.
• Admin dashboards and operational controls.
• Support tickets unless a support-service is approved.

Does not own:

• Wallet/AZ Credit in the first target service set. Those routes stay legacy-proxied.