social-app/docs/plans/2026-03-25-schemas-restructure-design.md

Backend Schemas Restructure Design

Goal: Restructure backend/src/schemas into clear domain/shared/enums modules while keeping API contracts in backend/src/v1/*/schemas.py.

Architecture: Move reusable validation models and enums into schemas/domain, schemas/shared, and schemas/enums.py. Keep versioned request/response contracts in v1/*/schemas.py and update imports to explicit module paths. Remove legacy aggregate exports and duplicate/empty schema directories.

Tech Stack: Python 3.13, Pydantic v2, Ruff, Pytest.

---

Approved decisions

• Use one-shot hard cut.
• Keep API contracts in backend/src/v1/*/schemas.py.
• Keep schemas as reusable constraints only.
• Remove implicit root re-export usage.

Target structure

• backend/src/schemas/enums.py
• backend/src/schemas/domain/*.py
• backend/src/schemas/shared/*.py
• backend/src/v1/*/schemas.py (unchanged naming and ownership)

Validation gates

• uv run ruff check ...
• uv run pytest ... for impacted suites
• ./infra/scripts/dev-migrate.sh migrate