Appearance
OpenAPI Contracts
Native Go-platform OpenAPI contracts live in the repository under contracts/openapi. They are intentionally kept outside the VitePress docs tree because the YAML files are build inputs for generated clients and service validation.
Contract Files
| Contract | Repository path |
|---|---|
| API Gateway | contracts/openapi/api-gateway.yaml |
| Admin Service | contracts/openapi/services/admin-service.yaml |
| AI Classifier Service | contracts/openapi/services/ai-classifier-service.yaml |
| Analytics Service | contracts/openapi/services/analytics-service.yaml |
| Attempt Service | contracts/openapi/services/attempt-service.yaml |
| Auth Service | contracts/openapi/services/auth-service.yaml |
| Classroom Service | contracts/openapi/services/classroom-service.yaml |
| Course Service | contracts/openapi/services/course-service.yaml |
| Document Service | contracts/openapi/services/document-service.yaml |
| DOCX Import Service | contracts/openapi/services/docx-import-service.yaml |
| Exam Service | contracts/openapi/services/exam-service.yaml |
| Notification Service | contracts/openapi/services/notification-service.yaml |
| Question Bank Service | contracts/openapi/services/question-bank-service.yaml |
| School Service | contracts/openapi/services/school-service.yaml |
| User Service | contracts/openapi/services/user-service.yaml |
Frontend Client Generation
Browser-facing code should generate from the gateway contract only:
bash
pnpm frontend:generate-apiThat command writes the API Gateway client types to packages/api-client/src/generated/api-gateway.ts.
Service contracts are for internal service validation, gateway adapter work, migration tooling, and focused service tests. Do not generate public browser clients from every native service contract unless that service is explicitly promoted to a public BFF surface.
Promotion Rule
A route cannot move out of legacy_proxy until these artifacts are aligned:
- Legacy route evidence and request/response examples.
- Native OpenAPI path and schema.
- Gateway route-table mapping.
- Auth, tenant, envelope, validation, and SSE parity notes.
- Unit, adapter, parity, browser/runtime, and rollback evidence.