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 |
| Audit Service | contracts/openapi/services/audit-service.yaml |
| Attempt Service | contracts/openapi/services/attempt-service.yaml |
| BFF Service | contracts/openapi/services/bff-service.yaml |
| IAM Service | contracts/openapi/services/iam-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 |
| Billing Service | contracts/openapi/services/billing-service.yaml |
| Usage Service | contracts/openapi/services/usage-service.yaml |
| Payment Service | contracts/openapi/services/payment-service.yaml |
| Question Bank Service | contracts/openapi/services/question-bank-service.yaml |
| School Service | contracts/openapi/services/school-service.yaml |
| Profile Service | contracts/openapi/services/profile-service.yaml |
| Search Service | contracts/openapi/services/search-service.yaml |
| Wallet Service | contracts/openapi/services/wallet-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.