# ARCHITECTURE

> **Placeholder.** Full architecture doc lands from a parallel research
> agent in a subsequent commit. Until then, the closest existing
> reference is the v1 design note:
>
> <https://git.s8n.ru/s8n/auth-limbo/blob/main/docs/V2-ARCHITECTURE.md>
>
> That document was written *during v1's lifecycle* as the design
> sketch for what would become v2. Treat it as the starting point —
> not the final architecture.

## Planned scope of this document (when written)

- **State machine.** Every login state, every transition, every
  timeout. Diagram + prose.
- **Threading model.** Which work runs on the main thread, which on
  async pools, where the synchronisation boundaries are.
- **Persistence.** What state is stored, where, in what format.
  Restart-safety semantics.
- **AuthMe integration.** How v2 reads `authme.db`, how it observes
  AuthMe's lifecycle events, how it decouples from AuthMe quirks.
- **Failure modes.** Backend-down, chunk-not-loaded, player-disconnect-
  mid-flow, server-restart-mid-flow. One paragraph per mode.
- **Observability.** Logging schema, metrics surface (if any — opt-in
  only), how an operator debugs a stuck player.
- **Security model.** Threat model, trust boundaries, what a hostile
  client can and cannot do.

Until the agent lands the real doc, design discussion happens in
PRs and the v1 reference above.