docs: add architecture documentation and standardize filenames

docs/RUNTIME_LIFECYCLE.md

@@ -0,0 +1,63 @@
+# Runtime Lifecycle Subsystem
+
+The `nx9-auth` runtime lifecycle subsystem provides an enterprise-grade, lock-free, deterministic architecture for application startup, dependency assembly, operational observability, background worker coordination, prioritized shutdown hooks, and graceful HTTP server termination.
+
+## Architecture Overview
+
+```
+CLI Commands / binary entrypoint (main.rs)
+   │
+   ▼
+ApplicationBuilder
+   │
+   ├── Database Initialization (SQLite / PostgreSQL)
+   ├── Repository Provider Assembly
+   ├── AppState Construction
+   └── Router Construction (Axum API + SPA UI)
+   │
+   ▼
+Application Container (Lifecycle)
+   │
+   ├── AtomicRuntimeState Machine
+   ├── SignalManager (SIGINT / SIGTERM)
+   ├── ShutdownCoordinator (CancellationToken Hierarchy)
+   ├── WorkerManager (Task Groups)
+   ├── HookRegistry (Prioritized Shutdown Hooks)
+   └── RuntimeMetrics
+   │
+   ▼
+axum::serve (HTTP Server)
+```
+
+## Lifecycle States (`RuntimeState`)
+
+The state machine is lock-free and driven by `AtomicU8` with `compare_exchange` transitions.
+
+| State | Value | Description |
+| :--- | :--- | :--- |
+| `Initializing` | 0 | Runtime configuration loading and dependency assembly. |
+| `Starting` | 1 | Database connection pool init, migrations, router assembly. |
+| `Running` | 2 | HTTP server bound and actively serving requests. |
+| `Draining` | 3 | Shutdown signal received; server stops accepting new connections, draining existing HTTP requests. |
+| `StoppingWorkers` | 4 | Cancelling and joining active background worker tasks. |
+| `ExecutingHooks` | 5 | Executing registered shutdown hooks in priority order (`First` -> `Normal` -> `Last`). |
+| `ClosingResources` | 6 | Closing database connection pools and flushing logs. |
+| `Stopped` | 7 | All resources released cleanly; runtime process exits with status 0. |
+
+## Startup Sequence
+
+1. `main()` parses CLI flags and loads configuration via `Config::find_and_load()`.
+2. `run_server()` invokes `Application::builder(config).build().await`.
+3. `ApplicationBuilder` creates `Application` and executes `initialize()`.
+4. `initialize()` transitions state to `Starting`, connects database pool, executes migrations, and builds `Router`.
+5. `app.start().await` transitions state to `Running`, binds `TcpListener`, prints `Listening on <addr>`, and awaits `axum::serve`.
+
+## Graceful Shutdown Sequence
+
+1. `SIGINT` (Ctrl+C) or `SIGTERM` signal received by `SignalManager` or `ShutdownCoordinator`.
+2. `axum::serve` completes its graceful shutdown loop, stopping the TCP listener.
+3. State transitions to `Draining`.
+4. State transitions to `StoppingWorkers`; `WorkerManager` cancels and joins task groups.
+5. State transitions to `ExecutingHooks`; `HookRegistry` executes registered hooks.
+6. State transitions to `ClosingResources`; `PoolHandle` closes the database pool.
+7. State transitions to `Stopped`; application returns `Ok(())` with exit status 0.