diff --git a/README.md b/README.md
index 2cd14a8..443e50c 100644
--- a/README.md
+++ b/README.md
@@ -131,6 +131,70 @@ make ci
---
+# Laminar Runtime Architecture Diagram
+
+```mermaid
+flowchart TD
+
+ A["Arc<RwLock<AppState>>
Global shared runtime container"]
+
+ A --> B["AppState
Fields:
- upstreams"]
+
+ B --> C["UpstreamPool
Fields:
- id
- current_index
- backends"]
+
+ C --> D["AtomicUsize
Round robin index"]
+
+ C --> E["Vec Arc BackendState
Shared backend objects"]
+
+ E --> F["Arc BackendState
Reference counted backend state"]
+
+ F --> G["BackendState
Fields:
- config
- healthy
- active_connections
- failed_health_checks"]
+
+ G --> H["BackendServerConfig
Static backend configuration"]
+
+ G --> I["AtomicBool healthy
Backend health state"]
+
+ G --> J["AtomicUsize active_connections
Tracks active connections"]
+
+ K["TCP Proxy Task
Accepts client connections"]
+
+ K --> L["next_backend
Selects healthy backend"]
+
+ L --> F
+
+ K --> M["ConnectionGuard new
Starts connection tracking"]
+
+ M --> N["ConnectionGuard
Owns backend Arc"]
+
+ N --> J
+
+ N --> O["Drop implementation
Decrements connection count"]
+
+ P["Background Health Checker Task"]
+
+ P --> Q["check_backend_status
TCP health probe"]
+
+ Q --> I
+
+ R["Future Systems
Metrics
Retries
Least connections"]
+
+ R --> F
+```
+
+# Runtime Flow Summary
+
+1. Client connects to Laminar TCP proxy.
+2. Proxy task accesses shared AppState.
+3. next_backend() selects a healthy backend.
+4. Backend Arc is cloned and moved into ConnectionGuard.
+5. ConnectionGuard increments active_connections.
+6. TCP traffic is proxied between client and backend.
+7. When connection ends, ConnectionGuard drops automatically.
+8. active_connections is decremented safely.
+9. Background health checker continuously updates backend health state.
+
+---
+
# CI Policy
All pull requests must pass CI before merging.
diff --git a/src/proxy/tcp.rs b/src/proxy/tcp.rs
index 0bd013c..d72330b 100644
--- a/src/proxy/tcp.rs
+++ b/src/proxy/tcp.rs
@@ -18,7 +18,7 @@ pub async fn start_tcp_proxy(address: &str, state: SharedAppState) -> anyhow::Re
info!("new client connected {}", client_address);
let state = state.clone();
-
+ // Arc> means SharedAppState only
tokio::spawn(async move {
if let Err(error) = handle_connection(client_stream, state).await {
error!("connection handling failed {:?}", error)
@@ -32,7 +32,7 @@ async fn handle_connection(mut stream: TcpStream, state: SharedAppState) -> anyh
let state = state.read().await;
let upstream = &state.upstreams[0];
let backend_arc = match upstream.next_backend() {
- Some(backend) => backend.clone(),
+ Some(backend) => backend,
None => {
error!("no healthy backend available");
return Ok(());