Onboarding: from zero to endpoint and docs

End-to-end onboarding path: start the project locally, add one endpoint through all layers, and publish matching documentation in the same workflow.

Goal and expected outcome

After this guide you should have:

Phase 1. Local setup and first successful call

  1. Create environment and install dependencies: 
    make venv && make install
    Expected: command ends with Dependencies installed.
  2. Initialize local config: 
    make env-init
    Expected: .env created from env/example (if it already exists, continue with current file).
  3. Apply migrations: 
    make migrate
    Expected: Migrations applied.
  4. Start API: 
    make run
    Expected: Uvicorn running on 127.0.0.1:8000 (or your .env host/port).
  5. In a second terminal, verify first success: 
    curl -i http://127.0.0.1:8000/live
    Expected: HTTP/1.1 200 OK and JSON status body.

Phase 2. Implement one endpoint across layers

Use this order so changes are reviewable and consistent with project layering.

  1. Create/update DB structures and migration if needed.
  2. Add request/response models in app/schemas/.
  3. Add repository data-access methods in app/repositories/.
  4. Add service logic and business checks in app/services/.
  5. Add router handler in app/api/v1/ with validation + response mapping.
  6. Update OpenAPI examples where relevant (app/openapi/examples/).

For a concrete beginner walkthrough, follow: Add POST /api/v1/contract.

Phase 3. Document the endpoint and behavior

  1. Update internal API hub/resource pages under docs/internal/api/ (resource index.html and operation pages as needed).
  2. If you add or rename internal pages, update sidebar source docs/assets/internal-sidebar.js.
  3. Keep docs structure consistent with: internal service docs layout guide.
  4. Sync generated fragments and docs artifacts: 
    make docs-fix

Phase 4. Quality gates and ready-to-review state

  1. Run full local gate (mutating docs): 
    make verify
  2. Before push, run CI-like gate: 
    make verify-ci
    This includes docs drift check and baseline docs accessibility checks.
  3. Confirm changed files include both code and docs for the new endpoint.

Page history

Date Change Author
Added Page history section (repository baseline). Ivan Boyarkin