feat(documentation): Updated documentation with architecture flow diagrams.

readme.md

@@ -2,6 +2,192 @@
 
 A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, and dynamic routing with authentication options.
 
+## Architecture & Flow Diagrams
+
+### Component Architecture
+The diagram below illustrates the main components of SmartProxy and how they interact:
+
+```mermaid
+flowchart TB
+    Client([Client])
+    
+    subgraph "SmartProxy Components"
+        direction TB
+        HTTP80[HTTP Port 80\nSslRedirect]
+        HTTPS443[HTTPS Port 443\nNetworkProxy]
+        PortProxy[TCP Port Proxy\nwith SNI routing]
+        IPTables[IPTablesProxy]
+        Router[ProxyRouter]
+        ACME[Port80Handler\nACME/Let's Encrypt]
+        Certs[(SSL Certificates)]
+    end
+    
+    subgraph "Backend Services"
+        Service1[Service 1]
+        Service2[Service 2]
+        Service3[Service 3]
+    end
+    
+    Client -->|HTTP Request| HTTP80
+    HTTP80 -->|Redirect| Client
+    Client -->|HTTPS Request| HTTPS443
+    Client -->|TLS/TCP| PortProxy
+    
+    HTTPS443 -->|Route Request| Router
+    Router -->|Proxy Request| Service1
+    Router -->|Proxy Request| Service2
+    
+    PortProxy -->|Direct TCP| Service2
+    PortProxy -->|Direct TCP| Service3
+    
+    IPTables -.->|Low-level forwarding| PortProxy
+    
+    HTTP80 -.->|Challenge Response| ACME
+    ACME -.->|Generate/Manage| Certs
+    Certs -.->|Provide TLS Certs| HTTPS443
+    
+    classDef component fill:#f9f,stroke:#333,stroke-width:2px;
+    classDef backend fill:#bbf,stroke:#333,stroke-width:1px;
+    classDef client fill:#dfd,stroke:#333,stroke-width:2px;
+    
+    class Client client;
+    class HTTP80,HTTPS443,PortProxy,IPTables,Router,ACME component;
+    class Service1,Service2,Service3 backend;
+```
+
+### HTTPS Reverse Proxy Flow
+This diagram shows how HTTPS requests are handled and proxied to backend services:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant NetworkProxy
+    participant ProxyRouter
+    participant Backend
+    
+    Client->>NetworkProxy: HTTPS Request
+    
+    Note over NetworkProxy: TLS Termination
+    
+    NetworkProxy->>ProxyRouter: Route Request
+    ProxyRouter->>ProxyRouter: Match hostname to config
+    
+    alt Authentication Required
+        NetworkProxy->>Client: Request Authentication
+        Client->>NetworkProxy: Send Credentials
+        NetworkProxy->>NetworkProxy: Validate Credentials
+    end
+    
+    NetworkProxy->>Backend: Forward Request
+    Backend->>NetworkProxy: Response
+    
+    Note over NetworkProxy: Add Default Headers
+    
+    NetworkProxy->>Client: Forward Response
+    
+    alt WebSocket Request
+        Client->>NetworkProxy: Upgrade to WebSocket
+        NetworkProxy->>Backend: Upgrade to WebSocket
+        loop WebSocket Active
+            Client->>NetworkProxy: WebSocket Message
+            NetworkProxy->>Backend: Forward Message
+            Backend->>NetworkProxy: WebSocket Message
+            NetworkProxy->>Client: Forward Message
+            NetworkProxy-->>NetworkProxy: Heartbeat Check
+        end
+    end
+```
+
+### Port Proxy with SNI-based Routing
+This diagram illustrates how TCP connections with SNI (Server Name Indication) are processed and forwarded:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant PortProxy
+    participant Backend
+    
+    Client->>PortProxy: TLS Connection
+    
+    alt SNI Enabled
+        PortProxy->>Client: Accept Connection
+        Client->>PortProxy: TLS ClientHello with SNI
+        PortProxy->>PortProxy: Extract SNI Hostname
+        PortProxy->>PortProxy: Match Domain Config
+        PortProxy->>PortProxy: Validate Client IP
+        
+        alt IP Allowed
+            PortProxy->>Backend: Forward Connection
+            Note over PortProxy,Backend: Bidirectional Data Flow
+        else IP Rejected
+            PortProxy->>Client: Close Connection
+        end
+    else Port-based Routing
+        PortProxy->>PortProxy: Match Port Range
+        PortProxy->>PortProxy: Find Domain Config
+        PortProxy->>PortProxy: Validate Client IP
+        
+        alt IP Allowed
+            PortProxy->>Backend: Forward Connection
+            Note over PortProxy,Backend: Bidirectional Data Flow
+        else IP Rejected
+            PortProxy->>Client: Close Connection
+        end
+    end
+    
+    loop Connection Active
+        PortProxy-->>PortProxy: Monitor Activity
+        PortProxy-->>PortProxy: Check Max Lifetime
+        alt Inactivity or Max Lifetime Exceeded
+            PortProxy->>Client: Close Connection
+            PortProxy->>Backend: Close Connection
+        end
+    end
+```
+
+### Let's Encrypt Certificate Acquisition
+This diagram shows how certificates are automatically acquired through the ACME protocol:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Port80Handler
+    participant ACME as Let's Encrypt ACME
+    participant NetworkProxy
+    
+    Client->>Port80Handler: HTTP Request for domain
+    
+    alt Certificate Exists
+        Port80Handler->>Client: Redirect to HTTPS
+    else No Certificate
+        Port80Handler->>Port80Handler: Mark domain as obtaining cert
+        Port80Handler->>ACME: Create account & new order
+        ACME->>Port80Handler: Challenge information
+        
+        Port80Handler->>Port80Handler: Store challenge token & key authorization
+        
+        ACME->>Port80Handler: HTTP-01 Challenge Request
+        Port80Handler->>ACME: Challenge Response
+        
+        ACME->>ACME: Validate domain ownership
+        ACME->>Port80Handler: Challenge validated
+        
+        Port80Handler->>Port80Handler: Generate CSR
+        Port80Handler->>ACME: Submit CSR
+        ACME->>Port80Handler: Issue Certificate
+        
+        Port80Handler->>Port80Handler: Store certificate & private key
+        Port80Handler->>Port80Handler: Mark certificate as obtained
+        
+        Note over Port80Handler,NetworkProxy: Certificate available for use
+        
+        Client->>Port80Handler: Another HTTP Request
+        Port80Handler->>Client: Redirect to HTTPS
+        Client->>NetworkProxy: HTTPS Request
+        Note over NetworkProxy: Uses new certificate
+    end
+```
+
 ## Features
 
 - **HTTPS Reverse Proxy** - Route traffic to backend services based on hostname with TLS termination