HocTapAZ API Guide

This guide is the entry point for API usage in go-platform. The core rule is: frontend and external clients call API Gateway through the legacy-compatible /api/* surface; native services expose /v1/* routes for gateway adapters, service-to-service calls, migration tools, and smoke tests.

Environments

Environment	Frontend base	API base	Notes
Local Go platform	http://127.0.0.1:5201-5206	http://localhost:8085	Use VITE_API_BASE_URL=http://localhost:8085.
V2 dev Pages	https://v2.dev.*.hoctapaz.com	https://hoctapaz.com until a dedicated v2 gateway is cut over	Current Cloudflare frontend bundles use VITE_API_BASE_URL=https://hoctapaz.com.
Internal service tests	n/a	http://<service>:8080/v1 or local service ports	Use native /v1/* only when testing a service or adapter directly.

Do not point frontend apps directly at service /v1/* routes. The browser contract is the API Gateway/BFF contract.

Public Gateway Contract

API Gateway owns the public compatibility layer:

• /api/* legacy-compatible HTTP routes.
• /api/v1/* compatibility rewrite where legacy callers still use it.
• Authorization: Bearer <accessToken> and hoctapaz.accessToken cookie extraction.
• X-Organization-Id, X-Request-Id, and X-Correlation-Id propagation.
• SSE pass-through for import, classification, attempt, and exam event streams.
• Legacy response envelopes and validation semantics while a route is migrating.

Success responses generally preserve the legacy envelope:

{
  "success": true,
  "data": {},
  "message": "OK"
}

Native /v1/* services may use canonical internal errors, but gateway adapters must translate public /api/* errors back to the expected legacy shape.

Required Headers

Header	Public /api/*	Native /v1/*	Purpose
Authorization: Bearer <token>	Required for authenticated routes	Required only when a service endpoint verifies tokens directly	Access token auth.
Cookie: hoctapaz.accessToken=<token>	Supported by gateway	Not a general service contract	Browser compatibility.
X-Organization-Id	Required on tenant-scoped routes	Forwarded by gateway or set in service tests	Tenant and organization scope.
X-Request-Id	Optional caller-provided	Forwarded or generated	Request tracing.
X-Correlation-Id	Optional caller-provided	Forwarded or generated	Cross-service tracing.
X-User-Id	Gateway-derived	Required on many native service tests	Actor identity.
X-User-Role	Gateway-derived	Required on role-guarded native endpoints	Actor role.

For native service tests, pass X-User-Id, X-User-Role, and X-Organization-Id explicitly only when the service API requires actor context. For browser traffic, let gateway derive those headers from the token.

Route State Lifecycle

Routes move one slice at a time:

State	Meaning
legacy_proxy	Public traffic is still served by legacy NestJS.
shadow_read	Gateway returns the legacy response and calls native for diff evidence.
native_read	Gateway serves the native read response after parity evidence is accepted.
native_write_shadow_validate	Write authority is controlled while resulting state is compared.
native_write	Native service is authoritative for that write route.
removed	Route is removed only after callers and ops confirm it is unused.

No route should move from legacy_proxy to native_write without documented legacy evidence, OpenAPI contract, adapter mapping, tests, and rollback notes.

Calling Examples

Local public login through gateway:

curl -sS http://localhost:8085/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"teacher@hoctapaz.com","password":"password123"}'

Local authenticated question-type read through gateway:

curl -sS 'http://localhost:8085/api/question-types?summary=true' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'X-Organization-Id: org_local_center'

Native service smoke test, bypassing gateway intentionally:

curl -sS 'http://localhost:8098/v1/question-types?summary=true' \
  -H 'X-User-Id: usr_teacher' \
  -H 'X-User-Role: TEACHER' \
  -H 'X-Organization-Id: org_local_center'

Use native examples only for service development, route-table rehearsals, and migration validation. Product clients should stay on /api/*.

OpenAPI Source

Native contracts live under:

• contracts/openapi/api-gateway.yaml
• contracts/openapi/services/*.yaml

Generate frontend gateway types with:

pnpm frontend:generate-api

The generated client is intentionally gateway-oriented. Do not generate browser clients from every service OpenAPI file unless a service is explicitly promoted to a public BFF surface.

Service Guide Index

Service	Guide	Public exposure
API Gateway	API Gateway	Public /api/* and health surface.
Auth Service	Auth Service	Rehearsed through selected /api/auth/* routes only.
User Service	User Service	Internal/native until gateway adapter is promoted.
School Service	School Service	Organization read rehearsals only.
Classroom Service	Classroom Service	Kept legacy-proxied until response hydration is complete.
Course Service	Course Service	Selected student course rehearsals only.
Document Service	Document Service	Storage/media adapters under controlled route tables.
DOCX Import Service	DOCX Import Service	Import status/create/approval rehearsals through gateway examples.
Question Bank Service	Question Bank Service	Question type/read/classification slices under gateway route tables.
Exam Service	Exam Service	Internal until exam authoring/publish adapters are promoted.
Attempt Service	Attempt Service	Attempt start/save/submit/event route rehearsals.
AI Classifier Service	AI Classifier Service	Apply route only; job runtime remains legacy-proxied.
Analytics Service	Analytics Service	Internal/native read foundation until public adapter cutover.
Notification Service	Notification Service	Inbox/preferences/parent alert rehearsals.
Admin Service	Admin Service	Feature maintenance and audit route rehearsals.

Cutover Checklist

Before promoting a route table entry:

1. Capture legacy route evidence and current frontend request shape.
2. Fill the native service OpenAPI contract.
3. Add or update the gateway target_prefix mapping.
4. Preserve auth, tenant, envelope, validation, and SSE behavior.
5. Add unit, gateway adapter, parity, and browser/runtime verification.
6. Document rollback by route-table switch or entry deletion.
7. Update this guide and the service-specific API page.