Internal docs - Home page

Overview

This project is all about the ETR Study API. If you are working on this project, this page helps you find where things live and where to learn more.

• What is this API? The ETR Study API provides a set of endpoints designed to help you build systems (for example, a study app) that support knowledge review using effective retrieval and scheduling methods.
• Want to know how the system is designed? See the System Design page for the big picture, diagrams, and project goals.
• Learning methodology (ideas only, not the API): Methodology — ETR methodology explanation.
• Employee portal (profiles & article ownership): See Employee portal for maintainer profiles and internal article ids.
• Looking for developer info and how to work on the code? Find guides, setup steps, and technical notes in the Developers Docs.
• Need a single documentation writing and review standard? Use Documentation style guide and audit standard for required structure, tone, and conformance checks.
• Need final frontend requirements for docs navigation and theme UX? Read #1 Docs frontend navigation and theme controls.
• Need docs keyboard shortcuts for quick actions and command palette? Open Docs frontend hotkeys.
• Need a full visual and interaction specification for docs frontend components? Read Docs frontend UI kit (premium surfaces and interactions).
• Need architecture decisions and deep technical implementation specs? Read ADR Index for decision rationale and RFC Index for implementation-level details (including docs search internals).
• Need onboarding from zero to first endpoint and docs? Start with Onboarding guide (setup → endpoint → docs).
• Interested in the API itself? See the HTTP API (internal) for endpoints and examples. For ETR notes, start at the Conspectus hub (field mapping and sample JSON).
• Need full error contract details? Open Error matrix for complete COMMON_* / USER_* matrices and sync process.
• Need the official API reference? Check the OpenAPI baseline or OpenAPI Explorer. If the app is running, visit /docs for live docs.
• Want more details? Explore the sidebar for more topics, or follow any link above to go deeper into the topic you need.

Onboarding path (first setup to endpoint + docs)

Canonical onboarding flow for new contributors:

1. Local startup and first successful API call.
2. Add one endpoint through schema, repository, service, and router layers.
3. Update internal docs and navigation where required.
4. Run make verify and make verify-ci before push.

Open the full step-by-step guide: Onboarding from zero to endpoint and docs.

Request path and layering

The typical request flow is: API → services → repositories → database. Request bodies are validated using Pydantic (app/schemas/) before they reach handler code. Validation errors are converted in app/validation/ to the standard 422 response format. Business rules that require database access are enforced in app/services/ (see ADR 0003).

For details, see:

• Layering model, processing order, and business rule overview: Business Logic Guide
• Schema evolution and contract safety: Schemas and contracts
• System architecture (C4 diagrams, containers, observability stack): System design §3

Contract and integrators

External developers must use the OpenAPI document as the contract: committed snapshot at docs/openapi/openapi-baseline.json, explorer at OpenAPI (test), live Swagger when the app runs at /docs. Release-to-release changes are summarized in the repository root CHANGELOG.md (ADR 0013).

Versioning rules (URL major version, additive changes within a major) follow ADR 0004.

Observability and operations

Health, readiness, and metrics expectations follow ADR 0009. Non-functional detail (including /metrics and Prometheus) is summarized under System design — Non-Functional Requirements (NFR-5). Structured logging follows ADR 0023. Operational recovery steps belong in Runbooks when they are procedural.

Page history