diff --git a/README.md b/README.md
index caed786..8391a0d 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,18 @@ hugo server
Then visit [http://localhost:1313](http://localhost:1313).
+## Updating diagrams
+
+Diagrams are located under [/static/css/img/diagrams/](https://github.com/actix/actix-website/tree/master/static/img/diagrams) and built with [Mermaid CLI](https://github.com/mermaidjs/mermaid.cli).
+
+For instance to edit `connection_overview` diagram:
+```sh
+cd static/css/img/diagrams
+vi connection_overview.mmd
+# Compile diagrams:
+mmdc -i connection_overview.mmd -o connection_overview.svg
+```
+
# License
Pretty murky. Right now a massive clone of the tokio website. Will get this
diff --git a/content/docs/conn_lifecycle.md b/content/docs/conn_lifecycle.md
new file mode 100644
index 0000000..6675111
--- /dev/null
+++ b/content/docs/conn_lifecycle.md
@@ -0,0 +1,42 @@
+---
+title: Connection Lifecycle
+menu: docs_architecture
+weight: 20
+---
+
+
+# Architecture overview
+
+After Server has started listening to all sockets, [`Accept`][Accept] and [`Worker`][Worker] are two main loops responsible for processing incoming client connections.
+
+Once connection accepted Application level protocol processing happens in a protocol specific [`Dispatcher`][Dispatcher] loop spawned from [`Worker`][Worker].
+
+ Please note, below diagrams are outlining happy-path scenarios only.
+
+
+
+## Accept loop in more detail
+
+
+
+Most of code implementation resides in [`actix-server`][server] crate for struct [`Accept`][Accept].
+
+## Worker loop in more detail
+
+
+
+Most of code implementation resides in [`actix-server`][server] crate for struct [`Worker`][Worker].
+
+## Request loop roughly
+
+
+
+Most of code implementation for request loop resides in [`actix-web`][web] and [`actix-http`][http] crates.
+
+
+[server]: https://crates.io/crates/actix-server
+[web]: https://crates.io/crates/actix-web
+[http]: https://crates.io/crates/actix-http
+[Accept]: https://github.com/actix/actix-net/blob/master/actix-server/src/accept.rs
+[Worker]: https://github.com/actix/actix-net/blob/master/actix-server/src/worker.rs
+[Dispatcher]: https://github.com/actix/actix-web/blob/master/actix-http/src/h1/dispatcher.rs
\ No newline at end of file
diff --git a/content/docs/http_server_init.md b/content/docs/http_server_init.md
new file mode 100644
index 0000000..2f3cb4b
--- /dev/null
+++ b/content/docs/http_server_init.md
@@ -0,0 +1,23 @@
+---
+title: Http Server Initialization
+menu: docs_architecture
+weight: 10
+---
+
+## Architecture overview
+
+Below is a diagram of HttpServer initalization, which happens on the following code
+```rust
+#[actix_rt::main]
+async fn main() -> std::io::Result<()> {
+ HttpServer::new(|| {
+ App::new()
+ .route("/", web::to(|| HttpResponse::Ok()))
+ })
+ .bind("127.0.0.1:8088")?
+ .run()
+ .await
+}
+```
+
+
diff --git a/layouts/docs/baseof.html b/layouts/docs/baseof.html
index 626433b..9f3960c 100644
--- a/layouts/docs/baseof.html
+++ b/layouts/docs/baseof.html
@@ -75,6 +75,17 @@
+ Diagrams
+
+
+ {{ range .Site.Menus.docs_architecture }}
+
+ {{ .Name }}
+
+ {{ end }}
+
+
API Documentation
diff --git a/static/img/diagrams/connection_accept.mmd b/static/img/diagrams/connection_accept.mmd
new file mode 100644
index 0000000..d6c8031
--- /dev/null
+++ b/static/img/diagrams/connection_accept.mmd
@@ -0,0 +1,28 @@
+sequenceDiagram
+
+participant ServerBuilder
+participant mio
+participant Accept
+participant WorkerClient
+
+
+ServerBuilder->>Accept: start(socks, workers)
+loop Continuous: poll
+ Accept->>mio: mio::Poll::poll()
+ alt poll() -> TIMER | CMD
+ Accept-->>Accept: process_*
+ else poll() -> NOTIFY
+ Accept->>Accept: backpressure
+ else poll() -> OTHER(token)
+ Accept-->>Accept: accept_one(Conn)
+ loop while exist WorkerClient
+ Accept->>WorkerClient: send(Conn)
+ alt send(Conn) -> Ok(_)
+ Note over Accept: break loop
+ else send(Conn) -> Err(_)
+ Accept->>ServerBuilder: worker_faulted(idx)
+ Accept->>Accept: remove worker, get next worker
+ end
+ end
+ end
+end
diff --git a/static/img/diagrams/connection_accept.svg b/static/img/diagrams/connection_accept.svg
new file mode 100644
index 0000000..9b17bb1
--- /dev/null
+++ b/static/img/diagrams/connection_accept.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/static/img/diagrams/connection_overview.mmd b/static/img/diagrams/connection_overview.mmd
new file mode 100644
index 0000000..e8a1394
--- /dev/null
+++ b/static/img/diagrams/connection_overview.mmd
@@ -0,0 +1,34 @@
+sequenceDiagram
+
+participant ServerBuilder
+participant Accept
+participant WorkerClient
+participant Worker
+participant Dispatcher
+
+ServerBuilder->>Accept: start(socks, workers)
+
+Note over Accept: accept Connections
+loop poll connections on sockets
+ activate Accept
+ Accept-->>Accept: poll() --> Conn
+ Note over Accept: backpressure logic
+ Accept->>WorkerClient: send(Conn)
+end
+deactivate Accept
+
+Note over Worker: process Connections
+loop Worker as Future::poll
+ activate Worker
+ Worker->>WorkerClient: rx.poll_next()
+ Note over Worker: Service factories
+ Worker-->>Dispatcher: new(stream)
+end
+deactivate Worker
+
+Note over Dispatcher: process Requests
+loop Dispatcher::poll
+ activate Dispatcher
+ Dispatcher-->>Dispatcher: Dispatch requests
+end
+deactivate Dispatcher
diff --git a/static/img/diagrams/connection_overview.svg b/static/img/diagrams/connection_overview.svg
new file mode 100644
index 0000000..68f26b8
--- /dev/null
+++ b/static/img/diagrams/connection_overview.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/static/img/diagrams/connection_request.mmd b/static/img/diagrams/connection_request.mmd
new file mode 100644
index 0000000..5e2e850
--- /dev/null
+++ b/static/img/diagrams/connection_request.mmd
@@ -0,0 +1,29 @@
+sequenceDiagram
+
+participant HttpServer
+participant HttpServiceHandler
+participant HSHR
+participant State
+participant Dispatcher
+participant Tokio
+
+Note over HSHR, State: HttpServiceHandlerResponse
+
+HttpServer-->>HttpServiceHandler: eventually build...
+alt Protocol::HTTP1
+HttpServiceHandler->>Dispatcher: H1::Dispatcher::new()
+HttpServiceHandler->>State: State::H1(Dispatcher)
+else Protocol::HTTP2
+HttpServiceHandler->>State: State::H2Handshake
+end
+HttpServiceHandler->>HSHR: HttpServiceHandlerResponse::new(State)
+HttpServiceHandler-->>Tokio: StreamService->Tokio::spawn(HttpServiceHandlerResponse as Future)
+
+Tokio->>HSHR: poll()
+alt State::H2Handshake
+HSHR->>Dispatcher: H2::Dispatcher::new(stream,services)
+HSHR->>HSHR: poll()
+else
+HSHR->>Dispatcher: poll()
+end
+Note over Dispatcher: requests loop
diff --git a/static/img/diagrams/connection_request.svg b/static/img/diagrams/connection_request.svg
new file mode 100644
index 0000000..8d78394
--- /dev/null
+++ b/static/img/diagrams/connection_request.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/static/img/diagrams/connection_worker.mmd b/static/img/diagrams/connection_worker.mmd
new file mode 100644
index 0000000..36cce9f
--- /dev/null
+++ b/static/img/diagrams/connection_worker.mmd
@@ -0,0 +1,34 @@
+sequenceDiagram
+
+participant ServerBuilder
+participant WorkerClient
+participant Worker
+participant StreamService
+participant HttpServiceHandler
+participant Tokio
+
+ServerBuilder-->>Tokio: spawn(Worker)
+
+Tokio-->>Worker: poll()
+alt WorkerState::Available
+ loop
+ Worker->>WorkerClient: rx.poll_next()
+ WorkerClient->>Worker: WorkerCommand(Conn)
+ Worker->>Worker: check_readiness()
+ alt check_readiness() -> Ok(true)
+ Note over Worker,StreamService: Worker::services[Conn.token]
+ Worker-->>StreamService: call(ServerMessage::Connect(stream))
+ StreamService->>HttpServiceHandler: call(stream)
+ HttpServiceHandler->>StreamService: HttpServiceHandlerResponse as Future
+ StreamService->>Tokio: spawn(HttpServiceHandlerResponse)
+
+ else check_readiness() -> Ok(false)
+ Worker-->>Worker: WorkerState::Unavailable
+ else check_readiness() -> Err(token,idx)
+ Worker-->>Worker: WorkerState::Restarting
+ end
+ end
+end
+
+
+Note over HttpServiceHandler: process connection
diff --git a/static/img/diagrams/connection_worker.svg b/static/img/diagrams/connection_worker.svg
new file mode 100644
index 0000000..10235d5
--- /dev/null
+++ b/static/img/diagrams/connection_worker.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file
diff --git a/static/img/diagrams/http_server.mmd b/static/img/diagrams/http_server.mmd
new file mode 100644
index 0000000..e4e8d48
--- /dev/null
+++ b/static/img/diagrams/http_server.mmd
@@ -0,0 +1,32 @@
+sequenceDiagram
+
+participant HttpServer
+participant ServerBuilder
+participant Worker
+participant StreamNewService
+participant HttpService
+participant HttpServiceResponse
+participant Tokio
+
+
+HttpServer-->>HttpService: build...
+HttpServer->>ServerBuilder: listen(addr,Fn->HttpService)
+ServerBuilder->>StreamNewService: create(addr,Fn->HttpService)
+HttpServer->>ServerBuilder: start()
+ServerBuilder->>Worker: start(StreamNewService)
+
+Worker->>StreamNewService: InternalServiceFactory::create()
+StreamNewService->>HttpService: new_service()
+HttpService->>HttpServiceResponse: HttpServiceResponse::new()
+HttpService->>StreamNewService: HttpServiceResponse as Future
+StreamNewService->>Worker: StreamService(HttpServiceResponse) as Future
+Worker-->>Tokio: spawn(StreamService(HttpServiceResponse)).map(Worker))
+Tokio-->>HttpServiceResponse: poll()
+HttpServiceResponse-->>Tokio: Ready(Worker(HttpServiceHandler))
+
+loop Worker process messages
+ Tokio-->>Worker: poll->Pending...
+ activate Worker
+ Note over Worker: pull messages
+ deactivate Worker
+end
diff --git a/static/img/diagrams/http_server.svg b/static/img/diagrams/http_server.svg
new file mode 100644
index 0000000..5427fef
--- /dev/null
+++ b/static/img/diagrams/http_server.svg
@@ -0,0 +1,4 @@
+
\ No newline at end of file