# User Service Docs

This directory keeps service-local documentation that is more operational or
more example-heavy than [`../README.md`](../README.md).

Sections:

- [Runtime and components](runtime.md)
- [Main flows and boundaries](flows.md)
- [Operator runbook](runbook.md)
- [Contract examples](examples.md)

Decision records:

- [PostgreSQL migration](postgres-migration.md) — schema and storage
  decisions landed by `PG_PLAN.md §3`
- [Stage 21 — `user_name` + `display_name` refactor](stage21-user-name-display-name.md)
- [Stage 22 — `permanent_block` + `DeleteUser` soft-delete](stage22-permanent-block-delete-user.md)

Primary references:

- [`../README.md`](../README.md) for stable service scope and business rules
- [`../openapi.yaml`](../openapi.yaml) for the trusted internal REST contract
- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) for system-level transport
  and ownership rules
- [`../../TESTING.md`](../../TESTING.md) for the cross-service testing matrix