You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iggy.apache.org by pi...@apache.org on 2026/03/19 21:33:30 UTC

(iggy-website) branch main updated: Refactor landing and docs

This is an automated email from the ASF dual-hosted git repository.

piotr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iggy-website.git


The following commit(s) were added to refs/heads/main by this push:
     new 84f1c127 Refactor landing and docs
84f1c127 is described below

commit 84f1c1275040fd516898a486f48d8913035549b9
Author: spetz <pi...@gmail.com>
AuthorDate: Thu Mar 19 22:33:23 2026 +0100

    Refactor landing and docs
---
 content/blog/release-0.6.0.mdx                |    2 +-
 content/blog/release-0.7.0.mdx                |    2 +-
 content/docs/ai/mcp.mdx                       |  129 ++-
 content/docs/cli/start.mdx                    |  207 +++-
 content/docs/clustering/meta.json             |    1 +
 content/docs/clustering/vsr.mdx               |  136 +++
 content/docs/connectors/introduction.mdx      |   44 +-
 content/docs/connectors/sinks/meta.json       |    2 +-
 content/docs/connectors/sinks/mongodb.mdx     |   70 ++
 content/docs/connectors/sinks/sink.mdx        |    2 +-
 content/docs/connectors/sinks/stdout.mdx      |   34 +
 content/docs/connectors/sources/meta.json     |    2 +-
 content/docs/connectors/sources/postgres.mdx  |    2 +-
 content/docs/connectors/sources/random.mdx    |   39 +
 content/docs/faq/faq.mdx                      |   38 +-
 content/docs/index.mdx                        |   40 +-
 content/docs/introduction/about.mdx           |   59 +-
 content/docs/introduction/architecture.mdx    |  160 +++-
 content/docs/introduction/getting-started.mdx |  121 +--
 content/docs/meta.json                        |    5 +-
 content/docs/sdk/cpp/intro.mdx                |   57 ++
 content/docs/sdk/cpp/meta.json                |    1 +
 content/docs/sdk/csharp/examples.mdx          |   47 +
 content/docs/sdk/csharp/intro.mdx             |   90 +-
 content/docs/sdk/go/examples.mdx              |  126 +++
 content/docs/sdk/go/intro.mdx                 |   60 +-
 content/docs/sdk/introduction.mdx             |  107 ++-
 content/docs/sdk/java/intro.mdx               |  114 ++-
 content/docs/sdk/meta.json                    |    2 +-
 content/docs/sdk/node/intro.mdx               |   98 +-
 content/docs/sdk/python/intro.mdx             |   73 +-
 content/docs/sdk/rust/intro.mdx               |  110 ++-
 content/docs/server/configuration.mdx         |   66 +-
 content/docs/server/docker.mdx                |   94 +-
 content/docs/server/introduction.mdx          |    4 +-
 content/docs/server/meta.json                 |    2 +-
 content/docs/server/networking.mdx            |  139 +++
 content/docs/server/schema.mdx                |  774 ++++++++++-----
 content/docs/server/security.mdx              |  192 ++++
 content/docs/server/storage-engine.mdx        |  188 ++++
 content/docs/web_ui/start.mdx                 |   48 +-
 package-lock.json                             |    7 +
 package.json                                  |    1 +
 src/app/(home)/page.tsx                       |  190 +++-
 src/app/error.tsx                             |   20 +
 src/app/global.css                            |   65 ++
 src/components/architecture-diagrams.tsx      | 1262 +++++++++++++++++++++++++
 src/components/benchmark-chart.tsx            |  151 +++
 src/components/code-tabs.tsx                  |  267 ++++++
 src/mdx-components.tsx                        |   32 +
 50 files changed, 5038 insertions(+), 444 deletions(-)

diff --git a/content/blog/release-0.6.0.mdx b/content/blog/release-0.6.0.mdx
index 5c32d44f..56576bab 100644
--- a/content/blog/release-0.6.0.mdx
+++ b/content/blog/release-0.6.0.mdx
@@ -43,7 +43,7 @@ All SDKs received significant updates:
 
 - [Rust](https://crates.io/crates/iggy) - builder pattern for client, unified TransportProtocol enum, cluster metadata support
 - [C#](https://www.nuget.org/packages/Apache.Iggy/) - high-level IggyPublisher/IggyConsumer clients, TCP reconnection, TLS support, AES encryption
-- [Java](https://mvnrepository.com/artifact/org.apache.iggy/iggy-java-sdk) - complete async API using Netty with CompletableFutures, TLS TCP support, fixed memory leak for sync client
+- [Java](https://mvnrepository.com/artifact/org.apache.iggy/iggy) - complete async API using Netty with CompletableFutures, TLS TCP support, fixed memory leak for sync client
 - [Python](https://pypi.org/project/apache-iggy/) - connection string support, bytes data, typing stubs, musllinux wheels
 - [Node.js (TypeScript)](https://www.npmjs.com/package/apache-iggy) - virtual commands (ensureStream, ensureTopic), cluster metadata, added examples
 - [Go](https://pkg.go.dev/github.com/apache/iggy/foreign/go) - DeleteConsumerOffset, improved error handling and deserialization
diff --git a/content/blog/release-0.7.0.mdx b/content/blog/release-0.7.0.mdx
index 9b539d61..24738875 100644
--- a/content/blog/release-0.7.0.mdx
+++ b/content/blog/release-0.7.0.mdx
@@ -97,7 +97,7 @@ All SDKs now have **auto-publishing** enabled — edge and RC versions are autom
 
 - [Rust](https://crates.io/crates/iggy) — improved high-level producer/consumer with ordered sharding, graceful `shutdown()`, and message loss prevention; fixed `max_in_flight` permit acquisition and client reconnection after disconnect
 - [C#](https://www.nuget.org/packages/Apache.Iggy/) — .NET 10 support, `DeleteSegments` and `GetSnapshot` methods, `TimeSpan`-based expiry handling, source link for debugging
-- [Java](https://mvnrepository.com/artifact/org.apache.iggy/iggy-java-sdk) — fluent builder API (`Iggy.tcpClientBuilder().blocking()`), semantic exception hierarchy, BDD tests with Cucumber, user headers support, TLS for HTTP, memory leak detection in CI
+- [Java](https://mvnrepository.com/artifact/org.apache.iggy/iggy) — fluent builder API (`Iggy.tcpClientBuilder().blocking()`), semantic exception hierarchy, BDD tests with Cucumber, user headers support, TLS for HTTP, memory leak detection in CI
 - [Python](https://pypi.org/project/apache-iggy/) — `AsyncIterator` interface for `IggyConsumer`, `message_expiry` parameter in `create_topic`, Windows build support
 - [Node.js (TypeScript)](https://www.npmjs.com/package/apache-iggy) — comprehensive JSDoc comments for improved API documentation and IDE support
 - [Go](https://pkg.go.dev/github.com/apache/iggy/foreign/go) — leader redirection for cluster failover handling
diff --git a/content/docs/ai/mcp.mdx b/content/docs/ai/mcp.mdx
index 361eca3c..ed8c4f2e 100644
--- a/content/docs/ai/mcp.mdx
+++ b/content/docs/ai/mcp.mdx
@@ -2,12 +2,16 @@
 title: MCP Server
 ---
 
-The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that standardizes how applications provide context to LLMs. The Apache Iggy MCP Server is an implementation of the MCP protocol for the message streaming infrastructure.
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that standardizes how applications provide context to LLMs. The Apache Iggy MCP Server is an implementation of the MCP protocol for the message streaming infrastructure. It is built using the `rmcp` crate and supports both **stdio** and **HTTP** transports.
+
+## Getting started
 
 To start the MCP server, simply run `cargo run --bin iggy-mcp`.
 
 The [docker image](https://hub.docker.com/r/apache/iggy-mcp) is available, and can be fetched via `docker pull apache/iggy-mcp`.
 
+## Configuration
+
 The minimal viable configuration requires at least the Iggy credentials, to create the connection with the running Iggy server using TCP with which the MCP server will communicate. You can choose between HTTP and STDIO transports (e.g. for the local usage with tools such as [Claude Desktop](https://claude.ai/download) choose `stdio`).
 
 ```toml
@@ -20,6 +24,11 @@ password = "iggy"
 # token = "secret" # Personal Access Token (PAT) can be used instead of username and password
 # consumer = "iggy-mcp" # Optional consumer name
 
+# TLS settings for connecting to Iggy server
+# [iggy.tls]
+# enabled = false
+# cert_file = "path/to/cert.pem"
+
 [http] # Optional HTTP API configuration
 address = "127.0.0.1:8082"
 path = "/mcp"
@@ -43,10 +52,115 @@ create = true
 read = true
 update = true
 delete = true
+
+[telemetry] # Optional OpenTelemetry integration
+enabled = false
+service_name = "iggy-mcp"
 ```
 
 Keep in mind that either of `toml`, `yaml`, or `json` formats are supported for the configuration file. The path to the configuration can be overriden by `IGGY_MCP_CONFIG_PATH` environment variable. Each configuration section can be also additionally updated by using the following convention `IGGY_MCP_SECTION_NAME.KEY_NAME` e.g. `IGGY_MCP_IGGY_USERNAME` and so on.
 
+## Available tools
+
+The MCP server exposes 40+ tools covering the full Iggy API:
+
+### Server
+
+| Tool | Description |
+|------|-------------|
+| `ping` | Health check |
+| `get_stats` | Server statistics (streams, topics, partitions, OS info) |
+| `get_me` | Current client info |
+| `get_client` | Get specific client details |
+| `get_clients` | List all connected clients |
+| `get_cluster_metadata` | Cluster information |
+| `snapshot` | Collect troubleshooting data |
+
+### Streams
+
+| Tool | Description |
+|------|-------------|
+| `get_streams` | List all streams |
+| `get_stream` | Get stream details |
+| `create_stream` | Create a new stream |
+| `update_stream` | Update stream name |
+| `delete_stream` | Delete a stream |
+| `purge_stream` | Purge all messages from a stream |
+
+### Topics
+
+| Tool | Description |
+|------|-------------|
+| `get_topics` | List topics in a stream |
+| `get_topic` | Get topic details |
+| `create_topic` | Create a new topic |
+| `update_topic` | Update topic settings |
+| `delete_topic` | Delete a topic |
+| `purge_topic` | Purge all messages from a topic |
+
+### Partitions & Segments
+
+| Tool | Description |
+|------|-------------|
+| `create_partitions` | Add partitions to a topic |
+| `delete_partitions` | Remove partitions from a topic |
+| `delete_segments` | Delete segments from a partition |
+
+### Messages
+
+| Tool | Description |
+|------|-------------|
+| `send_messages` | Send messages (partitioning: balanced, key, partition) |
+| `poll_messages` | Poll messages (strategies: offset, first, last, next, timestamp) |
+
+### Consumer Groups
+
+| Tool | Description |
+|------|-------------|
+| `get_consumer_groups` | List consumer groups |
+| `get_consumer_group` | Get consumer group details |
+| `create_consumer_group` | Create a consumer group |
+| `delete_consumer_group` | Delete a consumer group |
+
+### Consumer Offsets
+
+| Tool | Description |
+|------|-------------|
+| `get_consumer_offset` | Get stored consumer offset |
+| `store_consumer_offset` | Store consumer offset |
+| `delete_consumer_offset` | Delete consumer offset |
+
+### Users & Access Tokens
+
+| Tool | Description |
+|------|-------------|
+| `get_users` | List users |
+| `get_user` | Get user details |
+| `create_user` | Create a user |
+| `update_user` | Update user details |
+| `delete_user` | Delete a user |
+| `update_permissions` | Update user permissions |
+| `change_password` | Change user password |
+| `get_personal_access_tokens` | List PATs |
+| `create_personal_access_token` | Create a PAT |
+| `delete_personal_access_token` | Delete a PAT |
+
+## Permissions
+
+The `[permissions]` section provides a first layer of access control, checked before any request is forwarded to the Iggy server. This lets you restrict the MCP server to read-only operations, for example:
+
+```toml
+[permissions]
+create = false
+read = true
+update = false
+delete = false
+```
+
+On top of this, the Iggy user account used by the MCP server has its own granular permissions. For production use, create a dedicated user with the minimum required permissions.
+
+## Claude Desktop integration
+
 Here's the example configuration to be used with Claude Desktop:
 
 ```json
@@ -63,4 +177,15 @@ Here's the example configuration to be used with Claude Desktop:
 }
 ```
 
-**Remember to use the appropriate Iggy account credentials for your environment** (e.g. create the user with read-only permissions to avoid modifying the data). On top of this, you can also configure the `permissions` for the MCP server to control which operations are allowed (this will be checked first, before forwarding the actual request to the Iggy server).
+## Docker
+
+Run the MCP server as a container:
+
+```bash
+docker run -e IGGY_MCP_TRANSPORT=http \
+  -e IGGY_MCP_IGGY_ADDRESS=iggy-server:8090 \
+  -e IGGY_MCP_IGGY_USERNAME=iggy \
+  -e IGGY_MCP_IGGY_PASSWORD=iggy \
+  -p 8082:8082 \
+  apache/iggy-mcp
+```
diff --git a/content/docs/cli/start.mdx b/content/docs/cli/start.mdx
index e67735a8..0f2d8890 100644
--- a/content/docs/cli/start.mdx
+++ b/content/docs/cli/start.mdx
@@ -16,49 +16,226 @@ Then, you can simply invoke the `iggy` command to see the available options and
 
 ![CLI](/img/iggy_cli.png)
 
-For example, you can use the following commands to list all the available streams given the server is running on the default address:
+## Global options
 
-```bash
-iggy --username iggy --password iggy stream list
-```
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--username` | `-u` | Username for authentication |
+| `--password` | `-p` | Password for authentication |
+| `--token` | `-t` | Personal Access Token |
+| `--token-name` | `-n` | Token name from keyring |
+| `--transport` | | Transport protocol (`tcp`, `quic`, `http`, `websocket`) |
+| `--tcp-server-address` | | TCP server address (default: `localhost:8090`) |
+| `--quiet` | `-q` | Suppress output |
+| `--debug` | `-d` | Enable debug logging to file |
+| `--generate` | | Generate shell completions (bash, zsh, fish, elvish, powershell) |
+
+## Commands
 
-or with the short syntax:
+### Stream management
 
 ```bash
+# List all streams
 iggy -u iggy -p iggy stream list
+
+# Create a stream
+iggy -u iggy -p iggy stream create my-stream
+
+# Get stream details
+iggy -u iggy -p iggy stream get my-stream
+
+# Update a stream name
+iggy -u iggy -p iggy stream update my-stream new-name
+
+# Delete a stream
+iggy -u iggy -p iggy stream delete my-stream
+
+# Purge all messages from a stream
+iggy -u iggy -p iggy stream purge my-stream
 ```
 
-To create a new stream with the specific TCP transport and server address, you can use the following command:
+Alias: `s` (e.g. `iggy -u iggy -p iggy s list`)
+
+### Topic management
 
 ```bash
-iggy --transport tcp --tcp-server-address localhost:8090 -u iggy -p secret stream create my-stream
+# List topics in a stream
+iggy -u iggy -p iggy topic list my-stream
+
+# Create a topic with 2 partitions, no compression, 7 day retention
+iggy -u iggy -p iggy topic create my-stream my-topic 2 none 7d
+
+# Get topic details
+iggy -u iggy -p iggy topic get my-stream my-topic
+
+# Update a topic
+iggy -u iggy -p iggy topic update my-stream my-topic new-name
+
+# Delete a topic
+iggy -u iggy -p iggy topic delete my-stream my-topic
+
+# Purge all messages from a topic
+iggy -u iggy -p iggy topic purge my-stream my-topic
 ```
 
-To create a new topic within the stream with the specific partition count and retention policy, you can use the following command:
+Alias: `t`
+
+### Partition management
 
 ```bash
-iggy -u iggy -p secret topic create my-stream my-topic 1 none 7d
+# Create 2 additional partitions
+iggy -u iggy -p iggy partition create my-stream my-topic 2
+
+# Delete partitions
+iggy -u iggy -p iggy partition delete my-stream my-topic 2
 ```
 
-To send a raw string message to the specific partition of the topic, you can use the following command:
+Alias: `p`
+
+### Message operations
 
 ```bash
+# Send a message to a specific partition
 iggy -u iggy -p iggy message send --partition-id 1 my-stream my-topic "hello world"
+
+# Poll messages from partition 1, starting at offset 0
+iggy -u iggy -p iggy message poll --offset 0 --message-count 10 my-stream my-topic 1
+
+# Poll with auto-commit
+iggy -u iggy -p iggy message poll --offset 0 --message-count 10 --auto-commit my-stream my-topic 1
 ```
 
-To fetch the messages from the specific partition of the topic, you can use the following command:
+Alias: `m`
+
+### User management
 
 ```bash
-iggy -u iggy -p iggy message poll --offset 0 --message-count 10 my-stream my-topic 1
+# List users
+iggy -u iggy -p iggy user list
+
+# Create a user
+iggy -u iggy -p iggy user create new-user password123
+
+# Get user details
+iggy -u iggy -p iggy user get new-user
+
+# Change password
+iggy -u iggy -p iggy user change-password new-user old-pass new-pass
+
+# Delete a user
+iggy -u iggy -p iggy user delete new-user
 ```
 
-You could also login with the specific user and password for the given duration and invoke the subsequent requests.
-**Please keep in mind that this mode is only supported on Linux systems.**
+Alias: `u`
+
+### Consumer group management
 
 ```bash
-iggy -u iggy -p secret login 1h
+# List consumer groups for a topic
+iggy -u iggy -p iggy consumer-group list my-stream my-topic
+
+# Create a consumer group
+iggy -u iggy -p iggy consumer-group create my-stream my-topic my-group
+
+# Get consumer group details
+iggy -u iggy -p iggy consumer-group get my-stream my-topic my-group
+
+# Delete a consumer group
+iggy -u iggy -p iggy consumer-group delete my-stream my-topic my-group
+```
+
+Alias: `g`
+
+### Consumer offset management
+
+```bash
+# Get consumer offset
+iggy -u iggy -p iggy consumer-offset get my-consumer my-stream my-topic 1
+
+# Set consumer offset
+iggy -u iggy -p iggy consumer-offset set my-consumer my-stream my-topic 1 100
 ```
 
+Alias: `o`
+
+### Personal Access Tokens
+
+```bash
+# List tokens
+iggy -u iggy -p iggy pat list
+
+# Create a token with 7 day expiry
+iggy -u iggy -p iggy pat create my-token 7d
+
+# Delete a token
+iggy -u iggy -p iggy pat delete my-token
+```
+
+### Cluster operations
+
 ```bash
+# Get cluster info
+iggy -u iggy -p iggy cluster list
+```
+
+Alias: `cl`
+
+### Server operations
+
+```bash
+# Ping the server (health check with latency)
+iggy -u iggy -p iggy ping
+
+# Get current client info
+iggy -u iggy -p iggy me
+
+# Get server statistics
+iggy -u iggy -p iggy stats
+
+# Get client list
+iggy -u iggy -p iggy client list
+
+# Create a troubleshooting snapshot
+iggy -u iggy -p iggy snapshot
+```
+
+## Connection contexts
+
+The CLI supports named connection contexts (profiles) for managing multiple server connections. This is useful when you work with different Iggy environments (dev, staging, production).
+
+```bash
+# Create/switch to a named context
+iggy context set production --tcp-server-address prod-server:8090 -u admin -p secret
+
+# List contexts
+iggy context list
+
+# Use a specific context
+iggy --context production stream list
+```
+
+## Login sessions (Linux only)
+
+On Linux, you can log in for a specific duration and avoid passing credentials with every command:
+
+```bash
+# Login for 1 hour
+iggy -u iggy -p secret login 1h
+
+# Subsequent commands don't need credentials
 iggy stream list
+iggy topic create my-stream my-topic 2 none 7d
+
+# Logout
+iggy logout
+```
+
+## Shell completions
+
+Generate shell completions for your preferred shell:
+
+```bash
+iggy --generate bash > /etc/bash_completion.d/iggy
+iggy --generate zsh > ~/.zfunc/_iggy
+iggy --generate fish > ~/.config/fish/completions/iggy.fish
 ```
diff --git a/content/docs/clustering/meta.json b/content/docs/clustering/meta.json
new file mode 100644
index 00000000..20f5b735
--- /dev/null
+++ b/content/docs/clustering/meta.json
@@ -0,0 +1 @@
+{"title": "Clustering", "pages": ["vsr"]}
diff --git a/content/docs/clustering/vsr.mdx b/content/docs/clustering/vsr.mdx
new file mode 100644
index 00000000..4cc33e1a
--- /dev/null
+++ b/content/docs/clustering/vsr.mdx
@@ -0,0 +1,136 @@
+---
+title: Viewstamped Replication
+---
+
+Iggy is building clustering support based on **Viewstamped Replication (VSR)**, a consensus protocol for state machine replication. You can read the original [Viewstamped Replication Revisited](https://sands.kaust.edu.sa/classes/CS240/F21/papers/vr-revisited.pdf) paper for the full protocol specification. This work is actively in progress and represents a major milestone for production readiness. The building blocks are already implemented in the `core/consensus/` crate.
+
+## What is Viewstamped Replication?
+
+VSR is a consensus protocol (similar in purpose to Raft or Paxos) that ensures a group of replicas agree on the same sequence of operations, even in the presence of failures. It was chosen for Iggy because of its simplicity and proven track record in high-performance distributed systems.
+
+The protocol operates in three main phases:
+
+1. **Normal operation** - the primary (leader) receives client requests, assigns them sequence numbers, replicates them to backups, and commits once a quorum acknowledges
+2. **View change** - if the primary fails, the remaining replicas elect a new primary by transitioning to a higher view number
+3. **Recovering** - a replica that fell behind can catch up by receiving a snapshot and replay log from the primary
+
+## Architecture
+
+The VSR implementation in Iggy is split into two planes, each handling different types of operations:
+
+The VSR implementation splits replicated operations into two planes:
+
+**Control Plane** (routed through shard 0):
+- Stream operations: CreateStream, UpdateStream, DeleteStream, PurgeStream
+- Topic operations: CreateTopic, UpdateTopic, DeleteTopic, PurgeTopic
+- User operations: CreateUser, UpdateUser, DeleteUser, ChangePassword, UpdatePermissions
+- Other: CreatePartitions, DeletePartitions, CreateConsumerGroup, DeleteConsumerGroup, CreatePersonalAccessToken, DeletePersonalAccessToken
+
+**Data Plane** (routed to owning shard):
+- SendMessages, StoreConsumerOffset, DeleteSegments
+
+- **Control Plane (`IggyMetadata`)** - metadata operations replicated through shard 0. These include creating/deleting streams, topics, partitions, users, consumer groups, and managing permissions and access tokens.
+- **Data Plane (`IggyPartitions`)** - partition operations replicated on all shards via namespaced pipelines. These include sending messages and storing consumer offsets.
+
+## Core concepts
+
+### Replica state
+
+Each replica tracks the following state:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `replica_id` | u8 | Unique identifier for this replica |
+| `view` | u32 | Current view number (incremented on leader change) |
+| `log_view` | u32 | View when status was last normal |
+| `op` | u64 | Operation counter (monotonically increasing) |
+| `commit` | u64 | Latest committed operation number |
+| `status` | enum | Normal, ViewChange, or Recovering |
+
+### Message types
+
+The consensus protocol uses the following message types:
+
+| Message | Direction | Purpose |
+|---------|-----------|---------|
+| `Ping` / `Pong` | Bidirectional | Health checking between replicas |
+| `PingClient` / `PongClient` | Bidirectional | Health checking between client and replica |
+| `Request` | Client -> Primary | Client submitting an operation |
+| `Prepare` | Primary -> Backups | Replicate operation to backups |
+| `PrepareOk` | Backup -> Primary | Acknowledge replication |
+| `Reply` | Primary -> Client | Operation result |
+| `Commit` | Primary -> Backups | Confirm operation is committed |
+| `StartViewChange` | Any -> All | Initiate view change |
+| `DoViewChange` | Any -> New Primary | Transfer state for view change |
+| `StartView` | New Primary -> All | Announce new view |
+
+### Consensus header
+
+Each consensus message carries a 256-byte header (`#[repr(C)]`, zero-copy via `bytemuck`):
+
+| Field | Size | Description |
+|-------|------|-------------|
+| checksum | 16 bytes | Message integrity (u128) |
+| checksum_body | 16 bytes | Body integrity (u128) |
+| cluster | 16 bytes | Cluster identifier (u128) |
+| size | 4 bytes | Message size |
+| view | 4 bytes | View number |
+| release | 4 bytes | Software release version |
+| command | 1 byte | Message type |
+| replica | 1 byte | Sender replica ID |
+| reserved | remaining | Reserved for future use |
+
+### Quorum
+
+Operations are committed once a **quorum** of replicas (majority) acknowledges. The quorum is tracked using a `BitSet` per operation, which efficiently tracks which replicas have acknowledged.
+
+## Timeout management
+
+The VSR implementation uses **deterministic tick-based** timeouts (10ms per tick) for all timing-sensitive operations:
+
+| Timeout Type | Default Ticks | Purpose |
+|-------------|---------------|---------|
+| Ping | 100 (1s) | Health check interval |
+| Prepare | 25 (250ms) | Replication timeout |
+| CommitMessage | 50 (500ms) | Commit notification |
+| NormalHeartbeat | 500 (5s) | Leader heartbeat |
+| StartViewChange | 50 (500ms) | View change initiation |
+| ViewChangeStatus | 500 (5s) | View change monitoring |
+| DoViewChange | 50 (500ms) | View change vote |
+| RequestStartView | 100 (1s) | Request new view from primary |
+
+Timeouts support **exponential backoff** with PRNG-based jitter to avoid thundering herd effects during view changes.
+
+## Deterministic simulation testing
+
+The `core/simulator/` crate provides a network simulator for testing the VSR protocol deterministically. It simulates network conditions (delays, drops, partitions) and allows replaying exact scenarios. This includes modules for: bus, client, network, packet, ready queue, and replica simulation.
+
+## Cluster configuration
+
+Clustering is configured in the `[cluster]` section of `config.toml`:
+
+```toml
+[cluster]
+enabled = false
+name = "iggy-cluster"
+
+[cluster.node.current]
+name = "iggy-node-1"
+ip = "127.0.0.1"
+
+[[cluster.node.others]]
+name = "iggy-node-2"
+ip = "192.168.1.101"
+ports = { tcp = 8091, quic = 8081, http = 3001, websocket = 8093 }
+
+[[cluster.node.others]]
+name = "iggy-node-3"
+ip = "192.168.1.102"
+ports = { tcp = 8092, quic = 8082, http = 3002, websocket = 8094 }
+```
+
+All nodes in the same cluster must share the same `name` to prevent accidental cross-cluster communication. Each node's `ports` field is optional and defaults to the current node's configured ports.
+
+## Current status
+
+The VSR implementation includes the core consensus protocol, view change mechanism, deterministic timeout management, quorum tracking, shard-level plane multiplexing, and a network simulator for testing. Clustering is not yet production-ready but the foundational building blocks are in place and being actively developed. The server can be started as a follower node using the `--follower` flag.
diff --git a/content/docs/connectors/introduction.mdx b/content/docs/connectors/introduction.mdx
index 9cc059f0..32d5ba1a 100644
--- a/content/docs/connectors/introduction.mdx
+++ b/content/docs/connectors/introduction.mdx
@@ -6,12 +6,48 @@ The highly performant and modular runtime for statically typed, yet dynamically
 
 The [docker image](https://hub.docker.com/r/apache/iggy-connect) is available, and can be fetched via `docker pull apache/iggy-connect`.
 
+## Architecture
+
+Connectors are dynamically loaded shared libraries (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows) loaded at runtime via `dlopen2`. Data crossing the FFI boundary between the runtime and plugins is serialized using **postcard**, a compact binary format. Each plugin receives its own Tokio runtime inside the SDK, ensuring isolation.
+
+### Data Flow
+
+The connector runtime operates in two directions - **source** (ingest) and **sink** (egress):
+
+<ConnectorPipeline />
+
+**Key details:**
+
+- **Transforms** run inside the runtime process, not inside the plugins. They are applied after decoding for sources (before sending to Iggy) and after consuming from Iggy for sinks (before forwarding to the external system).
+- **State persistence** is file-based (using MessagePack serialization) and applies to source connectors only, tracking the last polled position.
+- **Consumer groups** handle offset tracking for sink connectors automatically, so sinks do not need to manage their own offsets.
+
+### Available Connectors
+
+| Type   | Connectors                                                     |
+|--------|----------------------------------------------------------------|
+| Source | PostgreSQL, Elasticsearch, Random                              |
+| Sink   | PostgreSQL, MongoDB, Elasticsearch, Quickwit, Apache Iceberg, Stdout |
+
+### Transforms
+
+The following built-in transforms are available:
+
+- **add_fields** - add new fields to the message payload.
+- **delete_fields** - remove existing fields from the message payload.
+- **filter_fields** - keep only the specified fields, removing everything else.
+- **update_fields** - update existing fields with computed values such as `timestamp_millis` or `uuid_v7`.
+
+### Supported Schemas
+
+Messages can be decoded and encoded using the following formats: **JSON**, **Raw bytes**, **Text**, **Protocol Buffers**, and **FlatBuffers**.
+
 ## Features
 
 - **High Performance**: Utilizes Rust's performance characteristics to ensure fast data ingestion and egress.
 - **Low memory footprint**: Designed with memory efficiency in mind, minimizing the memory footprint of the connectors.
 - **Modular Design**: Designed with modularity in mind, allowing for easy extension and customization.
-- **Dynamic Loading**: Supports dynamic loading of plugins, enabling seamless integration with various data sources and sinks.
+- **Dynamic Loading**: Supports dynamic loading of plugins, allowing integration with various data sources and sinks at runtime.
 - **Statically Typed**: Ensures type safety and compile-time checks, reducing runtime errors.
 - **Easy Customization**: Provides a simple interface for implementing custom connectors, making it easy to create new plugins.
 - **Data transformation**: Supports data transformation with the help of existing functions.
@@ -61,7 +97,7 @@ All the connectors are implemented as Rust libraries and can be used as a part o
 
 Sinks are responsible for consuming the messages from the configured stream(s) and topic(s) and sending them further to the specified destination. For example, the Quickwit sink connector is responsible for sending the messages to the Quickwit indexer.
 
-Please refer to the **[Sink documentation](/docs/connectors/sink)** for the details about the configuration and the sample implementation.
+Please refer to the **[Sink documentation](/docs/connectors/sinks/sink)** for the details about the configuration and the sample implementation.
 
 When implementing `Sink`, make sure to use the `sink_connector!` macro to expose the FFI interface and allow the connector runtime to register the sink with the runtime.
 Each sink should have its own, custom configuration, which is passed along with the unique plugin ID via expected `new()` method.
@@ -70,11 +106,11 @@ Each sink should have its own, custom configuration, which is passed along with
 
 Sources are responsible for producing the messages to the configured stream(s) and topic(s). For example, the Test source connector will generate the random messages that will be then sent to the configured stream and topic.
 
-Please refer to the **[Source documentation](/docs/connectors/source)** for the details about the configuration and the sample implementation.
+Please refer to the **[Source documentation](/docs/connectors/sources/source)** for the details about the configuration and the sample implementation.
 
 ## Building the connectors
 
-New connector can be built simply by implementing either `Sink` or `Source` trait. Please check the **[sink](/docs/connectors/sink)** or **[source](/docs/connectors/source)** documentation, as well as the existing examples under `/sinks` and `/sources` directories.
+New connector can be built simply by implementing either `Sink` or `Source` trait. Please check the **[sink](/docs/connectors/sinks/sink)** or **[source](/docs/connectors/sources/source)** documentation, as well as the existing examples under `/sinks` and `/sources` directories.
 
 ## Transformations
 
diff --git a/content/docs/connectors/sinks/meta.json b/content/docs/connectors/sinks/meta.json
index 36df9508..0c6164ac 100644
--- a/content/docs/connectors/sinks/meta.json
+++ b/content/docs/connectors/sinks/meta.json
@@ -1 +1 @@
-{"title": "Sinks", "pages": ["sink", "elasticsearch", "postgres", "quickwit", "iceberg"]}
+{"title": "Sinks", "pages": ["sink", "elasticsearch", "postgres", "mongodb", "quickwit", "iceberg", "stdout"]}
diff --git a/content/docs/connectors/sinks/mongodb.mdx b/content/docs/connectors/sinks/mongodb.mdx
new file mode 100644
index 00000000..df17d2d4
--- /dev/null
+++ b/content/docs/connectors/sinks/mongodb.mdx
@@ -0,0 +1,70 @@
+---
+title: MongoDB Sink
+---
+
+The MongoDB sink connector writes messages from Iggy streams to a MongoDB database. Each message is inserted as a document into the configured collection.
+
+## Configuration
+
+```toml
+type = "sink"
+key = "mongodb-sink"
+enabled = true
+version = 1
+name = "MongoDB Sink"
+path = "/path/to/libmongodb_sink.so"
+verbose = false
+
+[[streams]]
+stream = "my-stream"
+topics = ["my-topic"]
+schema = "json"
+batch_length = 100
+poll_interval = "1s"
+consumer_group = "mongodb-sink-group"
+
+[plugin_config]
+connection_uri = "mongodb://localhost:27017"
+database = "my_database"
+collection = "my_collection"
+batch_size = 100
+include_metadata = true
+include_checksum = true
+include_origin_timestamp = true
+payload_format = "json"
+auto_create_collection = true
+verbose_logging = false
+max_retries = 3
+retry_delay = "1s"
+```
+
+## Plugin config options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `connection_uri` | string | required | MongoDB connection string |
+| `database` | string | required | Target database name |
+| `collection` | string | required | Target collection name |
+| `batch_size` | u32 | `100` | Number of documents to insert per batch |
+| `include_metadata` | bool | `true` | Include message metadata (offset, timestamp) in documents |
+| `include_checksum` | bool | `true` | Include message checksum |
+| `include_origin_timestamp` | bool | `true` | Include client-provided timestamp |
+| `payload_format` | string | `"json"` | How to store the payload (`"json"` or `"bytea"`) |
+| `auto_create_collection` | bool | `true` | Create the collection if it doesn't exist |
+| `verbose_logging` | bool | `false` | Enable detailed logging |
+| `max_retries` | u32 | `3` | Max retry attempts on failure |
+| `retry_delay` | string | `"1s"` | Delay between retries |
+
+## Transforms
+
+You can apply transforms before writing to MongoDB. See the [transforms documentation](/docs/connectors/sdk#transforms) for details.
+
+```toml
+[transforms.add_fields]
+source = "iggy"
+processed_at = { type = "timestamp_millis" }
+trace_id = { type = "uuid_v7" }
+
+[transforms.delete_fields]
+fields = ["internal_field"]
+```
diff --git a/content/docs/connectors/sinks/sink.mdx b/content/docs/connectors/sinks/sink.mdx
index 5cef098e..7de1f138 100644
--- a/content/docs/connectors/sinks/sink.mdx
+++ b/content/docs/connectors/sinks/sink.mdx
@@ -4,7 +4,7 @@ title: Sink
 
 ## Overview
 
-Sink connectors are responsible for writing data from Iggy streams to external systems or destinations. They provide a way to integrate Apache Iggy with various data sources and destinations, enabling seamless data flow and processing.
+Sink connectors are responsible for writing data from Iggy streams to external systems or destinations. They provide a way to integrate Apache Iggy with various data sources and destinations, enabling data flow between Iggy and external systems.
 
 The sink is represented by the single `Sink` trait, which defines the basic interface for all sink connectors. It provides methods for initializing the sink, writing data to external destination, and closing the sink.
 
diff --git a/content/docs/connectors/sinks/stdout.mdx b/content/docs/connectors/sinks/stdout.mdx
new file mode 100644
index 00000000..2a2e4ed0
--- /dev/null
+++ b/content/docs/connectors/sinks/stdout.mdx
@@ -0,0 +1,34 @@
+---
+title: Stdout Sink
+---
+
+The stdout sink connector prints messages from Iggy streams to the standard output. This is useful for debugging, development, and verifying that your connector pipeline is working correctly.
+
+## Configuration
+
+```toml
+type = "sink"
+key = "stdout-sink"
+enabled = true
+version = 1
+name = "Stdout Sink"
+path = "/path/to/libstdout_sink.so"
+verbose = false
+
+[[streams]]
+stream = "my-stream"
+topics = ["my-topic"]
+schema = "json"
+batch_length = 10
+poll_interval = "1s"
+consumer_group = "stdout-sink-group"
+
+[plugin_config]
+print_payload = true
+```
+
+## Plugin config options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `print_payload` | bool | `true` | Whether to print the message payload to stdout |
diff --git a/content/docs/connectors/sources/meta.json b/content/docs/connectors/sources/meta.json
index b8d29d37..066b7014 100644
--- a/content/docs/connectors/sources/meta.json
+++ b/content/docs/connectors/sources/meta.json
@@ -1 +1 @@
-{"title": "Sources", "pages": ["source", "elasticsearch", "postgres"]}
+{"title": "Sources", "pages": ["source", "elasticsearch", "postgres", "random"]}
diff --git a/content/docs/connectors/sources/postgres.mdx b/content/docs/connectors/sources/postgres.mdx
index f6c7b8bd..6cfa50b0 100644
--- a/content/docs/connectors/sources/postgres.mdx
+++ b/content/docs/connectors/sources/postgres.mdx
@@ -63,7 +63,7 @@ The PostgreSQL source connector allows you to fetch data from PostgreSQL databas
 
 - Build-time feature flag: enable with `--features cdc_pg_replicate` on the `iggy_connector_postgres_source` crate.
 - When `cdc_backend` is set to `pg_replicate` but the feature is not enabled, the connector will return a clear initialization error.
-- The backend integrates Supabase's ETL for robust WAL decoding and resume from LSN.
+- The backend integrates Supabase's ETL for WAL decoding and resume from LSN.
 
 ### Notes
 
diff --git a/content/docs/connectors/sources/random.mdx b/content/docs/connectors/sources/random.mdx
new file mode 100644
index 00000000..9c92060c
--- /dev/null
+++ b/content/docs/connectors/sources/random.mdx
@@ -0,0 +1,39 @@
+---
+title: Random Source
+---
+
+The random source connector generates random messages and sends them to Iggy streams. This is useful for testing, benchmarking, and verifying that your connector pipeline is working correctly without needing an external data source.
+
+## Configuration
+
+```toml
+type = "source"
+key = "random-source"
+enabled = true
+version = 1
+name = "Random Source"
+path = "/path/to/librandom_source.so"
+verbose = false
+
+[[streams]]
+stream = "my-stream"
+topic = "my-topic"
+schema = "json"
+batch_length = 100
+linger_time = "100ms"
+
+[plugin_config]
+interval = "100ms"
+max_count = 0
+messages_range = [1, 10]
+payload_size = 256
+```
+
+## Plugin config options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `interval` | string | `"100ms"` | Delay between message generation batches |
+| `max_count` | u64 | `0` | Maximum number of messages to generate (0 = unlimited) |
+| `messages_range` | [u32, u32] | `[1, 10]` | Min/max messages per batch (random within range) |
+| `payload_size` | u32 | `256` | Size of each generated payload in bytes |
diff --git a/content/docs/faq/faq.mdx b/content/docs/faq/faq.mdx
index 5c7b6318..9d7c3ee1 100644
--- a/content/docs/faq/faq.mdx
+++ b/content/docs/faq/faq.mdx
@@ -8,4 +8,40 @@ Iggy is a persistent message streaming platform that stores messages in an appen
 
 ## Q: Are there plans to support Kafka protocol in Iggy?
 
-Currently, Iggy does not support the Kafka protocol. Our focus is on providing a high-performance native protocol that leverages the strengths of Iggy’s architecture. However, we are open to community contributions (in fact there is an [discussion](https://github.com/apache/iggy/discussions/6) about it).
+Currently, Iggy does not support the Kafka protocol. Our focus is on providing a high-performance native protocol that leverages the strengths of Iggy's architecture. However, we are open to community contributions (in fact there is an [discussion](https://github.com/apache/iggy/discussions/6) about it).
+
+## Q: What transport protocol should I use?
+
+For maximum throughput and lowest latency, use **TCP**. If you need built-in encryption without configuring TLS separately, **QUIC** is a good choice. **WebSocket** works well for browser-based clients. **HTTP** is the most accessible but has the highest overhead due to JSON serialization and stateless connections (no consumer groups).
+
+## Q: What are the system requirements?
+
+Iggy is a single binary with no external dependencies. On Linux, it uses `io_uring` for maximum performance, which requires kernel 5.19+. The server starts with around 20 MB of RAM (plus the configured memory pool, default 4 GiB). For Docker, you need to set `SYS_NICE` capability, disable seccomp, and set unlimited memlock.
+
+## Q: How does consumer group rebalancing work?
+
+When consumers join or leave a consumer group, the server triggers cooperative partition rebalancing. Partitions are redistributed among active members. During rebalancing, there is a pending revocation phase (configurable timeout, default 30s) to ensure in-progress message processing can complete before partitions move to new owners.
+
+## Q: Does Iggy support exactly-once delivery?
+
+Iggy supports **at-most-once** (with auto-commit), **at-least-once** (without auto-commit, manual offset management), and **exactly-once** via application-level deduplication. The server provides optional hash-based message deduplication per partition to help with this.
+
+## Q: How do I secure my Iggy deployment?
+
+Iggy supports TLS on all transport protocols, Argon2id password hashing, granular per-stream/per-topic permissions, Personal Access Tokens for programmatic access, and optional AES-256-GCM encryption at rest. For the HTTP API, JWT tokens are used for session management. See the [Security](/docs/server/security) documentation for details.
+
+## Q: Can I use Iggy with my existing tooling?
+
+Iggy provides a [Model Context Protocol (MCP)](/docs/ai/mcp) server with 40+ tools for LLM integration, [connectors](/docs/connectors/introduction) for piping data to/from external systems (PostgreSQL, MongoDB, Elasticsearch, Apache Iceberg, Quickwit), Prometheus metrics, and OpenTelemetry traces/logs. The HTTP API works with any REST client.
+
+## Q: What happened to the Tokio-based runtime?
+
+Iggy migrated from Tokio to a thread-per-core architecture with `compio` (which uses `io_uring` on Linux) starting with version 0.6.0. The migration delivered major performance improvements, including up to 92% better P9999 tail latency and 18% throughput improvement with fsync enabled. You can read the full story in the [thread-per-core io_uring blog post](https://iggy.apache.org/blogs/2026/02/27/thread-per-core-io_uring/).
+
+## Q: Is clustering/replication available?
+
+Clustering based on Viewstamped Replication (VSR) is under active development. The core consensus protocol, view change mechanism, deterministic timeout management, and network simulator are implemented. It is not yet production-ready. See the [Clustering](/docs/clustering/vsr) documentation for the current state.
+
+## Q: What examples are available?
+
+Examples are available in the [repository](https://github.com/apache/iggy/tree/master/examples) for multiple languages: Rust (basic, getting-started, message headers, compression, multi-tenant, stream builder, TLS), Go, Python, Java, Node.js, and C#. Docker Compose files and Helm charts are also provided.
diff --git a/content/docs/index.mdx b/content/docs/index.mdx
index bfa4914a..2c9a26a1 100644
--- a/content/docs/index.mdx
+++ b/content/docs/index.mdx
@@ -2,6 +2,42 @@
 title: Welcome
 ---
 
-Welcome to Apache Iggy (Incubating) documentation, which is under an active development.
+<DocsHero />
 
-Please, check the [introduction](/docs/introduction/about) to get the grasp of the fundamental concepts.
+<WhyIggy />
+
+## How Iggy organizes data
+
+Iggy uses a hierarchical model: **streams** contain **topics**, topics contain **partitions**, and partitions store messages in **segments** on disk. This gives you flexible multi-tenancy, parallel processing, and efficient storage all in one.
+
+<StreamHierarchy />
+
+## The append-only log
+
+Every partition is an append-only log. Messages are immutable once written, consumers can read from any offset, and you can replay the entire history at any time.
+
+<AppendOnlyLogViz />
+
+## Key capabilities
+
+| Capability | Details |
+|-----------|---------|
+| **Transport** | TCP, QUIC, WebSocket, HTTP with custom binary protocol |
+| **Performance** | Thread-per-core + io_uring, zero-copy deserialization, custom 4 GiB memory pool |
+| **Security** | TLS on all transports, Argon2id hashing, AES-256-GCM encryption, [granular RBAC](/docs/server/security) with per-stream/per-topic permissions |
+| **Connectors** | [Source & sink plugins](/docs/connectors/introduction) for PostgreSQL, MongoDB, Elasticsearch, Apache Iceberg, Quickwit with data transforms |
+| **AI Integration** | [MCP server](/docs/ai/mcp) with 40+ tools for LLM-driven message streaming management |
+| **Management** | [Web UI](/docs/web_ui/start) dashboard (embedded or standalone), [CLI](/docs/cli/start) with shell completions, Prometheus metrics, OpenTelemetry |
+| **Clustering** | [Viewstamped Replication (VSR)](/docs/clustering/vsr) consensus protocol (in development) |
+| **Deployment** | Single binary, [Docker & Helm](/docs/server/docker), NUMA-aware CPU affinity |
+
+## Ecosystem
+
+Iggy is more than just a server. The project includes a full ecosystem of tools:
+
+- **[Connectors Runtime](/docs/connectors/introduction)** - dynamically loaded Rust plugins for data integration. Ingest from PostgreSQL, Elasticsearch into Iggy, or forward to MongoDB, Elasticsearch, Apache Iceberg, Quickwit. Built-in data transforms and Prometheus metrics.
+- **[MCP Server](/docs/ai/mcp)** - Model Context Protocol server exposing 40+ tools for LLM integration. Works with Claude Desktop via stdio and HTTP transports.
+- **[Web UI](/docs/web_ui/start)** - SvelteKit dashboard for stream/topic management, message browsing with JSON/string/XML decoders, user management, and real-time terminal.
+- **[CLI](/docs/cli/start)** - full-featured command-line interface with named connection contexts, session-based login, and shell completions.
+- **[SDKs](/docs/sdk/introduction)** - client libraries for 7 languages (Rust, Python, Java, Go, Node.js, C#, C++) with examples for each.
+- **[Benchmarking](/docs/server/benchmarking)** - built-in `iggy-bench` tool with a Yew/WebAssembly dashboard for performance testing.
diff --git a/content/docs/introduction/about.mdx b/content/docs/introduction/about.mdx
index 57291beb..8bb6c368 100644
--- a/content/docs/introduction/about.mdx
+++ b/content/docs/introduction/about.mdx
@@ -20,15 +20,17 @@ The name is an abbreviation for the Italian Greyhound - small yet extremely fast
 
 - **Highly performant**, persistent append-only log for message streaming
 - **Very high throughput** for both writes and reads
-- **Low latency and predictable resource usage** thanks to the Rust compiled language (no GC) and `io_uring`.
-- **User authentication and authorization** with granular permissions and Personal Access Tokens (PAT)
+- **Low latency and predictable resource usage** thanks to the Rust compiled language (no GC) and `io_uring`
+- **Thread per core shared nothing design** together with `io_uring` guarantee the best possible performance on modern `Linux` systems
+- **NUMA-aware sharding** with CPU affinity and memory binding per NUMA node for optimal hardware utilization
+- **User authentication and authorization** with granular permissions, Personal Access Tokens (PAT) and Argon2id password hashing
 - Support for multiple streams, topics and partitions
 - Support for **multiple transport protocols** (QUIC, TCP, WebSocket, HTTP)
 - Fully operational RESTful API which can be optionally enabled
 - Available client SDK in multiple languages
-- **Thread per core shared nothing design** together with `io_uring` guarantee the best possible performance on modern `Linux` systems.
 - **Works directly with binary data**, avoiding enforced schema and serialization/deserialization overhead
-- Custom **zero-copy (de)serialization**, which greatly improves the performance and reduces memory usage.
+- Custom **zero-copy (de)serialization**, which greatly improves the performance and reduces memory usage
+- **Custom memory pool** with 32 buckets (buffer sizes from 256 B to 512 MiB) for pre-allocated, zero-copy message passing
 - Configurable server features (e.g. caching, segment size, data flush interval, transport protocols etc.)
 - Server-side storage of **consumer offsets**
 - Multiple ways of polling the messages:
@@ -37,52 +39,63 @@ The name is an abbreviation for the Italian Greyhound - small yet extremely fast
   - First/Last N messages
   - Next N messages for the specific consumer
 - Possibility of **auto committing the offset** (e.g. to achieve *at-most-once* delivery)
-- **Consumer groups** providing the message ordering and horizontal scaling across the connected clients
+- **Consumer groups** providing the message ordering and horizontal scaling across the connected clients, with cooperative partition rebalancing
 - **Message expiry** with auto deletion based on the configurable **retention policy**
 - Additional features such as **server side message deduplication**
 - **Multi-tenant** support via abstraction of **streams** which group **topics**
 - **TLS** support for all transport protocols (TCP, QUIC, WebSocket, HTTPS)
-- **[Connectors](https://github.com/apache/iggy/tree/master/core/connectors)** - sinks, sources and data transformations based on the **custom Rust plugins**
-- **[Model Context Protocol](https://github.com/apache/iggy/tree/master/core/ai/mcp)** - provide context to LLM with **MCP server**
+- **[Connectors](/docs/connectors/introduction)** - sinks, sources and data transformations based on the **custom Rust plugins** loaded dynamically at runtime
+- **[Model Context Protocol](/docs/ai/mcp)** - provide context to LLM with **MCP server** exposing 40+ tools for full Iggy management
 - Optional server-side as well as client-side **data encryption** using AES-256-GCM
 - Optional metadata support in the form of **message headers**
 - Optional **data backups and archiving** to disk or **S3** compatible cloud storage (e.g. AWS S3)
 - Support for **OpenTelemetry** logs & traces + Prometheus metrics
-- Built-in **CLI** to manage the streaming server installable via `cargo install iggy-cli`
+- Built-in **[CLI](/docs/cli/start)** to manage the streaming server installable via `cargo install iggy-cli`
+- Built-in **[Web UI](/docs/web_ui/start)** dashboard (Svelte) that can be embedded directly in the server binary or run as a standalone container
 - Built-in **benchmarking app** to test the performance
 - **Single binary deployment** (no external dependencies)
-- Running as a single node (clustering based on Viewstamped Replication will be implemented in the near future)
+- **TCP socket migration** across shards for optimal request routing
+- Running as a single node, with **clustering based on Viewstamped Replication (VSR)** currently being implemented
 
 ## Supported languages SDK
 
-- [Rust](https://crates.io/crates/iggy)
-- [C#](https://www.nuget.org/packages/Apache.Iggy/)
-- [Java](https://mvnrepository.com/artifact/org.apache.iggy/iggy-java-sdk)
-- [Python](https://pypi.org/project/apache-iggy/)
-- [Node.js (TypeScript)](https://www.npmjs.com/package/apache-iggy)
-- [Go](https://pkg.go.dev/github.com/apache/iggy/foreign/go)
-
-C++ and Elixir SDKs are a work in progress.
+| Language | Package | Registry |
+|----------|---------|----------|
+| Rust | [iggy](https://crates.io/crates/iggy) | crates.io |
+| C# | [Apache.Iggy](https://www.nuget.org/packages/Apache.Iggy/) | NuGet |
+| Java | [iggy](https://mvnrepository.com/artifact/org.apache.iggy/iggy) | Maven Central |
+| Python | [apache-iggy](https://pypi.org/project/apache-iggy/) | PyPI |
+| Node.js | [apache-iggy](https://www.npmjs.com/package/apache-iggy) | npm |
+| Go | [iggy-go](https://pkg.go.dev/github.com/apache/iggy/foreign/go) | pkg.go.dev |
+| C++ | [iggy-cpp](https://github.com/apache/iggy/tree/master/foreign/cpp) | GitHub (WIP) |
 
 ## CLI
 
 The interactive CLI is implemented under the `cli` project, to provide the best developer experience. This is a great addition to the Web UI, especially for developers who prefer using the console tools.
 
-Iggy CLI can be installed with `cargo install iggy-cli` and then simply accessed by typing `iggy` in your terminal.
+Iggy CLI can be installed with `cargo install iggy-cli` and then simply accessed by typing `iggy` in your terminal. It supports named connection contexts (profiles) for managing multiple server connections, shell completions for bash/zsh/fish/elvish/powershell, and session-based login on Linux.
 
 ### Web UI
 
-There's a dedicated Web UI for the server, which allows you to manage streams, topics, partitions, browsing the messages and so on. This is an ongoing effort to build a comprehensive dashboard for administrative purposes of the Iggy server. Check the Web UI in the `/web` directory.
-The [docker image](https://hub.docker.com/r/apache/iggy-web-ui) is available, and can be fetched via `docker pull apache/iggy-web-ui`.
+The Web UI provides a comprehensive dashboard for the Iggy server, built with SvelteKit and TypeScript. It can run in two modes:
+
+- **Embedded** - compiled into the server binary (with `iggy-web` feature flag), served at the `/ui` endpoint
+- **Standalone** - as a separate container via `docker pull apache/iggy-web-ui`
+
+Features include stream/topic/partition management, message browser with JSON/string/XML decoders, user management, server logs viewer, real-time terminal, and server configuration overview.
 
 ## Connectors
 
 Iggy provides a highly performant and modular **[runtime](/docs/connectors/runtime)** for statically typed, yet dynamically loaded connectors. You can ingest data from external sources and push the data to Iggy streams, or fetch data from Iggy streams and forward it to external systems. **Create your own Rust plugins** by simply implementing either the `Source` or `Sink` trait and **build custom pipelines for the data processing**.
+
+Available connectors include sources for PostgreSQL, Elasticsearch, and random data generation, along with sinks for PostgreSQL, MongoDB, Elasticsearch, Quickwit, Apache Iceberg, and stdout.
+
 The [docker image](https://hub.docker.com/r/apache/iggy-connect) is available, and can be fetched via `docker pull apache/iggy-connect`.
 
 ## Model Context Protocol
 
-The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that standardizes how applications provide context to LLMs. The **[Iggy MCP Server](/docs/ai/mcp)** is an implementation of the MCP protocol for message streaming infrastructure. It can be used to provide context to LLMs in real-time, allowing for more accurate and relevant responses.
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that standardizes how applications provide context to LLMs. The **[Iggy MCP Server](/docs/ai/mcp)** is an implementation of the MCP protocol for message streaming infrastructure. It exposes 40+ tools covering streams, topics, partitions, messages, consumer groups, users, and more. It supports both HTTP and stdio transports, making it compatible with tools like Claude Desktop and other MCP clients.
+
 The [docker image](https://hub.docker.com/r/apache/iggy-mcp) is available, and can be fetched via `docker pull apache/iggy-mcp`.
 
 ### Docker
@@ -118,6 +131,10 @@ Or when running with `docker run`:
 docker run --cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 apache/iggy:edge
 ```
 
+### Helm Charts
+
+Helm charts for Kubernetes deployment are available in the [repository](https://github.com/apache/iggy/tree/master/helm/charts/iggy). The chart includes templates for Deployment, Service, ServiceAccount, HPA (Horizontal Pod Autoscaler), Ingress, PersistentVolumeClaim, ServiceMonitor (for Prometheus), and root user credentials Secret.
+
 ### Versioning
 
 The official releases follow the regular semver (`0.5.0`) or have a `latest` tag applied (`apache/iggy:latest`).
diff --git a/content/docs/introduction/architecture.mdx b/content/docs/introduction/architecture.mdx
index a0cb3162..01afe4f1 100644
--- a/content/docs/introduction/architecture.mdx
+++ b/content/docs/introduction/architecture.mdx
@@ -20,9 +20,37 @@ There are advantages and disadvantages of both approaches, but the main differen
 
 As you might've guessed by now, Iggy is the latter - the message streaming platform.
 
+## How a message flows through Iggy
+
+Before diving into the architecture details, here's the complete journey of a message from client to disk:
+
+<MessageFlowDiagram />
+
 ## Thread per core (shared nothing) + io_uring
 
-Iggy utilizies `io_uring` as the main I/O interface, which allows it to achieve high performance and low latency. Each core (shard), runs it's own instance of the server, which means that there is (almost) no shared state between the cores. This allows Iggy to scale linearly with the number of cores, as there is no contention between the cores. This architecture been proven by systems such as `redpanda` or `scylladb`, which are known for their high performance and low latency. Each shard [...]
+Iggy uses a **thread-per-core shared nothing architecture** combined with `io_uring` for maximum performance. This design has been proven by systems like ScyllaDB and Redpanda, and is inspired by the Seastar framework.
+
+<ShardDiagram />
+
+### How it works
+
+Each CPU core runs its own **shard** (an instance of `IggyShard`), pinned to a specific core via `sched_setaffinity` on Linux. Each shard has its own single-threaded `compio` async runtime, which means there is no cross-thread synchronization needed within a shard. Memory is bound to the NUMA node of the core via `hwlocality` for optimal memory access latency.
+
+### Asymmetric shard roles
+
+Shards have asymmetric roles:
+
+- **Shard 0 (Primary)** holds the exclusive `MetadataWriter`, runs the HTTP and QUIC servers, and acts as the VSR consensus primary
+- **Shards 1..N (Workers)** hold `MetadataReader` clones, manage local partitions, and run TCP/WebSocket servers for load distribution
+
+### Request routing
+
+Requests are routed between shards using **message passing** (via `crossfire` bounded mpsc channels), which avoids locking entirely. The routing logic splits operations into two planes:
+
+- **Metadata operations** (create/delete stream/topic/user etc.) always go to **shard 0**
+- **Partition operations** (send_messages, store_consumer_offset) are routed to the shard owning that partition via a `DashMap` lookup
+
+Partitions are distributed between shards using `Murmur3` hashing with correction for small partition counts:
 
 ```rs
 pub fn calculate_shard_assignment(ns: &IggyNamespace, upperbound: u32) -> u16 {
@@ -34,20 +62,60 @@ pub fn calculate_shard_assignment(ns: &IggyNamespace, upperbound: u32) -> u16 {
 }
 ```
 
-`io_uring` is an ever-growing beast, to learn more about it please check the [documentation](https://kernel.dk/io_uring.pdf) or the excellent [presentation](https://www.youtube.com/watch?v=ToSRCSijRuE) by Jens Axboe, the original author of `io_uring`.
+### IggyNamespace
+
+The `IggyNamespace` packs stream_id (12 bits), topic_id (12 bits), and partition_id (20 bits) into a single `u64` for efficient hashing and routing. This gives maximums of 4096 streams, 4096 topics per stream, and 1,000,000 partitions per topic.
+
+<NamespacePacking />
+
+### CPU allocation modes
+
+The sharding system supports multiple allocation modes via the `cpu_allocation` config:
+
+- `"all"` - one shard per available CPU core
+- A numeric value (e.g. `4`) - exactly N shards pinned to cores 0..N
+- A range (e.g. `"5..8"`) - shards on specified core range
+- `"numa:auto"` - automatically detect NUMA topology and bind accordingly
+- `"numa:nodes=0,1;cores=4;no_ht=true"` - fine-grained NUMA control per node with hyperthread avoidance
+
+### io_uring and compio
+
+Traditional async runtimes like tokio use `epoll` which is **readiness-based** - you ask the kernel "is this file descriptor ready?" and then perform the I/O yourself. The Linux kernel considers regular files "always ready" for epoll, which means tokio has to outsource file I/O to a blocking thread pool (up to 512 threads). This does not scale well.
+
+`io_uring` is **completion-based** - you submit I/O requests to a submission queue (SQ), and the kernel completes them and places results in a completion queue (CQ). Both queues are lock-free ring buffers shared between user space and kernel. This is fundamentally better for disk I/O.
+
+<IoUringComparison />
+
+Iggy uses **compio** as its async runtime, which provides a driver-disaggregated architecture on top of io_uring (Linux) and IOCP (Windows). Each shard gets its own compio executor configured with:
+- Capacity: 4096 concurrent I/O operations
+- Event interval: 128 events per loop iteration
+- Cooperative task running enabled
+
+### Performance: Tokio vs Thread-per-Core
 
-Check [benchmarking](../server/benchmarking.md) section to see some performance numbers.
+The migration from Tokio to thread-per-core with compio delivered significant latency improvements across the board:
+
+<BenchmarkChart />
+
+### TCP socket migration
+
+Iggy supports **TCP socket migration** across shards. When a client sends a request that targets a partition on a different shard, instead of forwarding the request (cross-shard hop), the TCP socket itself can be migrated to the owning shard. This eliminates the overhead of cross-shard message passing for data plane operations.
+
+### Left-right metadata
+
+Shared metadata (streams, topics, consumer groups) uses a **left-right** concurrent data structure. Shard 0 is the sole writer, while all other shards hold read-only clones that are updated lock-free. This provides:
+- Lock-free reads on all shards (no contention on the hot path)
+- Strongly consistent writes serialized through shard 0
 
 ## Append-only log
 
-The append-only log is the core concept of Iggy. It's a simple data structure, which is optimized for the append-only operations. It's a sequence of records, that are being appended to the end of the log. The records are immutable, so that they can't be changed once they are written to the log. The records are being written in the order they are received, which results in the log being is ordered.
+The append-only log is the core concept of Iggy. It's a simple data structure, which is optimized for the append-only operations. It's a sequence of records, that are being appended to the end of the log. The records are immutable, so that they can't be changed once they are written to the log. The records are being written in the order they are received, which results in the log being ordered.
 
 To navigate the log, you can use the offset, which is the position of the record in the log. The offset is a simple integer, that starts from 0 and is incremented by 1 for each record. When the client is reading the records from the log, it can specify the offset from which it wants to start reading the records. The client can also specify the maximum number of records it wants to read. The client can read the records from the beginning, or from the specific offset, which means that you  [...]
 
-```mermaid
-graph LR
-  M1["Msg 1 · Offset 0"] --> M2["Msg 2 · Offset 1"] --> M3["Msg 3 · Offset 2"] --> M4["Msg 4 · Offset 3"] --> M5["Msg 5 · Offset 4"]
-```
+<AppendOnlyLogViz />
+
+<StreamHierarchy />
 
 ## Stream
 
@@ -58,7 +126,7 @@ The stream is a logical concept, and you might think of it as a namespace. For e
 
 The topic is also the logical concept, which is a part of the stream. The topic is identified by its unique ID. You could think of topic as an entity being responsible for storing the specific type of the records. For example, you could have a topic for the user events, and another topic for the order events, etc.
 
-The important thing to note is that, the messages are not being stored in the topic directly, but rather in the partitions, which are assigned to the topic. The topic can have one or more partitions assigned, that could help achieve higher parallelism and throughput. The topic can also have the retention policy assigned, which means that the records are being deleted automatically once they are older than the specified retention period.
+The important thing to note is that, the messages are not being stored in the topic directly, but rather in the partitions, which are assigned to the topic. The topic can have one or more partitions assigned, that could help achieve higher parallelism and throughput. The topic can also have the retention policy assigned, which means that the records are being deleted automatically once they are older than the specified retention period. Topics also support configurable compression (`none [...]
 
 ## Partition
 
@@ -66,23 +134,77 @@ The partition has its own unique ID and belongs to the topic. The partition is r
 
 Thanks to having multiple partitions, we can achieve the horizontal scalability between many independent consumers, since each consumer can read the messages from the different partitions. This can be achieved by using more advanced concepts such as consumer groups.
 
+Each partition in the thread-per-core architecture is owned by exactly one shard and includes:
+- A `SegmentedLog` with sealed segments and one active segment
+- Consumer offsets and consumer group offsets
+- Optional `MessageDeduplicator` for server-side dedup
+- Partition statistics and an atomic offset counter
+
 ## Segment
 
-The segment, being a part of the partition, is the actual physical layer which stores the records in the binary format in a form of the files. Each segment has the limited size (e.g. 1 GB) and once it's full, the new segment is being created automatically. The segment name is based on the start offset of the first record in the segment and is unique per partition.
+The segment, being a part of the partition, is the actual physical layer which stores the records in the binary format in a form of the files. Each segment has the limited size (default 1 GiB) and once it's full, the new segment is being created automatically. The segment name is based on the start offset of the first record in the segment and is unique per partition.
+
+Each segment consists of:
+- `.log` file - the actual message data
+- `.index` file - positional and time indexes for fast lookups
+
+Index caching can be configured per strategy: `"all"` (all indexes in memory), `"open_segment"` (only the active segment cached, the default), or `"none"` (on-demand disk reads).
+
+## Consumer groups
+
+Consumer groups provide horizontal scaling for message consumption. When multiple consumers join the same consumer group, the server automatically distributes partitions among group members so that each partition is consumed by exactly one member. When members join or leave, the server triggers a **cooperative partition rebalancing** with a pending revocation phase (configurable timeout, default 30s) to ensure smooth transitions without message loss.
+
+<ConsumerGroupViz />
+
+## Message format
+
+<MessageHeaderDiagram />
+
+Each message has a 64-byte header stored in little-endian format:
+
+| Field | Bytes | Type | Description |
+|-------|-------|------|-------------|
+| checksum | 0-8 | u64 | xxHash3 integrity checksum |
+| id | 8-24 | u128 | Unique message ID (UUIDv4) |
+| offset | 24-32 | u64 | Sequential offset in partition |
+| timestamp | 32-40 | u64 | Server-assigned timestamp |
+| origin_timestamp | 40-48 | u64 | Client-provided timestamp |
+| user_headers_length | 48-52 | u32 | Length of optional headers |
+| payload_length | 52-56 | u32 | Length of payload |
+| reserved | 56-64 | u64 | Reserved (must be 0) |
+
+After the header comes the optional user headers bytes, followed by the payload bytes.
 
 ## Structure
 
 Having in mind that stream consists of topics, which might have one or more partitions assigned, and each partition consists of segments, we can visualize the structure of the Iggy data directory as follows:
 
 ```bash
-streams/
-└── 1/
-    └── topics/
-        └── 1/
-            └── partitions/
-                └── 1/
-                    ├── 00000000000000000000.index
-                    └── 00000000000000000000.log
+local_data/
+├── info.json
+├── state.messages
+└── streams/
+    └── 1/
+        └── topics/
+            └── 1/
+                └── partitions/
+                    └── 1/
+                        ├── 00000000000000000000.index
+                        └── 00000000000000000000.log
 ```
 
-The additional `.index` file is being created automatically and are being used to speed up the search operations by keeping track of the offsets and timestamps of the records.
+The `.index` file is created automatically and is used to speed up the search operations by keeping track of the offsets and timestamps of the records. The `state.messages` file is a write-ahead log that persists all metadata operations (stream/topic/user creation, etc.) with SHA-256 checksums for integrity.
+
+## Memory pool
+
+Iggy uses a custom memory pool with 32 buckets holding buffer sizes from 256 B to 512 MiB. The default pool size is 4 GiB with 8192 buffers per bucket. This eliminates allocation overhead on the hot path and enables zero-copy message passing between components. The pool is page-aligned (4096-byte multiples) and requires a minimum of 512 MiB.
+
+## Write pipeline
+
+Messages flow through a multi-stage write pipeline:
+
+1. Messages arrive and are buffered in a `MemoryMessageJournal`
+2. A flush is triggered when either the message count threshold (default 1024) or size threshold (default 1 MiB) is reached
+3. The `MessagesWriter` uses **vectored I/O** with `MAX_IOV_COUNT=1024` to minimize syscalls
+4. Optional `fsync` per partition for durability guarantees
+5. When a segment reaches its size limit (default 1 GiB), it is sealed and a new segment is created
diff --git a/content/docs/introduction/getting-started.mdx b/content/docs/introduction/getting-started.mdx
index ff651141..861121f5 100644
--- a/content/docs/introduction/getting-started.mdx
+++ b/content/docs/introduction/getting-started.mdx
@@ -4,21 +4,19 @@ title: Getting started
 
 ## Before we start
 
-This is a **Rust based implementation**, to look for examples in the other programming languages, please check the [SDK](/docs/sdk/introduction)
+This tutorial uses the **low-level Rust SDK** to show how things work under the hood - creating streams, topics, sending and polling messages step by step. This is great for understanding the fundamentals.
 
-## What we will build
-
-Once you're familiar with the [architecture](/docs/introduction/architecture), it's high time to build the first application, or actually the set of applications - so-called **producer** (the one that will be publishing the messages to the stream) and **consumer** (yes, you got that right - it will handle the incoming messages stream).
+For real-world applications, you might typically prefer the **[high-level SDK](/docs/sdk/rust/high-level-sdk)**, which provides `IggyProducer` and `IggyConsumer` builders with auto-batching, consumer groups, offset management, reconnection, and retry logic out of the box. Check the [Stream Builder](/docs/sdk/rust/stream-builder) docs for the most ergonomic API.
 
-In the typical scenario, e.g. when working with the microservices architecture or any other kind of the distributed system, each application can be both at the same time (producer and consumer), as the particular service might publish its own messages (typically in a form of the events - facts, that have already happened) while at the same time be interested in the notifications coming from the other service(s).
+For examples in other programming languages, see the [SDK section](/docs/sdk/introduction).
 
-The completed sample can be found in [repository](https://github.com/apache/iggy/tree/master/examples/rust/src/getting-started), however, we will go through the implementation step by step, so that you can get a better understanding of how to build the applications from scratch.
+## What we will build
 
-Also, please do keep in mind that we'll be using the default implementation of `IggyClient` which provides a wrapper on top of the low-level, transport-specific `Client` trait (which you can always use, if you want to have more control over the communication with the server).
+<MessageFlowDiagram />
 
-On the other hand, if you're looking for a **more developer-friendly client builder API** providing additional features and extensions, please check the next article under [High-level SDK](/docs/sdk/rust/high-level-sdk) section (this is typically how you'd use Iggy SDK in the real-world applications).
+We will build a **producer** (publishing messages to a stream) and a **consumer** (reading those messages back). In a real system, a service can be both at the same time - publishing its own events while consuming events from other services.
 
-Nevertheless, let's start with the basic scenario, and build the producer and consumer applications using the default `IggyClient` implementation, so you can get a better understanding of how to work with the streaming server.
+The completed sample can be found in the [repository](https://github.com/apache/iggy/tree/master/examples/rust/src/getting-started). We will go through the implementation step by step so you get a clear understanding of how it all fits together.
 
 ## Starting the Iggy server
 
@@ -114,9 +112,7 @@ To make use of logging, simply invoke `tracing_subscriber::fmt::init()` at the b
 
 ```rust
 use std::error::Error;
-use iggy::client::{Client, UserClient};
-use iggy::clients::client::IggyClient;
-use iggy::users::defaults::{DEFAULT_ROOT_PASSWORD, DEFAULT_ROOT_USERNAME};
+use iggy::prelude::*;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
@@ -136,23 +132,15 @@ So far, so good, however, before we will be able to publish any messages to our
 
 Since our `IggyClient` implements the common [Client](https://github.com/apache/iggy/blob/master/core/sdk/src/clients/client.rs) trait, you can find lots of the different methods to interact with the server, also from the administrative point of view, e.g. creating the streams, topics etc.
 
-One thing worth mentioning is that, these methods are not idempotent - for example, if you were to try creating the stream with the same ID which already exists on the server, you would receive the specific error. In such a case, you can simply check for an error and move on. Let's do this then :)
+One thing worth mentioning is that, these methods are not idempotent - for example, if you were to try creating the stream with the same name which already exists on the server, you would receive the specific error. In such a case, you can simply check for an error and move on. When creating a stream, we only provide its name - the server assigns the numeric ID automatically. Let's do this then :)
 
 ```rust
-use iggy::client::{Client, StreamClient, TopicClient, UserClient};
-use iggy::clients::client::IggyClient;
-use iggy::identifier::Identifier;
-use iggy::streams::create_stream::CreateStream;
-use iggy::topics::create_topic::CreateTopic;
+use iggy::prelude::*;
 use std::error::Error;
 use tracing::{info, warn};
-use iggy::compression::compression_algorithm::CompressionAlgorithm;
-use iggy::users::defaults::{DEFAULT_ROOT_PASSWORD, DEFAULT_ROOT_USERNAME};
-use iggy::utils::expiry::IggyExpiry;
-use iggy::utils::topic_size::MaxTopicSize;
 
-const STREAM_ID: u32 = 1;
-const TOPIC_ID: u32 = 1;
+const STREAM_NAME: &str = "sample-stream";
+const TOPIC_NAME: &str = "sample-topic";
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
@@ -167,19 +155,18 @@ async fn main() -> Result<(), Box<dyn Error>> {
 }
 
 async fn init_system(client: &IggyClient) {
-    match client.create_stream("sample-stream", Some(STREAM_ID)).await {
+    match client.create_stream(STREAM_NAME).await {
         Ok(_) => info!("Stream was created."),
         Err(_) => warn!("Stream already exists and will not be created again."),
     }
 
     match client
         .create_topic(
-            &STREAM_ID.try_into().unwrap(),
-            "sample-topic",
+            &STREAM_NAME.try_into().unwrap(),
+            TOPIC_NAME,
             1,
             CompressionAlgorithm::default(),
             None,
-            Some(TOPIC_ID),
             IggyExpiry::NeverExpire,
             MaxTopicSize::ServerDefault,
         )
@@ -210,15 +197,15 @@ let partitioning = Partitioning::partition_id(PARTITION_ID);
 
 client
     .send_messages(
-        &STREAM_ID.try_into().unwrap(),
-        &TOPIC_ID.try_into().unwrap(),
+        &STREAM_NAME.try_into().unwrap(),
+        &TOPIC_NAME.try_into().unwrap(),
         &partitioning,
         &mut messages,
     )
     .await?;
 ```
 
-As you might've already noticed, there are quite a few fields to be assigned. While some of them should be rather self-descriptive, let's discuss the `identifier` (created implicitly by using `TryFrom` on top of `STREAM_ID` and `TOPIC_ID`) and the `partitioning` which might be a little bit confusing at first, starting with the former.
+As you might've already noticed, there are quite a few fields to be assigned. While some of them should be rather self-descriptive, let's discuss the `identifier` (created implicitly by using `TryFrom` on top of `STREAM_NAME` and `TOPIC_NAME`) and the `partitioning` which might be a little bit confusing at first, starting with the former.
 
 ```rust
 pub struct Identifier {
@@ -228,7 +215,7 @@ pub struct Identifier {
 }
 ```
 
-Whenever we interact with the streaming server in terms of e.g. sending or polling the messages, managing the streams, topics etc. we need to provide the unique identifier of the stream and the topic that we want to use. Since each stream and topic have a unique numeric ID, as well as a unique name, we can use either of them. Here, we use the numeric ID by calling `Identifier::numeric()`, however, you can also use the string identifier by invoking the `Identifier::named()` method instead [...]
+Whenever we interact with the streaming server in terms of e.g. sending or polling the messages, managing the streams, topics etc. we need to provide the unique identifier of the stream and the topic that we want to use. Since each stream and topic have a unique numeric ID, as well as a unique name, we can use either of them. Here, we use the string name by calling `Identifier::named()` (implicitly via `TryFrom` on a `&str`), however, you can also use the numeric identifier by invoking t [...]
 
 Next, let's move onto the `partitioning` field:
 
@@ -254,8 +241,8 @@ async fn produce_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
     let interval = Duration::from_millis(500);
     info!(
         "Messages will be sent to stream: {}, topic: {}, partition: {} with interval {} ms.",
-        STREAM_ID,
-        TOPIC_ID,
+        STREAM_NAME,
+        TOPIC_NAME,
         PARTITION_ID,
         interval.as_millis()
     );
@@ -273,8 +260,8 @@ async fn produce_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
         }
         client
             .send_messages(
-                &STREAM_ID.try_into().unwrap(),
-                &TOPIC_ID.try_into().unwrap(),
+                &STREAM_NAME.try_into().unwrap(),
+                &TOPIC_NAME.try_into().unwrap(),
                 &partitioning,
                 &mut messages,
             )
@@ -290,21 +277,15 @@ The reason behind passing a mutable reference is that the underlying client (esp
 Finally, let's complete the implementation of the producer - once you start the application after the latest changes, you shall see the messages being sent to the newly created stream.
 
 ```rust
-use iggy::client::{Client, MessageClient, StreamClient, TopicClient, UserClient};
-use iggy::clients::client::IggyClient;
-use iggy::messages::send_messages::{Message, Partitioning};
+use iggy::prelude::*;
 use std::error::Error;
 use std::str::FromStr;
 use std::time::Duration;
 use tokio::time::sleep;
 use tracing::{info, warn};
-use iggy::compression::compression_algorithm::CompressionAlgorithm;
-use iggy::users::defaults::{DEFAULT_ROOT_PASSWORD, DEFAULT_ROOT_USERNAME};
-use iggy::utils::expiry::IggyExpiry;
-use iggy::utils::topic_size::MaxTopicSize;
 
-const STREAM_ID: u32 = 1;
-const TOPIC_ID: u32 = 1;
+const STREAM_NAME: &str = "sample-stream";
+const TOPIC_NAME: &str = "sample-topic";
 const PARTITION_ID: u32 = 1;
 
 #[tokio::main]
@@ -321,19 +302,18 @@ async fn main() -> Result<(), Box<dyn Error>> {
 }
 
 async fn init_system(client: &IggyClient) {
-    match client.create_stream("sample-stream", Some(STREAM_ID)).await {
+    match client.create_stream(STREAM_NAME).await {
         Ok(_) => info!("Stream was created."),
         Err(_) => warn!("Stream already exists and will not be created again."),
     }
 
     match client
         .create_topic(
-            &STREAM_ID.try_into().unwrap(),
-            "sample-topic",
+            &STREAM_NAME.try_into().unwrap(),
+            TOPIC_NAME,
             1,
             CompressionAlgorithm::default(),
             None,
-            Some(TOPIC_ID),
             IggyExpiry::NeverExpire,
             MaxTopicSize::ServerDefault,
         )
@@ -348,8 +328,8 @@ async fn produce_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
     let interval = Duration::from_millis(500);
     info!(
         "Messages will be sent to stream: {}, topic: {}, partition: {} with interval {} ms.",
-        STREAM_ID,
-        TOPIC_ID,
+        STREAM_NAME,
+        TOPIC_NAME,
         PARTITION_ID,
         interval.as_millis()
     );
@@ -367,8 +347,8 @@ async fn produce_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
         }
         client
             .send_messages(
-                &STREAM_ID.try_into().unwrap(),
-                &TOPIC_ID.try_into().unwrap(),
+                &STREAM_NAME.try_into().unwrap(),
+                &TOPIC_NAME.try_into().unwrap(),
                 &partitioning,
                 &mut messages,
             )
@@ -386,8 +366,8 @@ The consumer part will be rather easy to implement. Just like on the producer si
 ```rust
 let polled_messages = client
     .poll_messages(
-        &STREAM_ID.try_into()?,
-        &TOPIC_ID.try_into()?,
+        &STREAM_NAME.try_into()?,
+        &TOPIC_NAME.try_into()?,
         Some(PARTITION_ID),
         &Consumer::default(),
         &PollingStrategy::offset(offset),
@@ -421,12 +401,11 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
     let mut offset = 0;
     let messages_per_batch = 10;
     let consumer = Consumer::default();
-    let mut strategy = PollingStrategy::offset(offset);
     loop {
         let polled_messages = client
             .poll_messages(
-                &STREAM_ID.try_into()?,
-                &TOPIC_ID.try_into()?,
+                &STREAM_NAME.try_into()?,
+                &TOPIC_NAME.try_into()?,
                 Some(PARTITION_ID),
                 &consumer,
                 &PollingStrategy::offset(offset),
@@ -442,7 +421,6 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
         }
 
         offset += polled_messages.messages.len() as u64;
-        strategy.set_value(offset);
         for message in polled_messages.messages {
             handle_message(&message)?;
         }
@@ -454,19 +432,14 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
 And here's the final code for our consumer application:
 
 ```rust
-use iggy::client::{Client, MessageClient, UserClient};
-use iggy::clients::client::IggyClient;
-use iggy::consumer::Consumer;
-use iggy::messages::poll_messages::PollingStrategy;
-use iggy::models::messages::PolledMessage;
+use iggy::prelude::*;
 use std::error::Error;
 use std::time::Duration;
 use tokio::time::sleep;
 use tracing::info;
-use iggy::users::defaults::{DEFAULT_ROOT_PASSWORD, DEFAULT_ROOT_USERNAME};
 
-const STREAM_ID: u32 = 1;
-const TOPIC_ID: u32 = 1;
+const STREAM_NAME: &str = "sample-stream";
+const TOPIC_NAME: &str = "sample-topic";
 const PARTITION_ID: u32 = 1;
 
 #[tokio::main]
@@ -484,8 +457,8 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
     let interval = Duration::from_millis(500);
     info!(
         "Messages will be consumed from stream: {}, topic: {}, partition: {} with interval {} ms.",
-        STREAM_ID,
-        TOPIC_ID,
+        STREAM_NAME,
+        TOPIC_NAME,
         PARTITION_ID,
         interval.as_millis()
     );
@@ -493,12 +466,11 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
     let mut offset = 0;
     let messages_per_batch = 10;
     let consumer = Consumer::default();
-    let mut strategy = PollingStrategy::offset(offset);
     loop {
         let polled_messages = client
             .poll_messages(
-                &STREAM_ID.try_into()?,
-                &TOPIC_ID.try_into()?,
+                &STREAM_NAME.try_into()?,
+                &TOPIC_NAME.try_into()?,
                 Some(PARTITION_ID),
                 &consumer,
                 &PollingStrategy::offset(offset),
@@ -514,7 +486,6 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
         }
 
         offset += polled_messages.messages.len() as u64;
-        strategy.set_value(offset);
         for message in polled_messages.messages {
             handle_message(&message)?;
         }
@@ -522,12 +493,12 @@ async fn consume_messages(client: &IggyClient) -> Result<(), Box<dyn Error>> {
     }
 }
 
-fn handle_message(message: &PolledMessage) -> Result<(), Box<dyn Error>> {
+fn handle_message(message: &IggyMessage) -> Result<(), Box<dyn Error>> {
     // The payload can be of any type as it is a raw byte array. In this case it's a simple string.
     let payload = std::str::from_utf8(&message.payload)?;
     info!(
         "Handling message at offset: {}, payload: {}...",
-        message.offset, payload
+        message.header.offset, payload
     );
     Ok(())
 }
diff --git a/content/docs/meta.json b/content/docs/meta.json
index 8736e0c2..4737886a 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -4,11 +4,12 @@
     "index",
     "introduction",
     "server",
+    "clustering",
+    "connectors",
     "sdk",
     "cli",
-    "connectors",
-    "ai",
     "web_ui",
+    "ai",
     "faq"
   ]
 }
diff --git a/content/docs/sdk/cpp/intro.mdx b/content/docs/sdk/cpp/intro.mdx
new file mode 100644
index 00000000..5125c4ca
--- /dev/null
+++ b/content/docs/sdk/cpp/intro.mdx
@@ -0,0 +1,57 @@
+---
+title: C++ SDK (WIP)
+---
+
+The Iggy C++ SDK is a work in progress. It wraps the Rust SDK via CXX/FFI, which means it can access all transport protocols (TCP, QUIC, HTTP, WebSocket) through connection strings. The source code is available at [github.com/apache/iggy/tree/master/foreign/cpp](https://github.com/apache/iggy/tree/master/foreign/cpp).
+
+This SDK is not yet published to any package registry. To use it, build from source using CMake.
+
+## Quick start
+
+```cpp
+#include "lib.rs.h"
+
+// Connect via connection string (supports all transports)
+auto* client = iggy::ffi::new_connection(
+    "iggy://iggy:iggy@localhost:8090"
+);
+client->connect();
+client->login_user("iggy", "iggy");
+
+// Create a stream
+client->create_stream("my-stream");
+
+// Build an identifier for the stream
+iggy::ffi::Identifier stream_id;
+stream_id.kind = "string";
+stream_id.length = 9;
+for (char c : std::string("my-stream"))
+    stream_id.value.push_back(static_cast<uint8_t>(c));
+
+// Create a topic with 2 partitions
+client->create_topic(stream_id, "my-topic", 2);
+
+// Cleanup
+iggy::ffi::delete_connection(client);
+```
+
+## Connection strings
+
+The C++ SDK supports the same connection string format as the Rust SDK:
+
+```
+iggy://user:pass@host:port           (TCP, default)
+iggy+quic://user:pass@host:port      (QUIC)
+iggy+http://user:pass@host:port      (HTTP)
+iggy+ws://user:pass@host:port        (WebSocket)
+```
+
+When an empty string or plain address is passed to `new_connection()`, it defaults to TCP.
+
+## Building from source
+
+The C++ SDK uses CMake and depends on the Rust SDK being compiled first (via CXX bridge). See the [build instructions](https://github.com/apache/iggy/tree/master/foreign/cpp) in the repository for details.
+
+## Current status
+
+The SDK provides low-level access to stream, topic, and client management operations. Message sending and polling, consumer groups, and higher-level abstractions are being developed. Contributions are welcome.
diff --git a/content/docs/sdk/cpp/meta.json b/content/docs/sdk/cpp/meta.json
new file mode 100644
index 00000000..1ee8efca
--- /dev/null
+++ b/content/docs/sdk/cpp/meta.json
@@ -0,0 +1 @@
+{"title": "C++", "pages": ["intro"]}
diff --git a/content/docs/sdk/csharp/examples.mdx b/content/docs/sdk/csharp/examples.mdx
index 42f7ed41..4d97eddf 100644
--- a/content/docs/sdk/csharp/examples.mdx
+++ b/content/docs/sdk/csharp/examples.mdx
@@ -1,3 +1,50 @@
 ---
 title: Examples
 ---
+
+## Basic producer
+
+```csharp
+using Apache.Iggy;
+
+var client = new IggyClient("localhost:8090");
+await client.ConnectAsync();
+await client.LoginAsync("iggy", "iggy");
+
+// Create stream and topic if they don't exist
+await client.CreateStreamAsync("dev");
+await client.CreateTopicAsync("dev", "events", partitions: 2);
+
+// Send messages
+for (int i = 0; i < 100; i++)
+{
+    await client.SendMessagesAsync("dev", "events",
+        partitionId: 1,
+        messages: new[] { $"Event #{i}" });
+}
+
+Console.WriteLine("Sent 100 messages");
+```
+
+## Basic consumer
+
+```csharp
+using Apache.Iggy;
+
+var client = new IggyClient("localhost:8090");
+await client.ConnectAsync();
+await client.LoginAsync("iggy", "iggy");
+
+// Poll messages
+var messages = await client.PollMessagesAsync("dev", "events",
+    partitionId: 1,
+    offset: 0,
+    count: 100);
+
+foreach (var msg in messages)
+{
+    Console.WriteLine($"Offset: {msg.Offset}, Payload: {msg.PayloadAsString}");
+}
+```
+
+For the full source code, see the [examples/csharp](https://github.com/apache/iggy/tree/master/examples/csharp) directory.
diff --git a/content/docs/sdk/csharp/intro.mdx b/content/docs/sdk/csharp/intro.mdx
index ab6dd3a6..ba752a5d 100644
--- a/content/docs/sdk/csharp/intro.mdx
+++ b/content/docs/sdk/csharp/intro.mdx
@@ -1,5 +1,91 @@
 ---
-title: Intro
+title: C# SDK
 ---
 
-The Iggy SDK for C# is a library that allows you to interact with the Iggy API from your C# applications. This SDK provides a convenient way to interact with the Iggy API and allows you to easily integrate Iggy functionality into your C# applications. Repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/csharp).
+The Iggy SDK for C# is a library that allows you to interact with the Iggy API from your .NET applications. It communicates with the Iggy server over TCP using the binary protocol. The repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/csharp).
+
+## Installation
+
+```bash
+dotnet add package Apache.Iggy
+```
+
+## Quick start
+
+### Producer
+
+```csharp
+using Apache.Iggy;
+
+const string StreamName = "sample-stream";
+const string TopicName = "sample-topic";
+
+var client = IggyClientFactory.CreateClient(new IggyClientConfigurator()
+{
+    BaseAddress = "127.0.0.1:8090",
+    Protocol = Protocol.Tcp,
+});
+
+await client.LoginAsync("iggy", "iggy");
+
+await client.CreateStreamAsync(StreamName);
+await client.CreateTopicAsync(StreamName, TopicName, partitionsCount: 1);
+
+for (int i = 0; i < 10; i++)
+{
+    var payload = $"message-{i}";
+    await client.SendMessagesAsync(
+        StreamName,
+        TopicName,
+        partitionId: 1,
+        messages: new[] { new Message(payload) }
+    );
+}
+```
+
+### Consumer
+
+```csharp
+using Apache.Iggy;
+
+var client = IggyClientFactory.CreateClient(new IggyClientConfigurator()
+{
+    BaseAddress = "127.0.0.1:8090",
+    Protocol = Protocol.Tcp,
+});
+
+await client.LoginAsync("iggy", "iggy");
+
+ulong offset = 0;
+while (true)
+{
+    var messages = await client.PollMessagesAsync(
+        "sample-stream",
+        "sample-topic",
+        partitionId: 1,
+        pollingStrategy: PollingStrategy.Offset(offset),
+        count: 10
+    );
+
+    if (messages.Count == 0) break;
+
+    foreach (var msg in messages)
+    {
+        Console.WriteLine($"Offset: {msg.Offset}, Payload: {msg.PayloadAsString}");
+        offset = msg.Offset + 1;
+    }
+}
+```
+
+## Examples
+
+Working examples are available in the [examples/csharp](https://github.com/apache/iggy/tree/master/examples/csharp) directory. The following example sets are included:
+
+- **GettingStarted** - basic producer and consumer
+- **MessageEnvelope** - working with message envelopes
+- **MessageHeaders** - custom message headers
+- **MultiTenant** - multi-tenant streaming setup
+- **TcpTls** - TLS-encrypted TCP connections
+- **StreamBuilder** - stream builder API usage
+
+The solution can be opened with Visual Studio or built with `dotnet build`.
diff --git a/content/docs/sdk/go/examples.mdx b/content/docs/sdk/go/examples.mdx
index 42f7ed41..7b0c20ad 100644
--- a/content/docs/sdk/go/examples.mdx
+++ b/content/docs/sdk/go/examples.mdx
@@ -1,3 +1,129 @@
 ---
 title: Examples
 ---
+
+## Getting started
+
+A complete getting-started example is available in the [examples/go](https://github.com/apache/iggy/tree/master/examples/go) directory. It demonstrates connecting to the server, creating streams and topics, sending messages, and consuming them.
+
+### Producer
+
+```go
+package main
+
+import (
+	"fmt"
+	"time"
+
+	iggcon "github.com/apache/iggy-go/contracts"
+	client "github.com/apache/iggy-go"
+)
+
+const (
+	StreamName = "sample-stream"
+	TopicName  = "sample-topic"
+	StreamId   = 1
+	TopicId    = 1
+	Partition  = 1
+	MsgCount   = 10
+)
+
+func main() {
+	cli, err := client.NewIggyClient(client.WithTcp("127.0.0.1", 8090))
+	if err != nil {
+		panic(err)
+	}
+
+	if err = cli.LogIn(iggcon.LogInRequest{
+		Username: "iggy",
+		Password: "iggy",
+	}); err != nil {
+		panic(err)
+	}
+
+	if err = cli.CreateStream(iggcon.CreateStreamRequest{
+		StreamId: StreamId,
+		Name:     StreamName,
+	}); err != nil {
+		panic(err)
+	}
+
+	if err = cli.CreateTopic(iggcon.CreateTopicRequest{
+		StreamId:       iggcon.NewIdentifier(StreamId),
+		TopicId:        TopicId,
+		Name:           TopicName,
+		PartitionsCount: Partition,
+	}); err != nil {
+		panic(err)
+	}
+
+	for i := 0; i < MsgCount; i++ {
+		payload := fmt.Sprintf("message-%d", i)
+		message := iggcon.NewIggyMessage([]byte(payload))
+		if err = cli.SendMessages(iggcon.SendMessagesRequest{
+			StreamId:  iggcon.NewIdentifier(StreamId),
+			TopicId:   iggcon.NewIdentifier(TopicId),
+			Partition: iggcon.PartitioningRequest{Kind: 1, Value: []byte{byte(Partition)}},
+			Messages:  []iggcon.IggyMessage{message},
+		}); err != nil {
+			panic(err)
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+}
+```
+
+### Consumer
+
+```go
+package main
+
+import (
+	"fmt"
+
+	iggcon "github.com/apache/iggy-go/contracts"
+	client "github.com/apache/iggy-go"
+)
+
+func main() {
+	cli, err := client.NewIggyClient(client.WithTcp("127.0.0.1", 8090))
+	if err != nil {
+		panic(err)
+	}
+
+	if err = cli.LogIn(iggcon.LogInRequest{
+		Username: "iggy",
+		Password: "iggy",
+	}); err != nil {
+		panic(err)
+	}
+
+	var offset uint64 = 0
+	consumer := iggcon.DefaultConsumer()
+
+	for {
+		messages, err := cli.PollMessages(iggcon.FetchMessagesRequest{
+			StreamId:        iggcon.NewIdentifier(1),
+			TopicId:         iggcon.NewIdentifier(1),
+			Consumer:        consumer,
+			PartitionId:     1,
+			PollingStrategy: iggcon.OffsetPollingStrategy(offset),
+			Count:           10,
+		})
+		if err != nil {
+			panic(err)
+		}
+
+		if len(messages.Messages) == 0 {
+			break
+		}
+
+		for _, msg := range messages.Messages {
+			fmt.Printf("Offset: %d, Payload: %s\n", msg.Offset, string(msg.Payload))
+			offset = msg.Offset + 1
+		}
+	}
+}
+```
+
+For the full source code, see the [examples/go](https://github.com/apache/iggy/tree/master/examples/go) directory.
diff --git a/content/docs/sdk/go/intro.mdx b/content/docs/sdk/go/intro.mdx
index 005d049d..f4d90154 100644
--- a/content/docs/sdk/go/intro.mdx
+++ b/content/docs/sdk/go/intro.mdx
@@ -1,5 +1,61 @@
 ---
-title: Intro
+title: Go SDK
 ---
 
-The Iggy Go SDK is a client library that allows you to interact with the Iggy API from your Go application. Repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/go).
+The Iggy Go SDK is a client library that allows you to interact with the Iggy API from your Go application. It communicates with the Iggy server over TCP using the binary protocol. The repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/go).
+
+## Installation
+
+```bash
+go get github.com/apache/iggy/foreign/go
+```
+
+## Quick start
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+    iggy "github.com/apache/iggy/foreign/go"
+)
+
+func main() {
+    client, err := iggy.NewClient("localhost:8090")
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer client.Close()
+
+    err = client.Login("iggy", "iggy")
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Create a stream
+    err = client.CreateStream("my-stream")
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Create a topic with 2 partitions
+    err = client.CreateTopic("my-stream", "my-topic", 2)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Send a message
+    err = client.SendMessages("my-stream", "my-topic", 1,
+        [][]byte{[]byte("Hello from Go!")})
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Println("Message sent successfully")
+}
+```
+
+## Examples
+
+Working examples are available in the [examples/go](https://github.com/apache/iggy/tree/master/examples/go) directory, including a getting-started example with producer and consumer.
diff --git a/content/docs/sdk/introduction.mdx b/content/docs/sdk/introduction.mdx
index 37742398..b6d75cff 100644
--- a/content/docs/sdk/introduction.mdx
+++ b/content/docs/sdk/introduction.mdx
@@ -2,4 +2,109 @@
 title: Introduction
 ---
 
-This module contains the SDK-related components of the Apache Iggy message streaming infrastructure. Please note that some programming languages may not support all the lastest features of the Iggy Server.
+Iggy provides official client SDKs in multiple languages. The **Rust SDK** is the most feature-complete, offering both a high-level API (with auto-batching, consumer groups, offset management, retry logic) and a low-level API for direct protocol operations.
+
+| Language | Package | Registry | Transport | Connection string |
+|----------|---------|----------|-----------|-------------------|
+| Rust | [iggy](https://crates.io/crates/iggy) | crates.io | TCP, QUIC, HTTP, WebSocket | Yes |
+| Python | [apache-iggy](https://pypi.org/project/apache-iggy/) | PyPI | TCP, QUIC, HTTP, WebSocket | Yes (PyO3 wrapper) |
+| Java | [iggy](https://mvnrepository.com/artifact/org.apache.iggy/iggy) | Maven Central | TCP, HTTP | No |
+| Node.js | [apache-iggy](https://www.npmjs.com/package/apache-iggy) | npm | TCP | No |
+| Go | [iggy-go](https://pkg.go.dev/github.com/apache/iggy/foreign/go) | pkg.go.dev | TCP | No |
+| C# | [Apache.Iggy](https://www.nuget.org/packages/Apache.Iggy/) | NuGet | TCP, HTTP | No |
+| C++ | [iggy-cpp](https://github.com/apache/iggy/tree/master/foreign/cpp) | GitHub (WIP) | TCP, QUIC, HTTP, WebSocket | Yes (Rust FFI) |
+
+Python and C++ wrap the Rust SDK, so they inherit all transport protocols when using connection strings. Java and C# implement TCP and HTTP natively. Go and Node.js currently support TCP only.
+
+The Rust SDK is always the first to receive new features.
+
+## Connection string
+
+Connection strings are supported by Rust, Python, and C++ SDKs. They provide a compact way to configure the client, including the transport protocol, credentials, server address, and options.
+
+**Format:**
+
+```
+iggy://username:password@host:port[?options]
+```
+
+**Transport selection** via scheme:
+
+| Scheme | Transport |
+|--------|-----------|
+| `iggy://` | TCP (default) |
+| `iggy+tcp://` | TCP |
+| `iggy+quic://` | QUIC |
+| `iggy+http://` | HTTP |
+| `iggy+ws://` | WebSocket |
+
+**Personal Access Token** authentication:
+
+```
+iggy://iggypat-your-token-here@host:port
+```
+
+**Examples:**
+
+```rust
+// Rust - TCP with default options
+let client = IggyClient::from_connection_string("iggy://iggy:iggy@localhost:8090")?;
+
+// Rust - QUIC with TLS
+let client = IggyClient::from_connection_string("iggy+quic://iggy:iggy@localhost:8080")?;
+
+// Rust - TCP with options
+let client = IggyClient::from_connection_string(
+    "iggy://iggy:iggy@localhost:8090?tls=true&reconnection_retries=unlimited&heartbeat_interval=5s"
+)?;
+```
+
+```python
+# Python
+client = IggyClient.from_connection_string("iggy://iggy:iggy@localhost:8090")
+```
+
+**Available TCP options:** `tls`, `tls_domain`, `tls_ca_file`, `reconnection_retries` (number or `unlimited`), `reconnection_interval`, `reestablish_after`, `heartbeat_interval`, `nodelay`
+
+**Available QUIC options:** `response_buffer_size`, `max_concurrent_bidi_streams`, `datagram_send_buffer_size`, `initial_mtu`, `send_window`, `receive_window`, `keep_alive_interval`, `max_idle_timeout`, `validate_certificate`, `heartbeat_interval`, `reconnection_max_retries`, `reconnection_interval`
+
+**Available WebSocket options:** `tls`, `tls_domain`, `tls_ca_file`, `heartbeat_interval`, `reconnection_retries`, `reconnection_interval`, `read_buffer_size`, `write_buffer_size`, `max_message_size`, `max_frame_size`
+
+**Available HTTP options:** `heartbeat_interval`, `retries`
+
+## Common operations
+
+All SDKs provide the same core operations through the unified client interface:
+
+- **SystemClient** - ping, stats, snapshot
+- **StreamClient** - create, get, list, update, delete, purge streams
+- **TopicClient** - create, get, list, update, delete, purge topics
+- **PartitionClient** - create, delete partitions
+- **MessageClient** - send, poll messages
+- **ConsumerOffsetClient** - get, store, delete consumer offsets
+- **ConsumerGroupClient** - create, get, list, delete consumer groups
+- **UserClient** - create, get, list, update, delete users, change password, update permissions
+- **PersonalAccessTokenClient** - create, list, delete PATs
+- **ClusterClient** - cluster metadata
+
+## Polling strategies
+
+When polling messages, you can choose from several strategies:
+
+| Strategy | Description |
+|----------|-------------|
+| `offset(n)` | Start from a specific offset |
+| `timestamp(t)` | Start after a specific timestamp |
+| `first()` | Start from the earliest available message |
+| `last()` | Start from the latest message |
+| `next()` | Continue from the last committed offset |
+
+## Partitioning strategies
+
+When sending messages, you can control partition routing:
+
+| Strategy | Description |
+|----------|-------------|
+| `partition_id(n)` | Send to a specific partition |
+| `balanced()` | Round-robin across partitions |
+| `messages_key(key)` | Hash-based routing by key |
diff --git a/content/docs/sdk/java/intro.mdx b/content/docs/sdk/java/intro.mdx
index 92a88587..7b1f7bdc 100644
--- a/content/docs/sdk/java/intro.mdx
+++ b/content/docs/sdk/java/intro.mdx
@@ -1,6 +1,114 @@
 ---
-title: Intro
+title: Java SDK
 ---
 
-The Iggy Java SDK is a library that allows you to interact with the Iggy API from your Java application.
-Repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/java).
+The Iggy Java SDK is a library that allows you to interact with the Iggy API from your Java application. It communicates with the Iggy server over TCP using the binary protocol. The repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/java).
+
+## Installation
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>org.apache.iggy</groupId>
+    <artifactId>iggy</artifactId>
+    <version>LATEST</version>
+</dependency>
+```
+
+### Gradle
+
+```groovy
+implementation 'org.apache.iggy:iggy:LATEST'
+```
+
+## Quick start
+
+### Producer
+
+```java
+import org.apache.iggy.client.IggyTcpClient;
+import org.apache.iggy.message.Message;
+import org.apache.iggy.message.Partitioning;
+
+public class Producer {
+
+    static final String STREAM_NAME = "sample-stream";
+    static final String TOPIC_NAME = "sample-topic";
+
+    public static void main(String[] args) {
+        var client = IggyTcpClient.builder()
+                .host("localhost")
+                .port(8090)
+                .credentials("iggy", "iggy")
+                .buildAndLogin();
+
+        client.streams().createStream(STREAM_NAME);
+        client.topics().createTopic(STREAM_NAME, TOPIC_NAME, 1);
+
+        for (int i = 0; i < 10; i++) {
+            String payload = "message-" + i;
+            client.messages().sendMessages(
+                    STREAM_NAME,
+                    TOPIC_NAME,
+                    Partitioning.partitionId(1),
+                    Message.of(payload)
+            );
+        }
+
+        client.close();
+    }
+}
+```
+
+### Consumer
+
+```java
+import org.apache.iggy.client.IggyTcpClient;
+import org.apache.iggy.message.PollingStrategy;
+
+public class Consumer {
+
+    public static void main(String[] args) {
+        var client = IggyTcpClient.builder()
+                .host("localhost")
+                .port(8090)
+                .credentials("iggy", "iggy")
+                .buildAndLogin();
+
+        long offset = 0;
+        while (true) {
+            var messages = client.messages().pollMessages(
+                    "sample-stream",
+                    "sample-topic",
+                    1,
+                    PollingStrategy.offset(offset),
+                    10
+            );
+            if (messages.isEmpty()) {
+                break;
+            }
+            for (var msg : messages) {
+                System.out.printf("Offset: %d, Payload: %s%n",
+                        msg.offset(), new String(msg.payload()));
+                offset = msg.offset() + 1;
+            }
+        }
+
+        client.close();
+    }
+}
+```
+
+## Examples
+
+Working examples are available in the [examples/java](https://github.com/apache/iggy/tree/master/examples/java) directory as a Gradle project. The following example sets are included:
+
+- **getting-started** - basic producer and consumer
+- **async** - asynchronous message processing
+- **message-envelope** - working with message envelopes
+- **message-headers** - custom message headers
+- **multi-tenant** - multi-tenant streaming setup
+- **tcp-tls** - TLS-encrypted TCP connections
+- **sink-data-producer** - data sink producer pattern
+- **stream-builder** - stream builder API usage
diff --git a/content/docs/sdk/meta.json b/content/docs/sdk/meta.json
index f051d4cf..639508ad 100644
--- a/content/docs/sdk/meta.json
+++ b/content/docs/sdk/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "SDK",
-  "pages": ["introduction", "csharp", "go", "node", "java", "python", "rust"]
+  "pages": ["introduction", "rust", "python", "java", "go", "node", "csharp", "cpp"]
 }
diff --git a/content/docs/sdk/node/intro.mdx b/content/docs/sdk/node/intro.mdx
index 8209fba9..89039155 100644
--- a/content/docs/sdk/node/intro.mdx
+++ b/content/docs/sdk/node/intro.mdx
@@ -1,5 +1,99 @@
 ---
-title: Intro
+title: Node.js SDK
 ---
 
-The Iggy Node.js SDK is a client library that allows you to interact with the Iggy API from your Node.js applications. This guide will help you get started with the SDK and show you how to use it to interact with the Iggy API. Repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/node).
+The Iggy Node.js SDK is a client library that allows you to interact with the Iggy API from your Node.js and TypeScript applications. It communicates with the Iggy server over TCP using the binary protocol. The repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/node).
+
+## Installation
+
+```bash
+npm install apache-iggy
+```
+
+## Quick start
+
+### Producer
+
+```typescript
+import { Client, Partitioning } from 'apache-iggy';
+
+const STREAM_NAME = 'sample-stream';
+const TOPIC_NAME = 'sample-topic';
+
+const client = new Client({
+  transport: 'TCP',
+  options: {
+    port: 8090,
+    host: '127.0.0.1',
+  },
+  credentials: {
+    username: 'iggy',
+    password: 'iggy',
+  },
+});
+
+await client.stream.create({ name: STREAM_NAME });
+await client.topic.create({
+  streamId: STREAM_NAME,
+  name: TOPIC_NAME,
+  partitionsCount: 1,
+});
+
+for (let i = 0; i < 10; i++) {
+  const payload = `message-${i}`;
+  await client.message.send({
+    streamId: STREAM_NAME,
+    topicId: TOPIC_NAME,
+    partitioning: Partitioning.PartitionId(1),
+    messages: [{ payload: Buffer.from(payload) }],
+  });
+}
+```
+
+### Consumer
+
+```typescript
+import { Client, PollingStrategy } from 'apache-iggy';
+
+const client = new Client({
+  transport: 'TCP',
+  options: {
+    port: 8090,
+    host: '127.0.0.1',
+  },
+  credentials: {
+    username: 'iggy',
+    password: 'iggy',
+  },
+});
+
+let offset = 0n;
+while (true) {
+  const messages = await client.message.poll({
+    streamId: 'sample-stream',
+    topicId: 'sample-topic',
+    partitionId: 1,
+    pollingStrategy: PollingStrategy.Offset(offset),
+    count: 10,
+  });
+
+  if (messages.length === 0) break;
+
+  for (const msg of messages) {
+    console.log(`Offset: ${msg.offset}, Payload: ${msg.payload.toString()}`);
+    offset = msg.offset + 1n;
+  }
+}
+```
+
+## Examples
+
+Working examples are available in the [examples/node](https://github.com/apache/iggy/tree/master/examples/node) directory, written in TypeScript. The following example sets are included:
+
+- **getting-started** - basic producer and consumer
+- **async** - asynchronous message processing
+- **message-envelope** - working with message envelopes
+- **message-headers** - custom message headers
+- **multi-tenant** - multi-tenant streaming setup
+- **tcp-tls** - TLS-encrypted TCP connections
+- **stream-builder** - stream builder API usage
diff --git a/content/docs/sdk/python/intro.mdx b/content/docs/sdk/python/intro.mdx
index e1e63187..0eae501a 100644
--- a/content/docs/sdk/python/intro.mdx
+++ b/content/docs/sdk/python/intro.mdx
@@ -1,5 +1,74 @@
 ---
-title: Intro
+title: Python SDK
 ---
 
-The Iggy Python SDK is a client library that allows you to interact with the Iggy API from your Python application. Repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/python).
+The Iggy Python SDK is a client library that allows you to interact with the Iggy API from your Python application. It is built as a PyO3 wrapper around the Rust SDK, which means it supports TCP, QUIC, and HTTP transports. The repository can be found [here](https://github.com/apache/iggy/tree/master/foreign/python).
+
+## Installation
+
+```bash
+pip install apache-iggy
+```
+
+## Quick start
+
+### Producer
+
+```python
+from apache_iggy import IggyClient, SendMessage
+
+STREAM_NAME = "sample-stream"
+TOPIC_NAME = "sample-topic"
+
+client = IggyClient.from_connection_string("iggy://iggy:iggy@localhost:8090")
+await client.connect()
+
+await client.create_stream(name=STREAM_NAME)
+await client.create_topic(
+    stream=STREAM_NAME,
+    name=TOPIC_NAME,
+    partitions_count=1,
+)
+
+for i in range(10):
+    payload = f"message-{i}"
+    message = SendMessage(payload=payload.encode())
+    await client.send_messages(
+        stream=STREAM_NAME,
+        topic=TOPIC_NAME,
+        partition_id=1,
+        messages=[message],
+    )
+```
+
+### Consumer
+
+```python
+from apache_iggy import IggyClient, PollingStrategy
+
+STREAM_NAME = "sample-stream"
+TOPIC_NAME = "sample-topic"
+
+client = IggyClient.from_connection_string("iggy://iggy:iggy@localhost:8090")
+await client.connect()
+
+offset = 0
+while True:
+    messages = await client.poll_messages(
+        stream=STREAM_NAME,
+        topic=TOPIC_NAME,
+        partition_id=1,
+        polling_strategy=PollingStrategy.offset(offset),
+        count=10,
+    )
+    if not messages:
+        break
+
+    for msg in messages:
+        print(f"Offset: {msg.offset}, Payload: {msg.payload}")
+        offset = msg.offset + 1
+```
+
+## Examples
+
+Working examples are available in the [examples/python](https://github.com/apache/iggy/tree/master/examples/python) directory.
diff --git a/content/docs/sdk/rust/intro.mdx b/content/docs/sdk/rust/intro.mdx
index 2609960e..f7e63f01 100644
--- a/content/docs/sdk/rust/intro.mdx
+++ b/content/docs/sdk/rust/intro.mdx
@@ -2,6 +2,112 @@
 title: Intro
 ---
 
-To learn more about the Rust SDK, please check the [getting started](/docs/introduction/getting-started) guide. The SDK is available on [crates.io](https://crates.io/crates/iggy) and the source code can be is part of the [core repository](https://github.com/apache/iggy/), located under `sdk` directory.
+The Rust SDK is the primary and most feature-complete client for Iggy. It is available on [crates.io](https://crates.io/crates/iggy) and the source code is part of the [core repository](https://github.com/apache/iggy/tree/master/core/sdk).
 
-To start using the Iggy SDK in your Rust project, simply run `cargo add iggy`.
+```bash
+cargo add iggy
+```
+
+## High-level vs low-level API
+
+The SDK provides two layers:
+
+**High-level API (recommended)** - the easiest way to get started. It handles connection management, auto-batching, consumer group lifecycle, offset commits, retry logic, and reconnection out of the box. Use `IggyClient`, `IggyProducer`, and `IggyConsumer` for the best developer experience.
+
+```rust
+use iggy::prelude::*;
+
+// Connect with a connection string
+let client = IggyClient::from_connection_string("iggy://iggy:iggy@localhost:8090")?;
+client.connect().await?;
+
+// Or use the builder
+let client = IggyClientBuilder::new()
+    .with_tcp()
+    .with_server_address("localhost:8090".to_string())
+    .build()?;
+client.connect().await?;
+client.login_user("iggy", "iggy").await?;
+```
+
+**Low-level API** - direct access to individual protocol operations. Useful when you need fine-grained control over every request, or when building custom abstractions on top.
+
+The high-level API is built on top of the low-level one, so you can always drop down when needed.
+
+## Connection string
+
+The connection string is the simplest way to configure the client. It supports all four transport protocols:
+
+```
+iggy://user:pass@host:port              (TCP, default)
+iggy+tcp://user:pass@host:port          (TCP, explicit)
+iggy+quic://user:pass@host:port         (QUIC)
+iggy+http://user:pass@host:port         (HTTP)
+iggy+ws://user:pass@host:port           (WebSocket)
+```
+
+Options can be appended as query parameters:
+
+```
+iggy://iggy:iggy@my-server:8090?tls=true&tls_ca_file=/path/to/ca.crt
+iggy://iggy:iggy@localhost:8090?reconnection_retries=unlimited&heartbeat_interval=5s
+```
+
+Personal Access Tokens are also supported:
+
+```
+iggy://iggypat-your-token@localhost:8090
+```
+
+## Quick example
+
+```rust
+use iggy::prelude::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = IggyClient::from_connection_string("iggy://iggy:iggy@localhost:8090")?;
+    client.connect().await?;
+
+    // Create stream and topic
+    client.create_stream("my-stream").await?;
+    client.create_topic(
+        &"my-stream".try_into()?,
+        "my-topic",
+        2,
+        CompressionAlgorithm::None,
+        None,
+        IggyExpiry::NeverExpire,
+        MaxTopicSize::ServerDefault,
+    ).await?;
+
+    // Send a message
+    let msg = IggyMessage::from_str("hello world")?;
+    client.send_messages(
+        &"my-stream".try_into()?,
+        &"my-topic".try_into()?,
+        &Partitioning::balanced(),
+        &mut [msg],
+    ).await?;
+
+    // Poll messages
+    let polled = client.poll_messages(
+        &"my-stream".try_into()?,
+        &"my-topic".try_into()?,
+        Some(1),
+        &Consumer::default(),
+        &PollingStrategy::offset(0),
+        10,
+        false,
+    ).await?;
+
+    for message in &polled.messages {
+        let payload = std::str::from_utf8(&message.payload)?;
+        println!("Offset: {}, Payload: {}", message.header.offset, payload);
+    }
+
+    Ok(())
+}
+```
+
+For the full getting started tutorial, see [Getting Started](/docs/introduction/getting-started). For the high-level producer/consumer builders, see [High-level SDK](/docs/sdk/rust/high-level-sdk) and [Stream Builder](/docs/sdk/rust/stream-builder).
diff --git a/content/docs/server/configuration.mdx b/content/docs/server/configuration.mdx
index 091ad3c3..2c8218bb 100644
--- a/content/docs/server/configuration.mdx
+++ b/content/docs/server/configuration.mdx
@@ -584,11 +584,60 @@ cert_file = "core/certs/iggy_cert.pem"
 key_file = "core/certs/iggy_key.pem"
 ```
 
+### Environment variables
+
+Every configuration option can be overridden using environment variables with the `IGGY_` prefix. The naming convention follows the TOML structure with underscores:
+
+```bash
+IGGY_TCP_ADDRESS=0.0.0.0:8090
+IGGY_HTTP_ENABLED=true
+IGGY_SYSTEM_PATH=/data/iggy
+IGGY_SYSTEM_SHARDING_CPU_ALLOCATION="Count:4"
+IGGY_ROOT_USERNAME=iggy
+IGGY_ROOT_PASSWORD=my-secret-password
+```
+
+### Command-line arguments
+
+The server binary accepts the following arguments:
+
+| Argument | Description |
+|----------|-------------|
+| `--config-provider file` | Configuration source (default: file) |
+| `--fresh` | Wipe data directory before start |
+| `--with-default-root-credentials` | Set root to iggy/iggy (dev only) |
+| `--follower` | Advertise as follower node (clustering) |
+
 ### Durability
 
 The single node `Iggy` server by default provides low durability guarantees, meaning that in case of a crash or power loss, some of messages might be lost.
-To fix that you can enable `enforce_fsync` option in `system.partition` section together with setting `messages_required_to_save` and `size_of_messages_required_to_save` to lowest allowed values.
-Since `messages_required_to_save` has to be at least 32 and `size_of_messages_required_to_save` at least 512 B, in case if your message size is not big enough, you might want to pad your message to 512 B boundary, or alternatively send messages in batches.
+To fix that you can enable `enforce_fsync` option in `system.partition` section together with setting `messages_required_to_save` and `size_of_messages_required_to_save` to lowest allowed values (minimum of 1 for count, and 512 B for size). In case if your message size is not big enough, you might want to pad your message to 512 B boundary, or alternatively send messages in batches.
+
+For even stronger durability, enable the `message_saver` with `enforce_fsync = true` which provides a background fsync at a configurable interval (default 30s).
+
+### Sharding
+
+The `[system.sharding]` section controls how the server maps shards to CPU cores. This is key to the thread-per-core architecture:
+
+- `"all"` - one shard per available CPU core
+- A numeric value (e.g. `4`) - exactly N shards
+- A range (e.g. `"5..8"`) - shards on cores 5, 6, 7
+- `"numa:auto"` - automatic NUMA-aware allocation
+- `"numa:nodes=0,1;cores=4;no_ht=true"` - fine-grained NUMA control
+
+See [Architecture](/docs/introduction/architecture) for more details on the thread-per-core design.
+
+### Memory pool
+
+The `[system.memory_pool]` section configures the pre-allocated buffer pool used for zero-copy message passing:
+
+- `size` - total pool size (minimum 512 MiB, must be page-aligned to 4096 bytes)
+- `bucket_capacity` - buffers per bucket (must be power of 2, minimum 128)
+- The pool has 32 buckets with buffer sizes from 256 B to 512 MiB
+
+### Clustering
+
+The `[cluster]` section configures multi-node replication using Viewstamped Replication (VSR). See [Clustering](/docs/clustering/vsr) for details. When clustering is enabled, all nodes must share the same cluster `name`.
 
 ### HTTP
 
@@ -600,25 +649,34 @@ To consume the HTTP API from Iggy SDK, you need to make use of the available `Ht
 
 HTTP API is highly performant, however, it's not as performant as TCP, and, since it's a stateless protocol, there's no such thing as the ongoing connection between client and server, thus some of the features such as consumer groups are not available.
 
+The HTTP server also hosts **Prometheus metrics** at `/metrics` (configurable) and the optional **embedded Web UI** at `/ui` (when compiled with `iggy-web` feature and `web_ui = true`).
+
 ### TCP
 
 An optional transport layer, which can be used to connect to the server with any tool or application that supports TCP. It is enabled by default, but you can disable it by setting `enabled` to `false`. The `address` option specifies the address and port to listen on.
 
 TCP provides the highest performance and throughput as it works directly with the binary data without an additional overhead of e.g. HTTP spec along with the JSON serialization.
 
+When `socket_migration` is enabled (default), TCP sockets can be migrated between shards to avoid cross-shard forwarding of data plane operations.
+
 To consume the TCP API from Iggy SDK, you need to make use of the available `TcpClient` component.
 
 ### QUIC
 
 An optional transport layer, which can be used to connect to the server with any tool or application that supports QUIC. It is enabled by default, but you can disable it by setting `enabled` to `false`. The `address` option specifies the address and port to listen on.
 
-Similar to TCP it's a stateful protocol, however, it's not as performant as TCP. QUIC support is built on top of [Quinn](https://github.com/quinn-rs/quinn) library, and all the remaining options are essentially the direct mapping of the options available in Quinn. QUIC and TCP use the same custom binary protocol specification.
+Similar to TCP it's a stateful protocol, however, it's not as performant as TCP. QUIC support is built on top of [Quinn](https://github.com/quinn-rs/quinn) library, and all the remaining options are essentially the direct mapping of the options available in Quinn. QUIC and TCP use the same custom binary protocol specification. QUIC has built-in mandatory TLS encryption.
 
 To consume the QUIC API from Iggy SDK, you need to make use of the available `QuicClient` component.
 
-
 ### WebSocket
 
 An optional transport layer, which can be used to connect to the server with any tool or application that supports WebSocket. It is enabled by default, but you can disable it by setting `enabled` to `false`. The `address` option specifies the address and port to listen on.
 
+WebSocket uses a custom `compio-ws` implementation that bridges tungstenite with compio's completion-based I/O model. It runs on all shards and supports optional TLS.
+
 To consume the WebSocket API from Iggy SDK, you need to make use of the available `WebSocketClient` component.
+
+### Telemetry
+
+The `[telemetry]` section configures OpenTelemetry integration for logs and traces. Supports both gRPC and HTTP transports for sending data to your observability backend (e.g. Jaeger, Grafana Tempo, Loki).
diff --git a/content/docs/server/docker.mdx b/content/docs/server/docker.mdx
index 79f0b2de..0347f0d4 100644
--- a/content/docs/server/docker.mdx
+++ b/content/docs/server/docker.mdx
@@ -1,13 +1,14 @@
 ---
-title: Docker
+title: Docker & Helm
 ---
 
+## Docker
+
 You can easily run the Iggy server with Docker - the official images can be found [here](https://hub.docker.com/r/apache/iggy), simply type `docker pull apache/iggy`.
 
 Below is an example of the `docker-compose.yml` file which additionally overrides the default configuration (described in the section below) with the environment variables. If you prefer using the configuration file, you can mount it as a volume and provide the path to it with the `IGGY_CONFIG_PATH` environment variable.
 
-When running the container, **make sure to include the additional capabilities**, as you can find in [docker-compose](https://github.com/apache/iggy/blob/master/docker-compose.yml) file:
-
+When running the container, **make sure to include the additional capabilities** required by `io_uring` and CPU affinity:
 
 ```yaml
 iggy:
@@ -53,3 +54,90 @@ Or when running with `docker run`:
 ```
 docker run --cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 apache/iggy:edge
 ```
+
+### Why these capabilities?
+
+- **`SYS_NICE`** - required for setting CPU affinity (`sched_setaffinity`) in the thread-per-core architecture
+- **`seccomp:unconfined`** - required for `io_uring` syscalls which are blocked by Docker's default seccomp profile
+- **`memlock: -1`** - `io_uring` needs to lock memory pages shared between user space and kernel
+
+### Available images
+
+| Image | Description |
+|-------|-------------|
+| `apache/iggy` | Server + CLI |
+| `apache/iggy-web-ui` | Standalone Web UI |
+| `apache/iggy-connect` | Connectors runtime |
+| `apache/iggy-mcp` | MCP server |
+
+Images tagged `latest` are based on stable releases. Images tagged `edge` are built from the latest `master` branch.
+
+### Building from source
+
+The Dockerfile uses a multi-stage build: Rust compilation (including the Web UI via npm), then a minimal Debian slim image. To build:
+
+```bash
+docker build -t iggy .
+```
+
+Or use `docker compose up` directly from the repository root.
+
+### Running the CLI inside the container
+
+```bash
+docker exec -it iggy-server /iggy -u iggy -p iggy stream list
+```
+
+## Helm charts
+
+Helm charts for Kubernetes deployment are available in the [repository](https://github.com/apache/iggy/tree/master/helm/charts/iggy).
+
+### Quick start
+
+```bash
+helm install iggy ./helm/charts/iggy
+```
+
+### Chart components
+
+The chart includes templates for:
+
+- **Deployment** - the Iggy server pod with required security context (SYS_NICE, seccomp unconfined, unlimited memlock)
+- **Service** - exposes TCP (8090), QUIC (8080), HTTP (3000), and WebSocket (8092) ports
+- **ServiceAccount** - dedicated service account
+- **PersistentVolumeClaim** - persistent storage for `local_data`
+- **HPA** - Horizontal Pod Autoscaler (optional)
+- **Ingress** - optional ingress for HTTP access
+- **ServiceMonitor** - Prometheus ServiceMonitor for metrics collection (optional)
+- **Secret** - root user credentials
+
+### Key values
+
+```yaml
+# values.yaml (excerpt)
+replicaCount: 1
+
+image:
+  repository: apache/iggy
+  tag: latest
+
+persistence:
+  enabled: true
+  size: 10Gi
+
+resources:
+  limits:
+    memory: 8Gi
+  requests:
+    cpu: 2
+    memory: 4Gi
+
+serviceMonitor:
+  enabled: false
+```
+
+Customize the values file for your environment and deploy with:
+
+```bash
+helm install iggy ./helm/charts/iggy -f my-values.yaml
+```
diff --git a/content/docs/server/introduction.mdx b/content/docs/server/introduction.mdx
index ae5d8ded..5add78d8 100644
--- a/content/docs/server/introduction.mdx
+++ b/content/docs/server/introduction.mdx
@@ -2,10 +2,10 @@
 title: Introduction
 ---
 
-## Introduction
-
 Iggy server is the most important part of the system as it's responsible for handling all the incoming connections, managing the data and providing the API for the clients. The server is written in Rust and can be run on any platform that supports it.
 
+<ServerEcosystem />
+
 The releases are published to GitHub and can be found [here](https://github.com/apache/iggy/tags). The official Docker images can be found [here](https://hub.docker.com/r/apache/iggy), simply type `docker pull apache/iggy`.
 
 Keep in mind, that if you were to compile the source code in release mode, the longer compilation time is due to [LTO](https://doc.rust-lang.org/rustc/linker-plugin-lto.html) enabled in [profile](https://github.com/apache/iggy/blob/master/Cargo.toml#L2).
diff --git a/content/docs/server/meta.json b/content/docs/server/meta.json
index d346d70c..4457c8e1 100644
--- a/content/docs/server/meta.json
+++ b/content/docs/server/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Server",
-  "pages": ["introduction", "configuration", "docker", "schema", "benchmarking"]
+  "pages": ["introduction", "configuration", "storage-engine", "networking", "security", "docker", "schema", "benchmarking"]
 }
diff --git a/content/docs/server/networking.mdx b/content/docs/server/networking.mdx
new file mode 100644
index 00000000..ce8b3239
--- /dev/null
+++ b/content/docs/server/networking.mdx
@@ -0,0 +1,139 @@
+---
+title: Networking
+---
+
+Iggy supports four transport protocols simultaneously, each optimized for different use cases. All stateful protocols (TCP, QUIC, WebSocket) use the same custom binary wire protocol, while HTTP provides a standard REST API.
+
+<ShardDiagram />
+
+## Transport protocols
+
+| Protocol | Default Address | Implementation | Best for |
+|----------|----------------|----------------|----------|
+| TCP | `127.0.0.1:8090` | compio + custom binary framing | Highest throughput, lowest latency |
+| QUIC | `127.0.0.1:8080` | compio-quic (quinn) | Secure connections, multiplexing |
+| HTTP | `127.0.0.1:3000` | axum | REST API, web integrations |
+| WebSocket | `127.0.0.1:8092` | compio-ws | Browser clients, bidirectional streaming |
+
+**Performance ranking** (lowest to highest overhead): TCP > QUIC > WebSocket > HTTP
+
+## Binary protocol
+
+TCP, QUIC, and WebSocket all use the same binary protocol format. Each request/response frame consists of:
+
+```
+┌──────────────────┬────────────────────┬──────────────────┐
+│ Command Code     │ Payload Length     │ Payload          │
+│ (4 bytes, LE)    │ (4 bytes, LE)      │ (N bytes)        │
+└──────────────────┴────────────────────┴──────────────────┘
+```
+
+The `iggy_binary_protocol` crate provides zero-copy serialization for all protocol frames. Foreign SDKs implement this protocol natively.
+
+## Protocol distribution across shards
+
+The transport servers are distributed across shards based on their requirements:
+
+- **Shard 0**: HTTP server (axum) and QUIC server
+- **All shards**: TCP and WebSocket servers
+
+This distribution means TCP and WebSocket connections can be served by any shard, which works well with TCP socket migration.
+
+## TCP
+
+TCP provides the highest performance as it works directly with binary data without the overhead of HTTP or TLS handshakes (unless TLS is enabled). Key features:
+
+- **Socket migration**: when enabled (default), TCP sockets can be migrated between shards. If a client's request targets a partition owned by a different shard, the socket moves to the owning shard instead of forwarding the request, eliminating cross-shard hops on the data path.
+- **IPv6 support**: configurable via `ipv6 = true`
+- **Socket tuning**: configurable buffer sizes, keepalive, nodelay (Nagle algorithm), and linger timeout
+
+```toml
+[tcp]
+enabled = true
+address = "127.0.0.1:8090"
+socket_migration = true
+ipv6 = false
+
+[tcp.tls]
+enabled = false
+self_signed = true
+cert_file = "core/certs/iggy_cert.pem"
+key_file = "core/certs/iggy_key.pem"
+
+[tcp.socket]
+override_defaults = false
+recv_buffer_size = "100 KB"
+send_buffer_size = "100 KB"
+keepalive = false
+nodelay = false
+linger = "0 s"
+```
+
+## QUIC
+
+QUIC provides built-in TLS encryption and stream multiplexing. It uses the same binary protocol as TCP but runs over UDP. QUIC support is built on top of the quinn library. While not quite as fast as TCP, QUIC provides better security out of the box (TLS is mandatory).
+
+```toml
+[quic]
+enabled = true
+address = "127.0.0.1:8080"
+max_concurrent_bidi_streams = 10_000
+datagram_send_buffer_size = "100 KB"
+initial_mtu = "8 KB"
+send_window = "100 KB"
+receive_window = "100 KB"
+keep_alive_interval = "5 s"
+max_idle_timeout = "10 s"
+
+[quic.certificate]
+self_signed = true
+cert_file = "core/certs/iggy_cert.pem"
+key_file = "core/certs/iggy_key.pem"
+```
+
+## HTTP
+
+The HTTP API is built on [axum](https://github.com/tokio-rs/axum) and provides a standard REST interface. It includes JWT authentication, Prometheus metrics, CORS configuration, and optional TLS.
+
+HTTP is the most accessible protocol but has the highest overhead due to JSON serialization and the stateless nature of HTTP (no persistent connections for consumer groups). You can find all the available endpoints in the [server.http](https://github.com/apache/iggy/blob/master/core/server/server.http) file.
+
+The HTTP server also hosts:
+- **Prometheus metrics** at `/metrics` (configurable endpoint)
+- **Embedded Web UI** at `/ui` (when compiled with `iggy-web` feature)
+
+## WebSocket
+
+WebSocket provides bidirectional streaming over HTTP upgrade. Iggy uses a custom `compio-ws` implementation that bridges the gap between tungstenite's poll-based model and compio's completion-based model.
+
+The challenge was fundamental: traditional WebSocket libraries expect `std::io::Read` (caller owns the buffer), while compio's `AsyncRead` takes ownership of the buffer (kernel owns it temporarily). The solution is a `GrowableSyncStream` that dynamically grows from a 128 KB base, with linear growth in base capacity increments, a 64 MB cap, and auto-shrink when the buffer exceeds 4x the base and data is consumed.
+
+WebSocket runs on all shards (not just shard 0) and supports optional TLS.
+
+**Benchmark comparison** (AWS i3en.3xlarge, fsync per message, 4 producers, 40M messages):
+- Producer avg latency: TCP 2.61ms vs WebSocket 3.43ms (+31%)
+- Consumer avg latency: TCP 0.70ms vs WebSocket 1.44ms (+106%)
+
+## TLS
+
+All transport protocols support TLS encryption:
+
+| Transport | TLS Mechanism |
+|-----------|---------------|
+| TCP | Optional, via rustls |
+| QUIC | Built-in, mandatory (part of QUIC spec) |
+| HTTP | Optional HTTPS |
+| WebSocket | Inherits from its transport |
+
+All protocols support self-signed certificate generation when `self_signed = true` and the cert files don't exist. For production, provide proper certificate files via the `cert_file` and `key_file` settings.
+
+## Heartbeat
+
+An optional heartbeat mechanism can verify client liveness:
+
+```toml
+[heartbeat]
+enabled = false
+interval = "5 s"
+```
+
+When enabled, the server expects periodic heartbeat messages from connected clients. Clients that miss heartbeats may be disconnected.
diff --git a/content/docs/server/schema.mdx b/content/docs/server/schema.mdx
index 690b1bb4..7e821a7b 100644
--- a/content/docs/server/schema.mdx
+++ b/content/docs/server/schema.mdx
@@ -8,6 +8,8 @@ Currently, there are 2 ways of data representation: JSON (text) and binary - any
 
 The binary format is more compact and efficient, but it is not human-readable - it's being used by TCP and QUIC transports. The JSON format is used by HTTP transport - all the existing endpoints are available in the [server.http](https://github.com/apache/iggy/blob/master/core/server/server.http).
 
+All multi-byte integer fields use **little-endian** encoding throughout.
+
 ## Request schema
 
 All the requests are represented as a binary message. The message consists of 3 parts: length, code and payload:
@@ -44,62 +46,88 @@ graph LR
 ## Request codes
 
 ```bash
-PING = 1;
-GET_STATS = 10;
-GET_SNAPSHOT_FILE = 11;
-GET_ME = 20;
-GET_CLIENT = 21;
-GET_CLIENTS = 22;
-GET_USER = 31;
-GET_USERS = 32;
-CREATE_USER = 33;
-DELETE_USER = 34;
-UPDATE_USER = 35;
-UPDATE_PERMISSIONS = 36;
-CHANGE_PASSWORD = 37;
-LOGIN_USER = 38;
-LOGOUT_USER = 39;
-GET_PERSONAL_ACCESS_TOKENS = 41;
-CREATE_PERSONAL_ACCESS_TOKEN = 42;
-DELETE_PERSONAL_ACCESS_TOKEN = 43;
-LOGIN_WITH_PERSONAL_ACCESS_TOKEN = 44;
-POLL_MESSAGES = 100;
-SEND_MESSAGES = 101;
-FLUSH_UNSAVED_BUFFER = 102;
-GET_CONSUMER_OFFSET = 120;
-STORE_CONSUMER_OFFSET = 121;
-GET_STREAM = 200;
-GET_STREAMS = 201;
-CREATE_STREAM = 202;
-DELETE_STREAM = 203;
-UPDATE_STREAM = 204;
-PURGE_STREAM = 205;
-GET_TOPIC = 300;
-GET_TOPICS = 301;
-CREATE_TOPIC = 302;
-DELETE_TOPIC = 303;
-UPDATE_TOPIC = 304;
-PURGE_TOPIC = 305;
-CREATE_PARTITIONS = 402;
-DELETE_PARTITIONS = 403;
-GET_CONSUMER_GROUP = 600;
-GET_CONSUMER_GROUPS = 601;
-CREATE_CONSUMER_GROUP = 602;
-DELETE_CONSUMER_GROUP = 603;
-JOIN_CONSUMER_GROUP = 604;
-LEAVE_CONSUMER_GROUP = 605;
+PING = 1
+GET_STATS = 10
+GET_SNAPSHOT = 11
+GET_CLUSTER_METADATA = 12
+GET_ME = 20
+GET_CLIENT = 21
+GET_CLIENTS = 22
+GET_USER = 31
+GET_USERS = 32
+CREATE_USER = 33
+DELETE_USER = 34
+UPDATE_USER = 35
+UPDATE_PERMISSIONS = 36
+CHANGE_PASSWORD = 37
+LOGIN_USER = 38
+LOGOUT_USER = 39
+GET_PERSONAL_ACCESS_TOKENS = 41
+CREATE_PERSONAL_ACCESS_TOKEN = 42
+DELETE_PERSONAL_ACCESS_TOKEN = 43
+LOGIN_WITH_PERSONAL_ACCESS_TOKEN = 44
+POLL_MESSAGES = 100
+SEND_MESSAGES = 101
+FLUSH_UNSAVED_BUFFER = 102
+GET_CONSUMER_OFFSET = 120
+STORE_CONSUMER_OFFSET = 121
+DELETE_CONSUMER_OFFSET = 122
+GET_STREAM = 200
+GET_STREAMS = 201
+CREATE_STREAM = 202
+DELETE_STREAM = 203
+UPDATE_STREAM = 204
+PURGE_STREAM = 205
+GET_TOPIC = 300
+GET_TOPICS = 301
+CREATE_TOPIC = 302
+DELETE_TOPIC = 303
+UPDATE_TOPIC = 304
+PURGE_TOPIC = 305
+CREATE_PARTITIONS = 402
+DELETE_PARTITIONS = 403
+DELETE_SEGMENTS = 503
+GET_CONSUMER_GROUP = 600
+GET_CONSUMER_GROUPS = 601
+CREATE_CONSUMER_GROUP = 602
+DELETE_CONSUMER_GROUP = 603
+JOIN_CONSUMER_GROUP = 604
+LEAVE_CONSUMER_GROUP = 605
 ```
 
 ## Shared
 
 ---
 
+### Identifier
+
+```rust
+pub struct Identifier {
+    pub kind: IdKind,
+    pub length: u8,
+    pub value: Vec<u8>
+}
+
+pub enum IdKind {
+    Numeric,  // Value = 1 (default)
+    String    // Value = 2
+}
+```
+
+The `Identifier` is a struct which represents the identifier of a stream, topic, user, or consumer group. It consists of the `kind` (numeric or string), `length` (length of the identifier value) and `value` (actual value of the identifier). The `value` is a vector of bytes, which can be either a numeric value (e.g. 1 encoded as const 4 bytes for u32 type) or a string (e.g. "my-stream") with variable length of UTF-8 string, maximum 255 bytes (chars).
+
+**Serialization**
+
+- `kind` - 1 byte
+- `length` - 1 byte
+- `value` - N bytes (4 bytes for numeric, 1-255 bytes for string)
+
 ### Consumer
 
 ```rust
 pub struct Consumer {
     pub kind: ConsumerKind,
-    pub id: u32,
+    pub id: Identifier,
 }
 
 pub enum ConsumerKind {
@@ -108,35 +136,48 @@ pub enum ConsumerKind {
 }
 ```
 
-The `Consumer` is a simple structs which represents the type of the consumer. It can be either a consumer or a consumer group. This type is used when interacting with the messages related commands  data such as `PollMessages`, `GetConsumerOffset` and `StoreConsumerOffset`.
+The `Consumer` represents the type of the consumer. It can be either a consumer or a consumer group. This type is used when interacting with the messages related commands such as `PollMessages`, `GetConsumerOffset`, `StoreConsumerOffset` and `DeleteConsumerOffset`.
 
 **Serialization**
 
 - `kind` - 1 byte
-- `id` - 4 bytes
+- `id` - variable (Identifier: 2 + N bytes)
 
-### Identifier
+### IggyMessage
 
 ```rust
-pub struct Identifier {
-    pub kind: IdKind,
-    pub length: u8,
-    pub value: Vec<u8>
+pub struct IggyMessage {
+    pub header: IggyMessageHeader,
+    pub user_headers: Option<Bytes>,
+    pub payload: Bytes,
 }
 
-pub enum IdKind {
-    Numeric,      // Value = 1 (default)
-    String        // Value = 2
+pub struct IggyMessageHeader {
+    pub checksum: u64,
+    pub id: u128,
+    pub offset: u64,
+    pub timestamp: u64,
+    pub origin_timestamp: u64,
+    pub user_headers_length: u32,
+    pub payload_length: u32,
+    pub reserved: u64,
 }
 ```
 
-The `Identifier` is a struct which represents the identifier of the stream or topic. It consists of the `kind` (numeric or string), `length` (length of the identifier value) and `value` (actual value of the identifier). The `value` is a vector of bytes, which can be either a numeric value (e.g. 1 encoded as const 4 bytes for u32 type) or a string (e.g. "my-stream") with variable length of UTF-8 string, maximum 255 bytes (chars). The total length varies between 3 (string type with a singl [...]
+Each message consists of a fixed 64-byte header followed by optional user headers and the payload.
 
-**Serialization**
+**Serialization (64-byte header + variable data)**
 
-- `kind` - 1 byte
-- `length` - 1 byte
-- `value` - N bytes
+- `checksum` - 8 bytes (u64, xxHash3)
+- `id` - 16 bytes (u128, UUIDv4)
+- `offset` - 8 bytes (u64)
+- `timestamp` - 8 bytes (u64, server-assigned)
+- `origin_timestamp` - 8 bytes (u64, client-provided)
+- `user_headers_length` - 4 bytes (u32)
+- `payload_length` - 4 bytes (u32)
+- `reserved` - 8 bytes (u64, must be 0)
+- `user_headers` - N bytes (length from `user_headers_length`)
+- `payload` - N bytes (length from `payload_length`)
 
 ### PolledMessages
 
@@ -144,53 +185,24 @@ The `Identifier` is a struct which represents the identifier of the stream or to
 pub struct PolledMessages {
     pub partition_id: u32,
     pub current_offset: u64,
-    pub messages: Vec<Message>,
+    pub count: u32,
+    pub messages: Vec<IggyMessage>,
 }
 ```
 
-The `PolledMessages` is a struct returned by the `PollMessages` command. It consists of the `partition_id`, `current_offset` and `messages` fields. The `messages` field is a vector of `Message` structs.
-
+The `PolledMessages` is returned by the `PollMessages` command.
 
 **Serialization**
 
 - `partition_id` - 4 bytes
 - `current_offset` - 8 bytes
-- `messages_count` - 4 bytes (hidden field)
-- `messages` - N bytes
-
-
-### Message
-
-```rust
-pub struct Message {
-    pub offset: u64,
-    pub state: MessageState,
-    pub timestamp: u64,
-    pub id: u128,
-    pub checksum: u32,
-    pub headers: Option<HashMap<HeaderKey, HeaderValue>>,
-    pub length: u32,
-    pub payload: Bytes,
-}
-```
-
-The `Message` consists of the `offset` (offset of the message in the partition), `state` (state of the message), `timestamp` (timestamp of the message), `id` (unique identifier of the message), `checksum` (checksum of the message), `headers` (optional headers of the message), `length` (length of the payload) and `payload` (actual payload of the message).
-
-**Serialization**
-
-- `offset` - 8 bytes
-- `state` - 1 byte
-- `timestamp` - 8 bytes
-- `id` - 16 bytes
-- `checksum` - 4 bytes
-- `headers` - N bytes
-- `length` - 4 bytes
-- `payload` - N bytes
+- `count` - 4 bytes
+- `messages` - N bytes (each message is 64-byte header + variable data)
 
 
 ### ConsumerOffsetInfo
 
-The `ConsumerOffsetInfo` is a struct returned by the `GetConsumerOffset` command. It consists of the `partition_id`, `current_offset` and `stored_offset` fields.
+Returned by the `GetConsumerOffset` command.
 
 ```rust
 pub struct ConsumerOffsetInfo {
@@ -206,53 +218,107 @@ pub struct ConsumerOffsetInfo {
 - `current_offset` - 8 bytes
 - `stored_offset` - 8 bytes
 
+### HeaderKey and HeaderValue
 
-## Streams
+```rust
+pub struct HeaderKey(String);
+
+pub struct HeaderValue {
+    pub kind: HeaderKind,
+    pub value: Vec<u8>
+}
+
+pub enum HeaderKind {
+    Raw,
+    String,
+    Bool,
+    Int8,
+    Int16,
+    Int32,
+    Int64,
+    Int128,
+    Uint8,
+    Uint16,
+    Uint32,
+    Uint64,
+    Uint128,
+    Float32,
+    Float64
+}
+```
+
+## System
 
 ---
 
-### Get stream
+### Ping
+
+**Code: 1** - Empty payload
+
+### Get stats
+
+**Code: 10** - Empty payload
+
+### Get snapshot
+
+**Code: 11** - Empty payload
+
+### Get cluster metadata
+
+**Code: 12** - Empty payload
+
+### Get me
+
+**Code: 20** - Empty payload
+
+### Get client
 
 ```rust
-pub struct GetStream {
-    pub stream_id: Identifier
+pub struct GetClient {
+    pub client_id: u32
 }
 ```
 
-**Code: 200**
+**Code: 21**
 
-**Serialization**
+- `client_id` - 4 bytes
 
-- `stream_id` - 3-257 bytes
+### Get clients
 
-### Get streams
+**Code: 22** - Empty payload
+
+## Streams
+
+---
+
+### Get stream
 
 ```rust
-pub struct GetStreams {}
+pub struct GetStream {
+    pub stream_id: Identifier
+}
 ```
 
-**Code: 201**
+**Code: 200**
 
-**Serialization**
+- `stream_id` - variable (Identifier)
+
+### Get streams
 
-- Empty bytes
+**Code: 201** - Empty payload
 
 
 ### Create stream
 
 ```rust
 pub struct CreateStream {
-    pub stream_id: u32,
     pub name: String
 }
 ```
 
 **Code: 202**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `name_length` - 1 byte (hidden field)
+- `name_length` - 1 byte
 - `name` - 1-255 bytes
 
 
@@ -266,9 +332,34 @@ pub struct DeleteStream {
 
 **Code: 203**
 
-**Serialization**
+- `stream_id` - variable (Identifier)
+
+### Update stream
 
-- `stream_id` - 3-257 bytes
+```rust
+pub struct UpdateStream {
+    pub stream_id: Identifier,
+    pub name: String
+}
+```
+
+**Code: 204**
+
+- `stream_id` - variable (Identifier)
+- `name_length` - 1 byte
+- `name` - 1-255 bytes
+
+### Purge stream
+
+```rust
+pub struct PurgeStream {
+    pub stream_id: Identifier
+}
+```
+
+**Code: 205**
+
+- `stream_id` - variable (Identifier)
 
 ## Topics
 
@@ -285,10 +376,8 @@ pub struct GetTopic {
 
 **Code: 300**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
 
 ### Get topics
 
@@ -300,30 +389,38 @@ pub struct GetTopics {
 
 **Code: 301**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
+- `stream_id` - variable (Identifier)
 
 ### Create topic
 
 ```rust
 pub struct CreateTopic {
     pub stream_id: Identifier,
-    pub topic_id: u32,
     pub partitions_count: u32,
-    pub message_expiry: Option<u32>,
+    pub compression_algorithm: CompressionAlgorithm,
+    pub message_expiry: IggyExpiry,
+    pub max_topic_size: MaxTopicSize,
+    pub replication_factor: Option<u8>,
     pub name: String,
 }
+
+pub enum CompressionAlgorithm {
+    None,   // Value = 1
+    Gzip,   // Value = 2
+    Lz4,    // Value = 3
+    Zstd,   // Value = 4
+}
 ```
 
 **Code: 302**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `partitions_count` - 4 bytes
-- `name_length` - 1 byte (hidden field)
+- `stream_id` - variable (Identifier)
+- `partitions_count` - 4 bytes (u32)
+- `compression_algorithm` - 1 byte
+- `message_expiry` - 8 bytes (u64, 0 = no expiry)
+- `max_topic_size` - 8 bytes (u64, 0 = unlimited)
+- `replication_factor` - 1 byte (0 = none)
+- `name_length` - 1 byte
 - `name` - 1-255 bytes
 
 ### Delete topic
@@ -337,10 +434,47 @@ pub struct DeleteTopic {
 
 **Code: 303**
 
-**Serialization**
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+
+### Update topic
+
+```rust
+pub struct UpdateTopic {
+    pub stream_id: Identifier,
+    pub topic_id: Identifier,
+    pub compression_algorithm: CompressionAlgorithm,
+    pub message_expiry: IggyExpiry,
+    pub max_topic_size: MaxTopicSize,
+    pub replication_factor: Option<u8>,
+    pub name: String,
+}
+```
+
+**Code: 304**
 
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `compression_algorithm` - 1 byte
+- `message_expiry` - 8 bytes (u64)
+- `max_topic_size` - 8 bytes (u64)
+- `replication_factor` - 1 byte
+- `name_length` - 1 byte
+- `name` - 1-255 bytes
+
+### Purge topic
+
+```rust
+pub struct PurgeTopic {
+    pub stream_id: Identifier,
+    pub topic_id: Identifier
+}
+```
+
+**Code: 305**
+
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
 
 ## Partitions
 
@@ -358,10 +492,8 @@ pub struct CreatePartitions {
 
 **Code: 402**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
 - `partitions_count` - 4 bytes
 
 ### Delete partitions
@@ -376,12 +508,32 @@ pub struct DeletePartitions {
 
 **Code: 403**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
 - `partitions_count` - 4 bytes
 
+## Segments
+
+---
+
+### Delete segments
+
+```rust
+pub struct DeleteSegments {
+    pub stream_id: Identifier,
+    pub topic_id: Identifier,
+    pub partition_id: u32,
+    pub segments_count: u32
+}
+```
+
+**Code: 503**
+
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partition_id` - 4 bytes
+- `segments_count` - 4 bytes
+
 ## Messages
 
 ---
@@ -393,7 +545,7 @@ pub struct PollMessages {
     pub consumer: Consumer,
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub partition_id: u32,
+    pub partition_id: Option<u32>,
     pub strategy: PollingStrategy,
     pub count: u32,
     pub auto_commit: bool,
@@ -415,13 +567,11 @@ pub enum PollingKind {
 
 **Code: 100**
 
-**Serialization**
-
-- `consumer` - 5 bytes
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `partition_id` - 4 bytes
-- `strategy` - 9 bytes
+- `consumer` - variable (Consumer)
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partition_id` - 5 bytes (1 byte flag + 4 bytes u32; flag: 1=Some, 0=None)
+- `strategy` - 9 bytes (1 byte kind + 8 bytes u64 value)
 - `count` - 4 bytes
 - `auto_commit` - 1 byte
 
@@ -432,7 +582,7 @@ pub struct SendMessages {
     pub stream_id: Identifier,
     pub topic_id: Identifier,
     pub partitioning: Partitioning,
-    pub messages: Vec<Message>
+    pub messages: Vec<IggyMessage>
 }
 
 pub struct Partitioning {
@@ -446,48 +596,32 @@ pub enum PartitioningKind {
     PartitionId,  // Value = 2
     MessagesKey   // Value = 3
 }
+```
 
-pub struct Message {
-    pub id: u128,
-    pub length: u32,
-    pub payload: Bytes // Memory-optimized vector of bytes
-    pub headers: Option<HashMap<HeaderKey, HeaderValue>> // Optional headers, see the changelog for more details
-}
+**Code: 101**
 
-pub struct HeaderKey(String);
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partitioning` - variable (1 byte kind + 1 byte length + N bytes value)
+- `messages` - each message: 64-byte header + user_headers + payload
 
-pub struct HeaderValue {
-    pub kind: HeaderKind,
-    pub value: Vec<u8>
-}
+### Flush unsaved buffer
 
-pub enum HeaderKind {
-    Raw,
-    String,
-    Bool,
-    Int8,
-    Int16,
-    Int32,
-    Int64,
-    Int128,
-    Uint8,
-    Uint16,
-    Uint32,
-    Uint64,
-    Uint128,
-    Float32,
-    Float64
+```rust
+pub struct FlushUnsavedBuffer {
+    pub stream_id: Identifier,
+    pub topic_id: Identifier,
+    pub partition_id: u32,
+    pub fsync: bool,
 }
 ```
 
-**Code: 101**
+**Code: 102**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `partitioning` - 3-257 bytes
-- `messages` - 16 + 4 + N bytes per single message
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partition_id` - 4 bytes
+- `fsync` - 1 byte (1=true, 0=false)
 
 ## Consumer offsets
 
@@ -500,18 +634,16 @@ pub struct GetConsumerOffset {
     pub consumer: Consumer,
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub partition_id: u32
+    pub partition_id: Option<u32>
 }
 ```
 
 **Code: 120**
 
-**Serialization**
-
-- `consumer` - 5 bytes
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `partition_id` - 4 bytes
+- `consumer` - variable (Consumer)
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partition_id` - 5 bytes (1 byte flag + 4 bytes u32)
 
 ### Store consumer offset
 
@@ -520,21 +652,37 @@ pub struct StoreConsumerOffset {
     pub consumer: Consumer,
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub partition_id: u32,
+    pub partition_id: Option<u32>,
     pub offset: u64
 }
 ```
 
 **Code: 121**
 
-**Serialization**
-
-- `consumer` - 5 bytes
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `partition_id` - 4 bytes
+- `consumer` - variable (Consumer)
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partition_id` - 5 bytes (1 byte flag + 4 bytes u32)
 - `offset` - 8 bytes
 
+### Delete consumer offset
+
+```rust
+pub struct DeleteConsumerOffset {
+    pub consumer: Consumer,
+    pub stream_id: Identifier,
+    pub topic_id: Identifier,
+    pub partition_id: Option<u32>
+}
+```
+
+**Code: 122**
+
+- `consumer` - variable (Consumer)
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `partition_id` - 5 bytes (1 byte flag + 4 bytes u32)
+
 ## Consumer groups
 
 ---
@@ -545,17 +693,15 @@ pub struct StoreConsumerOffset {
 pub struct GetConsumerGroup {
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub consumer_group_id: u32
+    pub group_id: Identifier
 }
 ```
 
 **Code: 600**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `consumer_group_id` - 4 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `group_id` - variable (Identifier)
 
 ### Get consumer groups
 
@@ -568,10 +714,8 @@ pub struct GetConsumerGroups {
 
 **Code: 601**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
 
 ### Create consumer group
 
@@ -579,17 +723,16 @@ pub struct GetConsumerGroups {
 pub struct CreateConsumerGroup {
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub consumer_group_id: u32
+    pub name: String,
 }
 ```
 
 **Code: 602**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `consumer_group_id` - 4 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `name_length` - 1 byte
+- `name` - 1-255 bytes
 
 ### Delete consumer group
 
@@ -597,17 +740,15 @@ pub struct CreateConsumerGroup {
 pub struct DeleteConsumerGroup {
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub consumer_group_id: u32
+    pub group_id: Identifier
 }
 ```
 
 **Code: 603**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `consumer_group_id` - 4 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `group_id` - variable (Identifier)
 
 ### Join consumer group
 
@@ -615,17 +756,15 @@ pub struct DeleteConsumerGroup {
 pub struct JoinConsumerGroup {
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub consumer_group_id: u32
+    pub group_id: Identifier
 }
 ```
 
 **Code: 604**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `consumer_group_id` - 4 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `group_id` - variable (Identifier)
 
 ### Leave consumer group
 
@@ -633,69 +772,198 @@ pub struct JoinConsumerGroup {
 pub struct LeaveConsumerGroup {
     pub stream_id: Identifier,
     pub topic_id: Identifier,
-    pub consumer_group_id: u32
+    pub group_id: Identifier
 }
 ```
 
 **Code: 605**
 
-**Serialization**
-
-- `stream_id` - 3-257 bytes
-- `topic_id` - 3-257 bytes
-- `consumer_group_id` - 4 bytes
+- `stream_id` - variable (Identifier)
+- `topic_id` - variable (Identifier)
+- `group_id` - variable (Identifier)
 
-## System
+## Users
 
 ---
 
-### Get me
+### Get user
 
 ```rust
-pub struct GetMe {}
+pub struct GetUser {
+    pub user_id: Identifier
+}
 ```
 
-**Code: 20**
+**Code: 31**
 
-**Serialization**
+- `user_id` - variable (Identifier)
 
-- Empty bytes
+### Get users
 
-### Get client
+**Code: 32** - Empty payload
+
+### Create user
 
 ```rust
-pub struct GetClient {
-    pub client_id: u32
+pub struct CreateUser {
+    pub username: String,
+    pub password: String,
+    pub status: u8,
+    pub permissions: Option<Permissions>,
 }
 ```
 
-**Code: 21**
+**Code: 33**
 
-**Serialization**
+- `username_length` - 1 byte
+- `username` - 1-255 bytes
+- `password_length` - 1 byte
+- `password` - 1-255 bytes
+- `status` - 1 byte
+- `has_permissions` - 1 byte (1=present, 0=absent)
+- `permissions_length` - 4 bytes (u32, always present, 0 when no permissions)
+- `permissions` - N bytes (only when `has_permissions=1` and `permissions_length > 0`)
 
-- `client_id` - 4 bytes
+### Delete user
+
+```rust
+pub struct DeleteUser {
+    pub user_id: Identifier
+}
+```
 
+**Code: 34**
 
-### Get clients
+- `user_id` - variable (Identifier)
+
+### Update user
 
 ```rust
-pub struct GetClients {}
+pub struct UpdateUser {
+    pub user_id: Identifier,
+    pub username: Option<String>,
+    pub status: Option<u8>,
+}
 ```
 
-**Code: 22**
+**Code: 35**
 
-**Serialization**
+- `user_id` - variable (Identifier)
+- `has_username` - 1 byte (1=present, 0=absent)
+- `username_length` - 1 byte (only when present)
+- `username` - N bytes (only when present)
+- `has_status` - 1 byte (1=present, 0=absent)
+- `status` - 1 byte (only when present)
 
-- Empty bytes
+### Update permissions
 
-### Get stats
+```rust
+pub struct UpdatePermissions {
+    pub user_id: Identifier,
+    pub permissions: Option<Permissions>,
+}
+```
+
+**Code: 36**
+
+- `user_id` - variable (Identifier)
+- `has_permissions` - 1 byte (1=present, 0=absent)
+- `permissions_length` - 4 bytes (u32, always present)
+- `permissions` - N bytes (only when `has_permissions=1`)
+
+### Change password
 
 ```rust
-pub struct GetStats {}
+pub struct ChangePassword {
+    pub user_id: Identifier,
+    pub current_password: String,
+    pub new_password: String,
+}
 ```
 
-**Code: 10**
+**Code: 37**
 
-**Serialization**
+- `user_id` - variable (Identifier)
+- `current_password_length` - 1 byte
+- `current_password` - N bytes
+- `new_password_length` - 1 byte
+- `new_password` - N bytes
+
+## Authentication
+
+---
+
+### Login user
+
+```rust
+pub struct LoginUser {
+    pub username: String,
+    pub password: String,
+    pub version: Option<String>,
+    pub context: Option<String>,
+}
+```
+
+**Code: 38**
+
+- `username_length` - 1 byte
+- `username` - N bytes
+- `password_length` - 1 byte
+- `password` - N bytes
+- `version_length` - 4 bytes (u32, 0 = absent)
+- `version` - N bytes (only when `version_length > 0`)
+- `context_length` - 4 bytes (u32, 0 = absent)
+- `context` - N bytes (only when `context_length > 0`)
+
+### Logout user
+
+**Code: 39** - Empty payload
+
+## Personal access tokens
+
+---
+
+### Get personal access tokens
+
+**Code: 41** - Empty payload
+
+### Create personal access token
+
+```rust
+pub struct CreatePersonalAccessToken {
+    pub name: String,
+    pub expiry: u64,
+}
+```
+
+**Code: 42**
+
+- `name_length` - 1 byte
+- `name` - 1-255 bytes
+- `expiry` - 8 bytes (u64, 0 = no expiry)
+
+### Delete personal access token
+
+```rust
+pub struct DeletePersonalAccessToken {
+    pub name: String,
+}
+```
+
+**Code: 43**
+
+- `name_length` - 1 byte
+- `name` - 1-255 bytes
+
+### Login with personal access token
+
+```rust
+pub struct LoginWithPersonalAccessToken {
+    pub token: String,
+}
+```
+
+**Code: 44**
 
-- Empty bytes
+- `token_length` - 1 byte
+- `token` - 1-255 bytes
diff --git a/content/docs/server/security.mdx b/content/docs/server/security.mdx
new file mode 100644
index 00000000..bcb2e322
--- /dev/null
+++ b/content/docs/server/security.mdx
@@ -0,0 +1,192 @@
+---
+title: Security
+---
+
+Iggy provides multiple layers of security covering authentication, authorization, transport encryption, and data encryption at rest.
+
+## Authentication
+
+Iggy supports two authentication mechanisms:
+
+### Username and password
+
+Users authenticate with a username and password via `login_user()`. Passwords are hashed using **Argon2id** (a memory-hard hashing algorithm). On first startup, the server generates a random password for the `root` user and logs it to the console. You can override this by setting environment variables:
+
+```bash
+IGGY_ROOT_USERNAME=iggy
+IGGY_ROOT_PASSWORD=my-secret-password
+```
+
+Or use the `--with-default-root-credentials` flag for development (sets root credentials to `iggy`/`iggy`).
+
+**Important**: once the data directory exists, environment variable credentials are ignored. To reset credentials, you must use the `--fresh` flag (which deletes all data).
+
+### Personal Access Tokens (PAT)
+
+PATs provide programmatic access with optional expiry. Each user can have up to `max_tokens_per_user` (default 100) active tokens. Tokens are hashed before storage and can be revoked at any time.
+
+```bash
+# Create a PAT via CLI
+iggy -u iggy -p secret pat create my-token 7d
+
+# Use the PAT for authentication
+iggy -t my-token-value stream list
+```
+
+An automatic cleaner removes expired tokens at a configurable interval.
+
+## Authorization
+
+Iggy provides granular permissions at three levels:
+
+1. **Global permissions** - system-wide operations (manage servers, manage users, read servers)
+2. **Stream permissions** - per-stream operations (manage stream, read stream, manage topics, read topics, poll messages, send messages)
+3. **Topic permissions** - per-topic operations within a stream (manage topic, read topic, poll messages, send messages)
+
+The root user has full access to everything and bypasses all permission checks. Other users can be assigned specific permissions using the CLI, SDK, or Web UI.
+
+### Permission hierarchy
+
+Permissions are organized in a tree structure. At the top level, the `Permissions` struct holds both global and per-stream settings:
+
+```rust
+pub struct Permissions {
+    pub global: GlobalPermissions,
+    pub streams: Option<HashMap<usize, StreamPermissions>>,
+}
+```
+
+The `global` field controls system-wide operations, while `streams` is an optional map keyed by stream ID that lets you grant fine-grained access to individual streams.
+
+### Global permissions
+
+`GlobalPermissions` contains boolean fields that govern server-wide operations:
+
+```rust
+pub struct GlobalPermissions {
+    pub manage_servers: bool,  // manage servers (superset of read_servers)
+    pub read_servers: bool,    // get stats, get clients
+    pub manage_users: bool,    // create/update/delete users (superset of read_users)
+    pub read_users: bool,      // get user, get users
+    pub manage_streams: bool,  // create/update/delete streams (superset of read_streams + manage_topics)
+    pub read_streams: bool,    // get streams (superset of read_topics)
+    pub manage_topics: bool,   // create/update/delete topics (superset of read_topics)
+    pub read_topics: bool,     // get topics, manage consumer groups (superset of poll_messages)
+    pub poll_messages: bool,   // poll messages from all streams/topics
+    pub send_messages: bool,   // send messages to all streams/topics
+}
+```
+
+Note that "manage" permissions are always supersets of their "read" counterparts. For example, if `manage_streams` is `true`, the user can also read streams, even if `read_streams` is `false`. Similarly, `read_topics` is a superset of `poll_messages`, so granting `read_topics` implicitly allows polling messages too.
+
+### Stream permissions
+
+When you need to restrict a user to specific streams rather than granting global access, use `StreamPermissions`:
+
+```rust
+pub struct StreamPermissions {
+    pub manage_stream: bool,
+    pub read_stream: bool,
+    pub manage_topics: bool,
+    pub read_topics: bool,
+    pub poll_messages: bool,
+    pub send_messages: bool,
+    pub topics: Option<HashMap<usize, TopicPermissions>>,
+}
+```
+
+The `topics` field works just like the `streams` field one level up. It is an optional map keyed by topic ID that lets you drill down even further.
+
+### Topic permissions
+
+At the most granular level, `TopicPermissions` controls access to a single topic within a stream:
+
+```rust
+pub struct TopicPermissions {
+    pub manage_topic: bool,
+    pub read_topic: bool,
+    pub poll_messages: bool,
+    pub send_messages: bool,
+}
+```
+
+### How permissions cascade
+
+Permissions are checked from top to bottom: global, then stream, then topic. If a permission is granted at a higher level, it covers everything below it. For instance:
+
+- Setting `global.poll_messages = true` lets the user poll messages from **all** streams and topics.
+- Setting `stream[1].poll_messages = true` lets the user poll messages from **all topics** in stream 1, but not from other streams.
+- Setting `stream[1].topics[5].poll_messages = true` lets the user poll messages only from topic 5 in stream 1.
+
+If the `streams` map is `None` (or a specific stream ID is absent from it), the user has no stream-level overrides and only global permissions apply. The same logic holds for the `topics` map within a stream.
+
+### Example: read-only user for a specific stream
+
+Suppose you want to create a user that can only poll messages from stream 42, with no other access. You would set up their permissions like this:
+
+```rust
+Permissions {
+    global: GlobalPermissions {
+        manage_servers: false,
+        read_servers: false,
+        manage_users: false,
+        read_users: false,
+        manage_streams: false,
+        read_streams: false,
+        manage_topics: false,
+        read_topics: false,
+        poll_messages: false,
+        send_messages: false,
+    },
+    streams: Some(HashMap::from([(
+        42,
+        StreamPermissions {
+            manage_stream: false,
+            read_stream: true,
+            manage_topics: false,
+            read_topics: true,
+            poll_messages: true,
+            send_messages: false,
+            topics: None, // allow all topics in this stream
+        },
+    )])),
+}
+```
+
+This user can read stream 42, list its topics, and poll messages from any topic within it, but cannot send messages, create topics, or access any other stream.
+
+## Transport encryption (TLS)
+
+All transport protocols support TLS encryption:
+
+- **TCP**: Optional TLS via rustls. Enable with `tcp.tls.enabled = true`.
+- **QUIC**: TLS is mandatory (built into the QUIC protocol). Uses self-signed certificates by default.
+- **HTTP**: Optional HTTPS. Enable with `http.tls.enabled = true`.
+- **WebSocket**: Optional TLS. Enable with `websocket.tls.enabled = true`.
+
+All protocols support automatic self-signed certificate generation when `self_signed = true` and the certificate files don't exist. For production deployments, provide proper certificates via `cert_file` and `key_file`.
+
+## Data encryption at rest
+
+Iggy supports optional **AES-256-GCM** encryption for message payloads and state commands. When enabled, all data is encrypted before being written to disk and decrypted when read. The encryption key must be a 32-byte base64-encoded string.
+
+```toml
+[system.encryption]
+enabled = false
+key = ""  # 32-byte base64-encoded key
+```
+
+## JWT (HTTP API)
+
+The HTTP API uses JWT (JSON Web Tokens) for session management. Tokens are signed with HS256 by default and have configurable expiry, clock skew tolerance, and audience/issuer validation.
+
+```toml
+[http.jwt]
+algorithm = "HS256"
+issuer = "iggy.apache.org"
+audience = "iggy.apache.org"
+access_token_expiry = "1 h"
+clock_skew = "5 s"
+```
+
+**Important**: change the default `encoding_secret` and `decoding_secret` values in production.
diff --git a/content/docs/server/storage-engine.mdx b/content/docs/server/storage-engine.mdx
new file mode 100644
index 00000000..bb0e134a
--- /dev/null
+++ b/content/docs/server/storage-engine.mdx
@@ -0,0 +1,188 @@
+---
+title: Storage Engine
+---
+
+Iggy's storage engine is built around the concept of a **segmented append-only log**. Every piece of data flows through a well-defined hierarchy: System -> Streams -> Topics -> Partitions -> Segments. This page covers how data is stored, indexed, flushed, and managed on disk.
+
+<StreamHierarchy />
+
+<AppendOnlyLogViz />
+
+## Directory layout
+
+All data is stored under the `system.path` directory (default `local_data`):
+
+```bash
+local_data/
+├── info.json                    # System metadata and version info
+├── state.messages               # Write-ahead log for metadata operations
+├── backup/                      # Optional backup storage
+├── logs/                        # Server log files
+├── runtime/                     # Runtime data
+└── streams/
+    └── {stream_id}/
+        └── topics/
+            └── {topic_id}/
+                └── partitions/
+                    └── {partition_id}/
+                        ├── 00000000000000000000.log
+                        ├── 00000000000000000000.index
+                        ├── 00000000000000000100.log
+                        └── 00000000000000000100.index
+```
+
+Each partition directory contains pairs of `.log` and `.index` files. The filename is the start offset of the first message in that segment, zero-padded to 20 digits.
+
+## Segmented log
+
+<SegmentVisualization />
+
+The `SegmentedLog` is the core storage abstraction per partition. It contains an ordered list of **sealed** (read-only) segments plus one **active** (writable) segment. When the active segment reaches its configured size limit (default 1 GiB), it is sealed and a new active segment is created.
+
+Key segment tracking fields:
+- `start_offset` / `end_offset` - first and last message position
+- `current_position` - write pointer in bytes
+- `size` - configured maximum (must be a multiple of 512 bytes)
+- `sealed` - whether the segment accepts new writes
+
+## Message binary format
+
+<MessageHeaderDiagram />
+
+Each message on disk consists of a 64-byte header followed by optional user headers and the payload:
+
+| Field | Bytes | Type | Description |
+|-------|-------|------|-------------|
+| checksum | 0..8 | u64 | xxHash3 integrity checksum |
+| id | 8..24 | u128 | Unique message ID (UUIDv4) |
+| offset | 24..32 | u64 | Sequential offset in partition |
+| timestamp | 32..40 | u64 | Server-assigned timestamp (microseconds) |
+| origin_timestamp | 40..48 | u64 | Client-provided timestamp |
+| user_headers_length | 48..52 | u32 | Length of user headers |
+| payload_length | 52..56 | u32 | Length of payload |
+| reserved | 56..64 | u64 | Reserved, must be 0 |
+
+After the 64-byte header: `user_headers` (variable, length from `user_headers_length`) followed by `payload` (variable, length from `payload_length`).
+
+All fields are stored in **little-endian** byte order. The header is exactly 64 bytes, which allows for efficient aligned reads. Messages are stored contiguously in the `.log` file with no padding between them.
+
+## Indexes
+
+Each segment has an accompanying `.index` file that stores positional and time indexes. These allow the server to quickly locate messages by offset or timestamp without scanning the entire log file.
+
+Index caching can be configured via the `cache_indexes` setting:
+
+| Strategy | Behavior |
+|----------|----------|
+| `"all"` | All segment indexes loaded at startup, kept in memory |
+| `"open_segment"` | Only the active segment's indexes are cached (default) |
+| `"none"` | Indexes are loaded on-demand from disk |
+
+If an index file becomes corrupted or goes missing, the `IndexRebuilder` can reconstruct it by scanning the corresponding `.log` file and parsing message headers.
+
+## Write pipeline
+
+Messages flow through a multi-stage pipeline before reaching disk:
+
+```mermaid
+graph TD
+  A["Client sends messages"] --> B["Messages buffered in MemoryMessageJournal"]
+  B --> C{"Flush threshold reached?"}
+  C -->|"Count >= 1024 OR Size >= 1 MiB"| D["MessagesWriter: vectored I/O"]
+  C -->|"No"| B
+  D --> E["Write to .log file"]
+  E --> F{"fsync enabled?"}
+  F -->|"Yes"| G["fsync to disk"]
+  F -->|"No"| H["OS manages writeback"]
+  G --> I{"Segment full?"}
+  H --> I
+  I -->|"Yes"| J["Seal segment, create new one"]
+  I -->|"No"| K["Done"]
+```
+
+The `MessagesWriter` uses **vectored I/O** (`writev`) with `MAX_IOV_COUNT=1024` to batch multiple message buffers into a single syscall, which significantly reduces the overhead of writing many small messages.
+
+The flush thresholds are configurable:
+- `messages_required_to_save` (default `1024`, minimum `1`) - count threshold
+- `size_of_messages_required_to_save` (default `"1 MiB"`) - size threshold
+
+These are soft limits - the actual count/size may be higher depending on the last batch size.
+
+## Memory pool
+
+Iggy includes a custom memory pool to eliminate allocation overhead on the hot path. The pool has **32 buckets** with buffer sizes ranging from 256 B up to 512 MiB (with non-uniform spacing optimized for common message sizes). When a component needs a buffer, it requests one from the appropriate bucket. When done, the buffer is returned to the pool.
+
+```toml
+[system.memory_pool]
+enabled = true
+size = "4 GiB"           # Total pool size (minimum 512 MiB, page-aligned)
+bucket_capacity = 8192    # Buffers per bucket (power of 2, minimum 128)
+```
+
+This avoids frequent heap allocations during message processing and enables zero-copy message passing between internal components.
+
+## Zero-copy deserialization
+
+Iggy uses a custom zero-copy deserialization approach for reading messages. Instead of fully deserializing each message from disk, the system maintains a separate index vector of `u32` values pointing to positions within the raw message data buffer. When a consumer polls messages, the server yields **views** into the underlying buffer rather than copying data, and performs just-in-time deserialization only for the fields the consumer actually needs.
+
+This approach delivered significant performance improvements:
+- Producer throughput: +40% (1.7 to 2.4 GB/s)
+- Consumer throughput: +90% (2.1 to 4.0 GB/s)
+- Producer P99 latency: +63% improvement (4.23 to 2.59ms)
+- Consumer P99 latency: +50% improvement (2.93 to 1.46ms)
+
+## Retention and cleanup
+
+Iggy supports two independent retention policies for automatic message cleanup, both configurable per topic:
+
+**Size-based retention**: when a topic exceeds `max_size`, the oldest sealed segments are removed to make room. Deletion kicks in at 90% of the limit. The active segment is always protected.
+
+**Time-based retention**: segments with all messages older than `message_expiry` are deleted. The cleaner runs at a configurable interval (default 1 minute) when `cleaner_enabled` is `true`.
+
+Both policies can be active simultaneously and only affect sealed segments. The active segment is never deleted, even if its messages have expired.
+
+## Message deduplication
+
+Optional server-side deduplication can be enabled per partition. When active, a hash-based `MessageDeduplicator` keeps track of recently seen message IDs and silently drops duplicates. This is useful for achieving exactly-once semantics at the application level.
+
+```toml
+[system.message_deduplication]
+enabled = false
+max_entries = 10000       # Max tracked IDs per partition
+expiry = "1 m"            # How long to remember seen IDs
+```
+
+## Encryption
+
+Iggy supports optional **AES-256-GCM** encryption for message payloads and state commands. When enabled, messages are encrypted before being written to disk and decrypted when read. The encryption key is a 32-byte base64-encoded string.
+
+```toml
+[system.encryption]
+enabled = false
+key = ""  # 32-byte base64-encoded key
+```
+
+## Compression
+
+Topic-level compression is supported with the following algorithms: `none`, `gzip`, `lz4`, `zstd`. The `allow_override` setting controls whether individual topics can override the default algorithm.
+
+## Backup and archiving
+
+Sealed segments can be archived to local/NAS storage or S3-compatible cloud storage (AWS S3, MinIO). Since sealed segments are immutable, they are safe to copy in parallel without any coordination. The archive path is configurable under `system.backup.path`.
+
+## State persistence (Write-ahead log)
+
+All metadata operations (create stream, delete topic, create user, etc.) are persisted to a write-ahead log (`state.messages`). Each entry contains:
+
+| Field | Size | Description |
+|-------|------|-------------|
+| index | 8 bytes | Sequential entry number |
+| term | 8 bytes | VSR consensus term |
+| timestamp | 8 bytes | Entry timestamp |
+| user_id | 4 bytes | Acting user |
+| flags | 4 bytes | Entry flags |
+| command_length | 4 bytes | Command payload size |
+| command_data | variable | Serialized command (MessagePack) |
+| checksum | 32 bytes | SHA-256 integrity verification |
+
+State is serialized using **MessagePack** (rmp-serde) for compact binary representation.
diff --git a/content/docs/web_ui/start.mdx b/content/docs/web_ui/start.mdx
index 9e825a17..c29f3a9d 100644
--- a/content/docs/web_ui/start.mdx
+++ b/content/docs/web_ui/start.mdx
@@ -2,11 +2,53 @@
 title: Iggy Web UI
 ---
 
-Iggy Web UI provides a comprehensive dashboard for Iggy server. It allows you to monitor the server's health, streams, topics, browse the messages, users and more. The dashboard is built with Svelte and is available as [open-source repository](https://github.com/apache/iggy/tree/master/web) as well as the Docker image on [Docker Hub](https://hub.docker.com/r/apache/iggy-web-ui).
+Iggy Web UI provides a comprehensive dashboard for Iggy server. It allows you to monitor the server's health, streams, topics, browse the messages, users and more. The dashboard is built with SvelteKit and TypeScript and is available as [open-source](https://github.com/apache/iggy/tree/master/web) as well as the Docker image on [Docker Hub](https://hub.docker.com/r/apache/iggy-web-ui).
 
 ![Web UI](/img/iggy_web_ui.png)
 
-Here's the full example of the `docker-compose.yml` file that starts the Iggy server, initializes it with the `my-stream` stream and `my-topic` topic with the help of [Iggy CLI](../cli/start.md), and eventually starts the Iggy Web UI:
+## Running modes
+
+### Embedded mode
+
+The Web UI can be compiled directly into the Iggy server binary using the `iggy-web` feature flag. When enabled, it is served at the `/ui` endpoint:
+
+```toml
+[http]
+enabled = true
+web_ui = true   # Enable embedded Web UI at /ui
+```
+
+This mode requires the server to be built with the `iggy-web` feature. If the server is compiled without it and `web_ui = true`, a warning is logged but the server continues to run normally.
+
+### Standalone mode
+
+Run the Web UI as a separate container:
+
+```bash
+docker pull apache/iggy-web-ui
+docker run -e PUBLIC_IGGY_API_URL=http://iggy-server:3000 -p 3050:3050 apache/iggy-web-ui
+```
+
+## Features
+
+The Web UI provides the following pages and functionality:
+
+- **Dashboard** - server health overview and key metrics
+- **Streams** - list, create, and manage streams
+- **Topics** - manage topics per stream (create, update, delete, purge)
+- **Partitions** - view partition details per topic
+- **Messages** - browse messages per partition with built-in decoders:
+  - JSON decoder (formatted JSON output)
+  - String decoder (UTF-8 text)
+  - XML decoder
+- **Clients** - list connected clients and their sessions
+- **Logs** - real-time server log viewer
+- **Users** - user management (create, update, delete, permissions)
+- **Settings** - server configuration overview, terminal access, and Web UI preferences
+
+## Docker Compose example
+
+Here's the full example of the `docker-compose.yml` file that starts the Iggy server, initializes it with the `my-stream` stream and `my-topic` topic with the help of [Iggy CLI](/docs/cli/start), and starts the Iggy Web UI:
 
 ```yaml
 iggy:
@@ -59,7 +101,7 @@ init-iggy:
 
     echo 'Creating my-stream topics...'
     iggy --tcp-server-address iggy:3000 --username iggy --password Secret123 topic create my-stream my-topic 1 none 7d
-    echo 'Created my-stream topics`
+    echo 'Created my-stream topics'
     "
 
 iggy-web-ui:
diff --git a/package-lock.json b/package-lock.json
index 07de6200..c6feaa26 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,6 +18,7 @@
         "next": "16.1.6",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
+        "sugar-high": "^0.9.5",
         "tailwind-merge": "^3.4.0",
         "zod": "^4.3.6"
       },
@@ -5668,6 +5669,12 @@
         }
       }
     },
+    "node_modules/sugar-high": {
+      "version": "0.9.5",
+      "resolved": "https://registry.npmjs.org/sugar-high/-/sugar-high-0.9.5.tgz",
+      "integrity": "sha512-eirwp9p7QcMg6EFCD6zrGh4H30uFx2YtfiMJUavagceP6/YUUjLeiQmis7QuwqKB3nXrWXlLaRumCqOd9AKpSA==",
+      "license": "MIT"
+    },
     "node_modules/tailwind-merge": {
       "version": "3.4.0",
       "resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.4.0.tgz",
diff --git a/package.json b/package.json
index 4c4dce25..cc1c0dcf 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
     "next": "16.1.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "sugar-high": "^0.9.5",
     "tailwind-merge": "^3.4.0",
     "zod": "^4.3.6"
   },
diff --git a/src/app/(home)/page.tsx b/src/app/(home)/page.tsx
index 224f2b1a..c3218c65 100644
--- a/src/app/(home)/page.tsx
+++ b/src/app/(home)/page.tsx
@@ -20,6 +20,8 @@
 import Link from "next/link";
 import Image from "next/image";
 import type { Metadata } from "next";
+import { LandingCodeTabs } from "@/components/code-tabs";
+import { BenchmarkSection } from "@/components/benchmark-chart";
 
 export const metadata: Metadata = {
   title: "Apache Iggy (Incubating) — Hyper-Efficient Message Streaming",
@@ -34,12 +36,12 @@ const heroStats = [
     gradient: "from-[#f9923f] via-[#5f87fd] to-[#fa5e8a]",
   },
   {
-    value: "< 1 ms",
-    label: "Latency @ P99",
+    value: "~1 ms",
+    label: "Avg Write Latency",
     gradient: "from-[#5f87fd] to-[#7d44e0]",
   },
   {
-    value: "6+",
+    value: "6",
     label: "Language SDKs",
     gradient: "from-[#9d44e0] to-[#e55efa]",
   },
@@ -69,17 +71,17 @@ const features = [
   {
     title: "Multi-Language SDKs",
     description:
-      "Client libraries available for Rust, C#, Java, Go, Python and Node.js with more languages coming for best developer experience.",
+      "Client libraries available for Rust, C#, Java, Go, Python, Node.js and C++ with more languages coming for best developer experience.",
   },
   {
     title: "Consumer Groups & Partitioning",
     description:
-      "Built-in support for consumer groups, partitioning, and horizontal scaling across connected clients.",
+      "Built-in support for consumer groups with cooperative rebalancing, partitioning, and horizontal scaling across connected clients.",
   },
   {
-    title: "Security & Authentication",
+    title: "Security & Access Control",
     description:
-      "User authentication and authorization with granular permissions, Personal Access Tokens, and optional data encryption.",
+      "TLS on all transports, per-stream and per-topic permissions, Personal Access Tokens for programmatic access, optional AES-256-GCM encryption at rest.",
   },
   {
     title: "Built-in Monitoring",
@@ -89,7 +91,38 @@ const features = [
   {
     title: "Multi-Tenant Support",
     description:
-      "Stream abstraction for multi-tenancy, message retention policies, and S3-compatible backup storage.",
+      "Stream abstraction for multi-tenancy, configurable message retention policies, and tiered storage coming in the future.",
+  },
+];
+
+const ecosystem = [
+  {
+    title: "Connectors",
+    description: "Dynamically loaded Rust plugins for data integration. Source from PostgreSQL, Elasticsearch, or sink to MongoDB, Elasticsearch, Apache Iceberg, Quickwit. Built-in data transforms.",
+    href: "/docs/connectors/introduction",
+    color: "#14b8a6",
+    tags: ["PostgreSQL", "MongoDB", "Elasticsearch", "Iceberg", "Quickwit"],
+  },
+  {
+    title: "MCP Server",
+    description: "Model Context Protocol server exposing 40+ tools for LLM integration. Works with Claude Desktop and other MCP clients via stdio and HTTP transports.",
+    href: "/docs/ai/mcp",
+    color: "#ec4899",
+    tags: ["Claude", "LLM", "40+ tools", "stdio", "HTTP"],
+  },
+  {
+    title: "Web UI",
+    description: "SvelteKit dashboard for stream/topic management, message browsing with JSON/string/XML decoders, user management, server logs, and real-time terminal.",
+    href: "/docs/web_ui/start",
+    color: "#a855f7",
+    tags: ["Dashboard", "Message browser", "User mgmt"],
+  },
+  {
+    title: "CLI",
+    description: "Full-featured command-line interface with named connection contexts, session-based login, and shell completions for bash/zsh/fish/powershell.",
+    href: "/docs/cli/start",
+    color: "#6366f1",
+    tags: ["Contexts", "Completions", "Login sessions"],
   },
 ];
 
@@ -165,7 +198,7 @@ export default function HomePage() {
         </div>
       </section>
 
-      {/* Features Section */}
+      {/* Built for performance - with architecture visualization */}
       <section
         className="px-6 py-20"
         style={{
@@ -179,18 +212,20 @@ export default function HomePage() {
               Built for <span className="text-[#ff9103]">performance</span>
             </h2>
             <p className="text-lg font-light leading-relaxed text-[#838d95]">
-              Apache Iggy (Incubating) is designed from the ground up to deliver{" "}
-              <span className="text-[#fffaeb]">
-                exceptional performance, reliability, and developer experience
-              </span>{" "}
-              for modern message streaming workloads. Combined with{" "}
+              Designed from the ground up with{" "}
               <span className="text-[#fffaeb]">
                 io_uring and thread-per-core, shared nothing architecture
-              </span>{" "}
-              for maximum speed and efficiency.
+              </span>
+              . Each CPU core runs its own shard, pinned and NUMA-aware.
+              No locks on the hot path, no GC pauses, no thread contention.
             </p>
           </div>
 
+          {/* Architecture visualization */}
+          <div className="mb-14">
+            <BenchmarkSection />
+          </div>
+
           <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
             {features.map((feature) => (
               <div
@@ -209,6 +244,129 @@ export default function HomePage() {
         </div>
       </section>
 
+      {/* How it works + code examples */}
+      <section
+        className="px-6 py-20"
+        style={{
+          backgroundImage:
+            "radial-gradient(circle farthest-side at 30% 80%, #1a100820, #070c17 50%)",
+        }}
+      >
+        <div className="mx-auto max-w-6xl">
+          <div className="mx-auto mb-14 max-w-3xl text-center">
+            <h2 className="mb-5 text-4xl font-bold tracking-tight text-[#fffaeb] md:text-5xl">
+              How it <span className="text-[#ff9103]">works</span>
+            </h2>
+            <p className="text-lg font-light leading-relaxed text-[#838d95]">
+              Messages flow from producers through streams and topics into
+              partitioned, append-only segment files on disk. Pick your language
+              and start streaming in minutes.
+            </p>
+          </div>
+
+          <div className="grid gap-6 md:grid-cols-2 items-start">
+            <div className="space-y-4">
+              {[
+                {
+                  step: "1",
+                  title: "Producers send messages",
+                  desc: "Connect via TCP, QUIC, WebSocket or HTTP. Messages are routed to the target partition using balanced, key-based or explicit partitioning.",
+                },
+                {
+                  step: "2",
+                  title: "Shard receives and buffers",
+                  desc: "Each partition is owned by exactly one CPU-pinned shard. Messages are buffered in a memory journal, then flushed to disk via vectored I/O through io_uring.",
+                },
+                {
+                  step: "3",
+                  title: "Segments store on disk",
+                  desc: "Data lands in append-only .log files with .index files for offset and timestamp lookups. Segments are sealed at 1 GiB and rotated automatically.",
+                },
+                {
+                  step: "4",
+                  title: "Consumers poll at any offset",
+                  desc: "Read from the beginning, a specific offset, a timestamp, or continue from the last committed position. Consumer groups distribute partitions for horizontal scaling.",
+                },
+              ].map((item) => (
+                <div
+                  key={item.step}
+                  className="flex gap-4 rounded-xl border border-white/[0.06] bg-white/[0.02] p-5"
+                >
+                  <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-[#ff9103]/10 text-[#ff9103] text-sm font-bold">
+                    {item.step}
+                  </div>
+                  <div>
+                    <h4 className="text-base font-semibold text-[#fffaeb] mb-1">
+                      {item.title}
+                    </h4>
+                    <p className="text-sm font-light leading-relaxed text-[#838d95] m-0">
+                      {item.desc}
+                    </p>
+                  </div>
+                </div>
+              ))}
+            </div>
+
+            <LandingCodeTabs />
+          </div>
+        </div>
+      </section>
+
+      {/* Ecosystem Section */}
+      <section
+        className="px-6 py-20"
+        style={{
+          backgroundImage:
+            "radial-gradient(circle farthest-side at 50% 90%, #1a1008, #070c17 65%)",
+        }}
+      >
+        <div className="mx-auto max-w-6xl">
+          <div className="mx-auto mb-14 max-w-3xl text-center">
+            <h2 className="mb-5 text-4xl font-bold tracking-tight text-[#fffaeb] md:text-5xl">
+              Complete <span className="text-[#ff9103]">ecosystem</span>
+            </h2>
+            <p className="text-lg font-light leading-relaxed text-[#838d95]">
+              Iggy is more than a server. Integrate with external systems, manage
+              everything from your browser or terminal, and connect LLMs to your
+              streaming infrastructure.
+            </p>
+          </div>
+
+          <div className="grid gap-5 sm:grid-cols-2">
+            {ecosystem.map((item) => (
+              <Link
+                key={item.title}
+                href={item.href}
+                className="group rounded-2xl border border-white/[0.08] bg-white/[0.02] p-6 transition-all duration-300 hover:border-[#ff9103]/30 hover:bg-[#18213a]/50 no-underline"
+              >
+                <div className="flex items-center gap-3 mb-3">
+                  <div
+                    className="w-3 h-3 rounded-full"
+                    style={{ backgroundColor: item.color }}
+                  />
+                  <h3 className="text-xl font-semibold text-[#fffaeb] m-0">
+                    {item.title}
+                  </h3>
+                </div>
+                <p className="text-sm font-light leading-relaxed text-[#838d95] mb-4">
+                  {item.description}
+                </p>
+                <div className="flex flex-wrap gap-1.5">
+                  {item.tags.map((tag) => (
+                    <span
+                      key={tag}
+                      className="px-2 py-0.5 rounded-full text-[10px] font-medium text-[#aaafb6] border border-white/[0.08]"
+                    >
+                      {tag}
+                    </span>
+                  ))}
+                </div>
+              </Link>
+            ))}
+          </div>
+        </div>
+      </section>
+
       {/* Footer */}
       <footer
         className="border-t border-[#3d4450] px-6 py-14"
diff --git a/src/app/error.tsx b/src/app/error.tsx
new file mode 100644
index 00000000..5f4782e4
--- /dev/null
+++ b/src/app/error.tsx
@@ -0,0 +1,20 @@
+"use client";
+
+export default function Error({
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div className="flex min-h-[50vh] flex-col items-center justify-center gap-4 p-8">
+      <h2 className="text-xl font-semibold">Something went wrong</h2>
+      <button
+        onClick={reset}
+        className="rounded-lg bg-fd-primary px-4 py-2 text-sm font-medium text-fd-primary-foreground"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
diff --git a/src/app/global.css b/src/app/global.css
index 5c8231ef..a288c343 100644
--- a/src/app/global.css
+++ b/src/app/global.css
@@ -24,10 +24,28 @@
 :root {
     --color-fd-primary: hsl(34 100% 51%);
     --color-fd-primary-foreground: hsl(0 0% 0%);
+    --sh-class: #e879f9;
+    --sh-identifier: #c4b5fd;
+    --sh-sign: #8996a3;
+    --sh-property: #e0f2fe;
+    --sh-entity: #67e8f9;
+    --sh-jsxliterals: #9ca3af;
+    --sh-string: #a5d6ff;
+    --sh-keyword: #ff7b72;
+    --sh-comment: #636b75;
 }
 
 .dark,
 [data-theme="dark"] {
+    --sh-class: #e879f9;
+    --sh-identifier: #c4b5fd;
+    --sh-sign: #8996a3;
+    --sh-property: #e0f2fe;
+    --sh-entity: #67e8f9;
+    --sh-jsxliterals: #9ca3af;
+    --sh-string: #a5d6ff;
+    --sh-keyword: #ff7b72;
+    --sh-comment: #636b75;
     --color-fd-primary: hsl(34 100% 51%);
     --color-fd-primary-foreground: hsl(0 0% 0%);
     --color-fd-background: hsl(222 55% 6%);
@@ -79,3 +97,50 @@ figure.shiki {
 .fd-prose a:hover {
     text-decoration: underline;
 }
+
+/* Architecture diagram animations */
+
+@keyframes fade-in {
+    from { opacity: 0; transform: translateY(0.25rem); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.animate-fade-in {
+    animation: fade-in 0.3s ease-out both;
+}
+
+@keyframes shard-pulse-kf {
+    0%, 100% { box-shadow: 0 0 0 0 currentColor; }
+    50% { box-shadow: 0 0 0 4px transparent; }
+}
+
+.shard-pulse {
+    animation: shard-pulse-kf 2s ease-in-out infinite;
+}
+
+@keyframes ring-glow-kf {
+    0%, 100% { box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.4); }
+    50% { box-shadow: 0 0 0 3px rgba(16, 185, 129, 0); }
+}
+
+.ring-glow {
+    animation: ring-glow-kf 2s ease-in-out infinite;
+}
+
+@keyframes segment-fill-kf {
+    0% { opacity: 0.6; }
+    50% { opacity: 1; }
+    100% { opacity: 0.6; }
+}
+
+.segment-fill-active {
+    animation: segment-fill-kf 2s ease-in-out infinite;
+}
+
+@keyframes bench-bar-kf {
+    from { width: 0%; }
+}
+
+.bench-bar {
+    animation: bench-bar-kf 1s ease-out both;
+}
diff --git a/src/components/architecture-diagrams.tsx b/src/components/architecture-diagrams.tsx
new file mode 100644
index 00000000..66f33183
--- /dev/null
+++ b/src/components/architecture-diagrams.tsx
@@ -0,0 +1,1262 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+"use client";
+
+import { useState, useEffect } from "react";
+
+export function MessageFlowDiagram() {
+  const [step, setStep] = useState(0);
+  const [isPlaying, setIsPlaying] = useState(true);
+  const totalSteps = 7;
+
+  useEffect(() => {
+    if (!isPlaying) return;
+    const timer = setInterval(() => {
+      setStep((s) => (s + 1) % totalSteps);
+    }, 2000);
+    return () => clearInterval(timer);
+  }, [isPlaying]);
+
+  const steps = [
+    { label: "Client", desc: "Client sends messages via TCP/QUIC/WS/HTTP", icon: "M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-1 17.93c-3.95-.49-7-3.85-7-7.93 0-.62.08-1.21.21-1.79L9 15v1c0 1.1.9 2 2 2v1.93z" },
+    { label: "Listener", desc: "Transport listener receives the request on a shard thread", icon: "M21 3L3 10.53v.98l6.84 2.65L12.48 21h.98L21 3z" },
+    { label: "Router", desc: "Request routed to owning shard via IggyNamespace hash", icon: "M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z" },
+    { label: "Stream", desc: "Stream lookup by ID (metadata read from left-right)", icon: "M4 6h16v2H4zm0 5h16v2H4zm0 5h16v2H4z" },
+    { label: "Topic", desc: "Topic lookup within stream, compression applied", icon: "M3 18h6v-2H3v2zM3 6v2h18V6H3zm0 7h12v-2H3v2z" },
+    { label: "Partition", desc: "Messages buffered in MemoryMessageJournal", icon: "M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 16H5V5h14v14z" },
+    { label: "Segment", desc: "Flushed to .log file via vectored I/O (io_uring)", icon: "M14 2H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V8l-6-6zm4 18H6V4h7v5h5v11z" },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <div className="flex items-center justify-between mb-6">
+        <h3 className="text-lg font-semibold text-fd-foreground m-0">Message Flow</h3>
+        <button
+          onClick={() => setIsPlaying(!isPlaying)}
+          className="px-3 py-1 rounded-md text-xs font-medium bg-fd-accent text-fd-accent-foreground hover:opacity-80 transition-opacity"
+        >
+          {isPlaying ? "Pause" : "Play"}
+        </button>
+      </div>
+
+      <div className="space-y-2 mb-6">
+        {steps.map((s, i) => (
+          <div
+            key={i}
+            onClick={() => { setStep(i); setIsPlaying(false); }}
+            className={`
+              relative flex items-center gap-4 rounded-lg px-4 py-3 transition-all duration-500 cursor-pointer
+              ${i <= step
+                ? "bg-fd-primary/10 border border-fd-primary/30"
+                : "bg-fd-muted/30 border border-transparent"
+              }
+              ${i === step ? "ring-2 ring-fd-primary/50 shadow-lg shadow-fd-primary/10" : ""}
+            `}
+          >
+            <div className={`
+              relative flex items-center justify-center w-9 h-9 rounded-lg shrink-0 transition-all duration-500
+              ${i <= step ? "bg-fd-primary text-fd-primary-foreground" : "bg-fd-muted text-fd-muted-foreground"}
+            `}>
+              <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor">
+                <path d={s.icon} />
+              </svg>
+              {i === step && (
+                <span className="absolute -top-1.5 -right-1.5 w-3 h-3 rounded-full bg-fd-primary animate-ping" />
+              )}
+            </div>
+            <div className="flex-1 min-w-0">
+              <div className="flex items-center gap-2">
+                <span className={`text-sm font-mono font-bold transition-colors duration-500 ${
+                  i <= step ? "text-fd-foreground" : "text-fd-muted-foreground"
+                }`}>
+                  {i + 1}. {s.label}
+                </span>
+              </div>
+              <p className={`text-sm m-0 mt-0.5 transition-colors duration-500 ${
+                i <= step ? "text-fd-foreground/80" : "text-fd-muted-foreground/60"
+              }`}>
+                {s.desc}
+              </p>
+            </div>
+            {i < steps.length - 1 && i <= step && (
+              <div className="absolute left-[1.4rem] -bottom-2 w-px h-2 bg-fd-primary/30" />
+            )}
+          </div>
+        ))}
+      </div>
+
+      <div className="flex justify-center gap-1.5 mt-4">
+        {steps.map((_, i) => (
+          <button
+            key={i}
+            onClick={() => { setStep(i); setIsPlaying(false); }}
+            className={`w-2 h-2 rounded-full transition-all duration-300 ${
+              i === step ? "bg-fd-primary w-6" : "bg-fd-muted-foreground/30 hover:bg-fd-muted-foreground/50"
+            }`}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function ShardDiagram() {
+  const [activeShard, setActiveShard] = useState(0);
+
+  const shards = [
+    {
+      id: 0,
+      label: "Shard 0 (Primary)",
+      color: "var(--color-fd-primary)",
+      features: ["MetadataWriter", "HTTP Server (axum)", "QUIC Server", "VSR Primary", "Config Writer"],
+      partitions: ["P1", "P4", "P7"],
+    },
+    {
+      id: 1,
+      label: "Shard 1",
+      color: "#3b82f6",
+      features: ["MetadataReader", "TCP Server", "WebSocket Server"],
+      partitions: ["P2", "P5", "P8"],
+    },
+    {
+      id: 2,
+      label: "Shard 2",
+      color: "#8b5cf6",
+      features: ["MetadataReader", "TCP Server", "WebSocket Server"],
+      partitions: ["P3", "P6", "P9"],
+    },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-6">Thread-per-Core Shard Architecture</h3>
+
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mb-6">
+        {shards.map((shard) => (
+          <button
+            key={shard.id}
+            onClick={() => setActiveShard(shard.id)}
+            className={`
+              relative rounded-xl border-2 p-4 text-left transition-all duration-300
+              ${activeShard === shard.id
+                ? "border-fd-primary bg-fd-primary/5 shadow-lg shadow-fd-primary/10"
+                : "border-fd-border bg-fd-card hover:border-fd-muted-foreground/30"
+              }
+            `}
+          >
+            <div className="flex items-center gap-2 mb-3">
+              <div
+                className="w-3 h-3 rounded-full shard-pulse"
+                style={{ backgroundColor: shard.color }}
+              />
+              <span className="text-xs font-mono font-bold text-fd-foreground">{shard.label}</span>
+            </div>
+
+            <div className="rounded-md bg-fd-muted/50 p-2 mb-2">
+              <span className="text-[10px] font-mono text-fd-muted-foreground block mb-1">compio runtime</span>
+              <div className="flex items-center gap-1">
+                <span className="inline-block w-1.5 h-1.5 rounded-full bg-emerald-500 ring-glow" />
+                <span className="text-[10px] text-fd-foreground">io_uring (4096 ops)</span>
+              </div>
+            </div>
+
+            <div className="space-y-1">
+              {shard.features.map((f) => (
+                <div key={f} className="flex items-center gap-1.5">
+                  <span className="w-1 h-1 rounded-full bg-fd-muted-foreground/50" />
+                  <span className="text-[11px] text-fd-muted-foreground">{f}</span>
+                </div>
+              ))}
+            </div>
+
+            <div className="mt-3 flex gap-1.5">
+              {shard.partitions.map((p) => (
+                <span
+                  key={p}
+                  className="inline-flex items-center justify-center px-2 py-0.5 rounded text-[10px] font-mono font-medium bg-fd-accent text-fd-accent-foreground"
+                >
+                  {p}
+                </span>
+              ))}
+            </div>
+
+            <div className="absolute -top-2 -right-2 px-2 py-0.5 rounded-full text-[9px] font-mono font-bold bg-fd-secondary text-fd-secondary-foreground border border-fd-border">
+              CPU {shard.id}
+            </div>
+          </button>
+        ))}
+      </div>
+
+      <div className="rounded-lg bg-fd-muted/30 p-4">
+        <div className="flex items-center gap-2 mb-2">
+          <svg width="16" height="16" viewBox="0 0 16 16" className="text-fd-muted-foreground">
+            <path d="M2 8h12M10 4l4 4-4 4" stroke="currentColor" strokeWidth="1.5" fill="none" />
+          </svg>
+          <span className="text-xs font-medium text-fd-muted-foreground">Inter-shard communication</span>
+        </div>
+        <p className="text-xs text-fd-muted-foreground m-0">
+          Shards communicate via <code className="text-[11px]">crossfire</code> bounded mpsc channels. Metadata mutations route to Shard 0.
+          Partition ops route to the owning shard via <code className="text-[11px]">DashMap&lt;IggyNamespace, PartitionLocation&gt;</code>.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+export function IoUringComparison() {
+  return (
+    <div className="my-8 grid grid-cols-1 md:grid-cols-2 gap-4">
+      <div className="rounded-xl border border-fd-border bg-fd-card p-5">
+        <div className="flex items-center gap-2 mb-4">
+          <span className="w-2.5 h-2.5 rounded-full bg-red-500/70" />
+          <h4 className="text-sm font-semibold text-fd-foreground m-0">epoll (readiness-based)</h4>
+        </div>
+        <div className="space-y-3">
+          {["App asks: \"Is FD ready?\"", "Kernel: \"Yes, it's ready\"", "App performs the I/O itself"].map((text, i) => (
+            <div key={i} className="flex items-start gap-3">
+              <span className="mt-0.5 text-xs font-mono text-fd-muted-foreground w-4 shrink-0">{i + 1}.</span>
+              <div className="rounded-md bg-fd-muted/50 p-2 flex-1">
+                <span className="text-[11px] text-fd-foreground block">{text}</span>
+              </div>
+            </div>
+          ))}
+          <div className="rounded-md bg-red-500/10 border border-red-500/20 p-2 mt-2">
+            <span className="text-[11px] text-red-400 block">Files are &quot;always ready&quot; for epoll. Tokio uses a blocking thread pool (up to 512 threads) for file I/O.</span>
+          </div>
+        </div>
+      </div>
+
+      <div className="rounded-xl border border-fd-primary/30 bg-fd-card p-5 shadow-lg shadow-fd-primary/5">
+        <div className="flex items-center gap-2 mb-4">
+          <span className="w-2.5 h-2.5 rounded-full bg-fd-primary shard-pulse" />
+          <h4 className="text-sm font-semibold text-fd-foreground m-0">io_uring (completion-based)</h4>
+        </div>
+        <div className="space-y-3">
+          {["App submits I/O to Submission Queue (SQ)", "Kernel completes the I/O asynchronously", "Result placed in Completion Queue (CQ)"].map((text, i) => (
+            <div key={i} className="flex items-start gap-3">
+              <span className="mt-0.5 text-xs font-mono text-fd-muted-foreground w-4 shrink-0">{i + 1}.</span>
+              <div className="rounded-md bg-fd-primary/10 p-2 flex-1">
+                <span className="text-[11px] text-fd-foreground block">{text}</span>
+              </div>
+            </div>
+          ))}
+          <div className="rounded-md bg-emerald-500/10 border border-emerald-500/20 p-2 mt-2">
+            <span className="text-[11px] text-emerald-400 block">Both SQ and CQ are lock-free ring buffers shared between user space and kernel. No syscall per I/O in the hot path.</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function SegmentVisualization() {
+  const [expanded, setExpanded] = useState<number | null>(0);
+
+  const segments = [
+    { offset: 0, size: "1 GiB", messages: "~16M msgs", status: "sealed", startOffset: 0, endOffset: 15999999 },
+    { offset: 16000000, size: "1 GiB", messages: "~16M msgs", status: "sealed", startOffset: 16000000, endOffset: 31999999 },
+    { offset: 32000000, size: "412 MiB", messages: "~6.5M msgs", status: "active", startOffset: 32000000, endOffset: 38500000 },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Partition Storage Layout</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-5">
+        Each partition contains a segmented log. Segments are sealed at 1 GiB and new ones created automatically. Click a segment to inspect its files.
+      </p>
+
+      <div className="space-y-3">
+        {segments.map((seg, i) => (
+          <button
+            key={i}
+            onClick={() => setExpanded(expanded === i ? null : i)}
+            className={`
+              w-full text-left rounded-lg border p-4 transition-all duration-300
+              ${seg.status === "active"
+                ? "border-fd-primary/50 bg-fd-primary/5"
+                : "border-fd-border bg-fd-muted/20 hover:border-fd-muted-foreground/30"
+              }
+              ${expanded === i ? "shadow-lg" : ""}
+            `}
+          >
+            <div className="flex items-center justify-between">
+              <div className="flex items-center gap-3">
+                <div className="w-32 h-3 rounded-full bg-fd-muted/50 overflow-hidden">
+                  <div
+                    className={`h-full rounded-full ${
+                      seg.status === "active"
+                        ? "bg-fd-primary segment-fill-active"
+                        : "bg-fd-muted-foreground/40"
+                    }`}
+                    style={{ width: seg.status === "active" ? "40%" : "100%" }}
+                  />
+                </div>
+                <div>
+                  <span className="text-xs font-mono font-bold text-fd-foreground block">
+                    {String(seg.offset).padStart(20, "0")}
+                  </span>
+                  <span className="text-[10px] text-fd-muted-foreground">
+                    {seg.size} / {seg.messages}
+                  </span>
+                </div>
+              </div>
+              <div className="flex items-center gap-2">
+                <span
+                  className={`px-2 py-0.5 rounded-full text-[10px] font-medium ${
+                    seg.status === "active"
+                      ? "bg-fd-primary/20 text-fd-primary"
+                      : "bg-fd-muted text-fd-muted-foreground"
+                  }`}
+                >
+                  {seg.status === "active" ? "writing" : "sealed"}
+                </span>
+                <svg width="12" height="12" viewBox="0 0 12 12" className={`text-fd-muted-foreground transition-transform duration-200 ${expanded === i ? "rotate-180" : ""}`}>
+                  <path d="M3 4.5l3 3 3-3" stroke="currentColor" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+                </svg>
+              </div>
+            </div>
+
+            {expanded === i && (
+              <div className="mt-4 pt-3 border-t border-fd-border/50 animate-fade-in">
+                <div className="grid grid-cols-2 gap-3 mb-3">
+                  <div className="rounded-lg bg-fd-accent/30 p-3">
+                    <div className="flex items-center gap-2 mb-1">
+                      <span className="w-2 h-2 rounded bg-fd-primary/60" />
+                      <span className="text-[11px] font-mono font-bold text-fd-foreground">.log</span>
+                    </div>
+                    <span className="text-[10px] text-fd-muted-foreground block">Message data (headers + payloads)</span>
+                    <span className="text-[10px] text-fd-muted-foreground block">64-byte header per message</span>
+                  </div>
+                  <div className="rounded-lg bg-fd-accent/30 p-3">
+                    <div className="flex items-center gap-2 mb-1">
+                      <span className="w-2 h-2 rounded bg-blue-500/60" />
+                      <span className="text-[11px] font-mono font-bold text-fd-foreground">.index</span>
+                    </div>
+                    <span className="text-[10px] text-fd-muted-foreground block">Positional + time indexes</span>
+                    <span className="text-[10px] text-fd-muted-foreground block">Fast offset and timestamp lookups</span>
+                  </div>
+                </div>
+                <div className="flex gap-4 text-[10px] text-fd-muted-foreground">
+                  <span>Offsets: <code className="text-fd-foreground">{seg.startOffset.toLocaleString()}</code> .. <code className="text-fd-foreground">{seg.endOffset.toLocaleString()}</code></span>
+                  {seg.status === "sealed" && <span>Read-only, safe to archive</span>}
+                  {seg.status === "active" && <span>Accepting writes via vectored I/O</span>}
+                </div>
+              </div>
+            )}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function MessageHeaderDiagram() {
+  const [hoveredField, setHoveredField] = useState<string | null>(null);
+
+  const fields = [
+    { name: "checksum", bytes: "0-8", size: 8, type: "u64", desc: "xxHash3 integrity checksum", color: "#ef4444" },
+    { name: "id", bytes: "8-24", size: 16, type: "u128", desc: "Unique message ID (UUIDv4)", color: "#f59e0b" },
+    { name: "offset", bytes: "24-32", size: 8, type: "u64", desc: "Sequential offset in partition", color: "#10b981" },
+    { name: "timestamp", bytes: "32-40", size: 8, type: "u64", desc: "Server-assigned timestamp", color: "#3b82f6" },
+    { name: "origin_ts", bytes: "40-48", size: 8, type: "u64", desc: "Client-provided timestamp", color: "#6366f1" },
+    { name: "hdrs_len", bytes: "48-52", size: 4, type: "u32", desc: "User headers length", color: "#8b5cf6" },
+    { name: "pay_len", bytes: "52-56", size: 4, type: "u32", desc: "Payload length", color: "#a855f7" },
+    { name: "reserved", bytes: "56-64", size: 8, type: "u64", desc: "Reserved (must be 0)", color: "#6b7280" },
+  ];
+
+  const totalSize = 64;
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Message Header (64 bytes, little-endian)</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-5">
+        Every message starts with this fixed-size header for efficient aligned reads.
+      </p>
+
+      <div className="flex rounded-lg overflow-hidden mb-4 h-10">
+        {fields.map((f) => (
+          <div
+            key={f.name}
+            onMouseEnter={() => setHoveredField(f.name)}
+            onMouseLeave={() => setHoveredField(null)}
+            className="relative flex items-center justify-center transition-all duration-200 cursor-default border-r border-fd-card last:border-r-0"
+            style={{
+              width: `${(f.size / totalSize) * 100}%`,
+              backgroundColor: hoveredField === f.name ? f.color : `${f.color}66`,
+              opacity: hoveredField && hoveredField !== f.name ? 0.4 : 1,
+            }}
+          >
+            <span className="text-[9px] font-mono font-bold text-white truncate px-1">
+              {f.name}
+            </span>
+          </div>
+        ))}
+      </div>
+
+      <div className="flex mb-4 text-[8px] font-mono text-fd-muted-foreground">
+        {fields.map((f) => (
+          <div key={f.name} style={{ width: `${(f.size / totalSize) * 100}%` }} className="text-center">
+            {f.bytes}
+          </div>
+        ))}
+      </div>
+
+      {hoveredField && (
+        <div className="rounded-lg bg-fd-accent/50 p-3 animate-fade-in">
+          {(() => {
+            const f = fields.find((x) => x.name === hoveredField)!;
+            return (
+              <div className="flex items-center gap-3">
+                <div className="w-3 h-3 rounded" style={{ backgroundColor: f.color }} />
+                <div>
+                  <span className="text-xs font-mono font-bold text-fd-foreground">{f.name}</span>
+                  <span className="text-xs text-fd-muted-foreground ml-2">({f.type}, {f.size} bytes)</span>
+                  <p className="text-xs text-fd-muted-foreground m-0 mt-0.5">{f.desc}</p>
+                </div>
+              </div>
+            );
+          })()}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function BenchmarkChart() {
+  const metrics = [
+    { label: "8 partitions P9999", tokio: 100, tpc: 19, improvement: "81%" },
+    { label: "16 partitions P95", tokio: 100, tpc: 72, improvement: "28%" },
+    { label: "16 partitions P99", tokio: 100, tpc: 68, improvement: "32%" },
+    { label: "16 partitions P9999", tokio: 100, tpc: 8, improvement: "92%" },
+    { label: "32 partitions P95", tokio: 100, tpc: 43, improvement: "57%" },
+    { label: "32 partitions P99", tokio: 100, tpc: 40, improvement: "60%" },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Latency Improvements: Tokio vs Thread-per-Core</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-5">
+        Relative latency comparison (lower is better). Thread-per-core with io_uring vs Tokio work-stealing.
+      </p>
+
+      <div className="space-y-4">
+        {metrics.map((m, i) => (
+          <div key={i}>
+            <div className="flex items-center justify-between mb-1">
+              <span className="text-[11px] font-mono text-fd-muted-foreground">{m.label}</span>
+              <span className="text-[11px] font-bold text-emerald-400">-{m.improvement}</span>
+            </div>
+            <div className="flex gap-1.5">
+              <div className="flex-1 h-5 rounded bg-fd-muted/50 relative overflow-hidden">
+                <div className="h-full rounded bg-red-500/40 bench-bar" style={{ width: `${m.tokio}%` }} />
+                <span className="absolute inset-0 flex items-center justify-center text-[9px] font-mono text-fd-muted-foreground">tokio</span>
+              </div>
+              <div className="flex-1 h-5 rounded bg-fd-muted/50 relative overflow-hidden">
+                <div className="h-full rounded bg-fd-primary/60 bench-bar" style={{ width: `${m.tpc}%` }} />
+                <span className="absolute inset-0 flex items-center justify-center text-[9px] font-mono text-fd-foreground">thread-per-core</span>
+              </div>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function NamespacePacking() {
+  const bitGroups = [
+    { label: "unused (20 bits)", bits: 20, color: undefined, range: "63..44" },
+    { label: "stream", bits: 12, color: "#f59e0b88", range: "43..32", sub: "12 bits" },
+    { label: "topic", bits: 12, color: "#3b82f688", range: "31..20", sub: "12 bits" },
+    { label: "partition", bits: 20, color: "#10b98188", range: "19..0", sub: "20 bits" },
+  ];
+
+  const limits = [
+    { label: "Max Streams", value: "4,096", color: "#f59e0b" },
+    { label: "Max Topics", value: "4,096", color: "#3b82f6" },
+    { label: "Max Partitions", value: "1,000,000", color: "#10b981" },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">IggyNamespace Bit Packing (u64)</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-5">
+        Stream, topic, and partition IDs are packed into a single u64 for efficient hashing and shard routing.
+      </p>
+
+      <div className="flex rounded-lg overflow-hidden h-12 mb-3">
+        {bitGroups.map((g, i) => (
+          <div
+            key={i}
+            className={`flex items-center justify-center ${i < bitGroups.length - 1 ? "border-r border-fd-card" : ""} ${!g.color ? "bg-fd-muted/30" : ""}`}
+            style={{ width: `${(g.bits / 64) * 100}%`, ...(g.color ? { backgroundColor: g.color } : {}) }}
+          >
+            <div className="text-center">
+              <span className={`text-[10px] font-mono ${g.color ? "font-bold text-white" : "text-fd-muted-foreground"} block`}>{g.label}</span>
+              {g.sub && <span className="text-[8px] font-mono text-white/70">{g.sub}</span>}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <div className="flex text-[8px] font-mono text-fd-muted-foreground mb-4">
+        {bitGroups.map((g, i) => (
+          <div key={i} style={{ width: `${(g.bits / 64) * 100}%` }} className="text-center">{g.range}</div>
+        ))}
+      </div>
+
+      <div className="grid grid-cols-3 gap-3">
+        {limits.map((item) => (
+          <div key={item.label} className="rounded-lg bg-fd-muted/30 p-3 text-center">
+            <div className="w-2 h-2 rounded-full mx-auto mb-1" style={{ backgroundColor: item.color }} />
+            <span className="text-xs font-mono font-bold text-fd-foreground block">{item.value}</span>
+            <span className="text-[10px] text-fd-muted-foreground">{item.label}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function StreamHierarchy() {
+  const [expanded, setExpanded] = useState<Record<string, boolean>>({
+    stream: true,
+    "topic-user": true,
+    "topic-order": true,
+    "partition-user-1": false,
+    "partition-user-2": false,
+    "partition-user-3": false,
+    "partition-order-1": false,
+    "partition-order-2": false,
+    "partition-order-3": false,
+  });
+
+  const toggle = (key: string) => {
+    setExpanded((prev) => ({ ...prev, [key]: !prev[key] }));
+  };
+
+  const Chevron = ({ open }: { open: boolean }) => (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 14 14"
+      fill="none"
+      className={`shrink-0 transition-transform duration-200 ${open ? "rotate-90" : ""}`}
+    >
+      <path d="M5 3l4 4-4 4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  );
+
+  const SegmentBadge = ({ label, active }: { label: string; active?: boolean }) => (
+    <span
+      className={`inline-flex items-center gap-1.5 px-2 py-1 rounded text-[11px] font-mono ${
+        active
+          ? "bg-fd-primary/10 border border-fd-primary/30 text-fd-primary"
+          : "bg-fd-muted/40 border border-fd-border text-fd-muted-foreground"
+      }`}
+    >
+      {active && <span className="w-1.5 h-1.5 rounded-full bg-fd-primary animate-pulse" />}
+      {label}
+    </span>
+  );
+
+  const partitions = (topicKey: string) =>
+    [1, 2, 3].map((p) => {
+      const pKey = `partition-${topicKey}-${p}`;
+      return (
+        <div key={pKey} className="ml-8 mt-1.5">
+          <button
+            onClick={() => toggle(pKey)}
+            className="flex items-center gap-2 w-full rounded-md px-3 py-2 text-left transition-colors hover:bg-[#10b981]/10 border border-transparent hover:border-[#10b981]/20"
+          >
+            <Chevron open={!!expanded[pKey]} />
+            <span className="w-2 h-2 rounded-full bg-[#10b981] shrink-0" />
+            <span className="text-xs font-mono font-medium text-fd-foreground">Partition {p}</span>
+            <span className="text-[10px] text-fd-muted-foreground ml-auto">append-only log</span>
+          </button>
+          {expanded[pKey] && (
+            <div className="ml-10 mt-1.5 flex flex-wrap gap-1.5">
+              <SegmentBadge label="seg-0 (sealed)" />
+              <SegmentBadge label="seg-1 (sealed)" />
+              <SegmentBadge label={`seg-2 (active)`} active />
+            </div>
+          )}
+        </div>
+      );
+    });
+
+  const topics = [
+    { key: "user", name: "user-events", partitionCount: 3, messageRate: "~2.4M msg/s" },
+    { key: "order", name: "order-events", partitionCount: 3, messageRate: "~1.8M msg/s" },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-5">Stream Hierarchy</h3>
+
+      <div className="rounded-xl border-2 border-fd-primary/40 bg-fd-primary/5 p-4">
+        <button
+          onClick={() => toggle("stream")}
+          className="flex items-center gap-2 w-full text-left"
+        >
+          <Chevron open={expanded.stream} />
+          <span className="w-3 h-3 rounded bg-fd-primary shrink-0" />
+          <span className="text-sm font-mono font-bold text-fd-foreground">Stream: orders</span>
+          <span className="text-[10px] text-fd-muted-foreground ml-auto">ID: 1</span>
+        </button>
+
+        {expanded.stream && (
+          <div className="mt-3 space-y-2">
+            {topics.map((topic) => (
+              <div
+                key={topic.key}
+                className="ml-4 rounded-lg border border-[#3b82f6]/30 bg-[#3b82f6]/5 p-3"
+              >
+                <button
+                  onClick={() => toggle(`topic-${topic.key}`)}
+                  className="flex items-center gap-2 w-full text-left"
+                >
+                  <Chevron open={!!expanded[`topic-${topic.key}`]} />
+                  <span className="w-2.5 h-2.5 rounded bg-[#3b82f6] shrink-0" />
+                  <span className="text-xs font-mono font-bold text-fd-foreground">Topic: {topic.name}</span>
+                  <span className="text-[10px] text-fd-muted-foreground ml-auto">{topic.partitionCount} partitions / {topic.messageRate}</span>
+                </button>
+
+                {expanded[`topic-${topic.key}`] && (
+                  <div className="mt-1">
+                    {partitions(topic.key)}
+                  </div>
+                )}
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className="mt-4 flex items-center gap-4 text-[11px] text-fd-muted-foreground">
+        <span className="flex items-center gap-1.5"><span className="w-2.5 h-2.5 rounded bg-fd-primary" /> Stream</span>
+        <span className="flex items-center gap-1.5"><span className="w-2.5 h-2.5 rounded bg-[#3b82f6]" /> Topic</span>
+        <span className="flex items-center gap-1.5"><span className="w-2.5 h-2.5 rounded-full bg-[#10b981]" /> Partition</span>
+        <span className="flex items-center gap-1.5"><span className="w-2 h-2 rounded bg-fd-muted-foreground/40" /> Segment</span>
+      </div>
+    </div>
+  );
+}
+
+export function AppendOnlyLogViz() {
+  const [offsets, setOffsets] = useState([0, 1, 2, 3, 4, 5]);
+  const [consumerOffset, setConsumerOffset] = useState(2);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setOffsets((prev) => {
+        const next = prev[prev.length - 1] + 1;
+        const updated = [...prev, next];
+        return updated.length > 12 ? updated.slice(1) : updated;
+      });
+    }, 2500);
+    return () => clearInterval(timer);
+  }, []);
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Append-Only Log</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-5">
+        Messages are appended sequentially. Consumers track their position independently via offsets.
+      </p>
+
+      <div className="relative">
+        <div className="flex items-end gap-1 overflow-hidden pb-8 pt-6">
+          {offsets.map((offset, i) => {
+            const isLast = i === offsets.length - 1;
+            const isAtConsumer = offset === consumerOffset;
+            return (
+              <button
+                key={offset}
+                onClick={() => setConsumerOffset(offset)}
+                className={`
+                  relative flex-shrink-0 w-14 h-16 rounded-md border flex flex-col items-center justify-center transition-all duration-500
+                  ${isLast
+                    ? "border-fd-primary/60 bg-fd-primary/15 shadow-lg shadow-fd-primary/20 animate-pulse"
+                    : isAtConsumer
+                      ? "border-emerald-500/60 bg-emerald-500/10"
+                      : offset < consumerOffset
+                        ? "border-fd-border/50 bg-fd-muted/20 opacity-50"
+                        : "border-fd-border bg-fd-muted/30"
+                  }
+                `}
+              >
+                <span className="text-[10px] font-mono text-fd-muted-foreground">msg</span>
+                <span className="text-sm font-mono font-bold text-fd-foreground">{offset}</span>
+              </button>
+            );
+          })}
+
+          <div className="flex-shrink-0 w-14 h-16 rounded-md border-2 border-dashed border-fd-primary/40 flex flex-col items-center justify-center">
+            <span className="relative flex h-3 w-3">
+              <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-fd-primary opacity-75" />
+              <span className="relative inline-flex rounded-full h-3 w-3 bg-fd-primary" />
+            </span>
+            <span className="text-[9px] font-mono text-fd-primary mt-1">write</span>
+          </div>
+        </div>
+
+        <div className="absolute bottom-0 left-0 right-0 flex gap-1 px-0">
+          {offsets.map((offset) => {
+            const isAtConsumer = offset === consumerOffset;
+            return (
+              <div key={offset} className="flex-shrink-0 w-14 flex flex-col items-center">
+                {isAtConsumer && (
+                  <>
+                    <svg width="12" height="8" viewBox="0 0 12 8" className="text-emerald-500">
+                      <path d="M6 0L12 8H0z" fill="currentColor" />
+                    </svg>
+                    <span className="text-[9px] font-mono font-bold text-emerald-500">consumer</span>
+                  </>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      </div>
+
+      <p className="text-[11px] text-fd-muted-foreground m-0 mt-4">
+        Click any message block to move the consumer pointer. New messages appear from the right.
+      </p>
+    </div>
+  );
+}
+
+export function ConsumerGroupViz() {
+  const consumers = [
+    { id: "A", color: "#f59e0b", partitions: ["P1", "P4"] },
+    { id: "B", color: "#3b82f6", partitions: ["P2", "P5"] },
+    { id: "C", color: "#10b981", partitions: ["P3", "P6"] },
+  ];
+
+  const allPartitions = ["P1", "P2", "P3", "P4", "P5", "P6"];
+
+  const getConsumerForPartition = (p: string) =>
+    consumers.find((c) => c.partitions.includes(p))!;
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Consumer Group</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-6">
+        Each partition is assigned to exactly one consumer. When a consumer joins or leaves, partitions are rebalanced.
+      </p>
+
+      <div className="grid grid-cols-1 md:grid-cols-[1fr_auto_1fr] gap-6 items-center">
+        <div className="space-y-3">
+          <span className="text-[11px] font-mono text-fd-muted-foreground uppercase tracking-wider">Consumers</span>
+          {consumers.map((c) => (
+            <div
+              key={c.id}
+              className="flex items-center gap-3 rounded-lg border border-fd-border p-3 bg-fd-muted/10"
+              style={{ borderLeftColor: c.color, borderLeftWidth: 3 }}
+            >
+              <div
+                className="w-8 h-8 rounded-full flex items-center justify-center text-white text-xs font-bold shrink-0"
+                style={{ backgroundColor: c.color }}
+              >
+                {c.id}
+              </div>
+              <div>
+                <span className="text-xs font-mono font-medium text-fd-foreground block">Consumer {c.id}</span>
+                <span className="text-[10px] text-fd-muted-foreground">{c.partitions.join(", ")}</span>
+              </div>
+            </div>
+          ))}
+        </div>
+
+        <div className="hidden md:flex flex-col items-center gap-1">
+          {[0, 1, 2, 3, 4, 5].map((i) => {
+            const consumer = consumers[i % 3];
+            return (
+              <div key={i} className="flex items-center gap-0">
+                <div className="w-12 h-px" style={{ backgroundColor: consumer.color + "80" }} />
+                <svg width="8" height="8" viewBox="0 0 8 8" style={{ color: consumer.color }}>
+                  <path d="M0 0L8 4L0 8z" fill="currentColor" opacity="0.6" />
+                </svg>
+              </div>
+            );
+          })}
+        </div>
+
+        <div className="space-y-3">
+          <span className="text-[11px] font-mono text-fd-muted-foreground uppercase tracking-wider">Partitions</span>
+          <div className="grid grid-cols-2 gap-2">
+            {allPartitions.map((p) => {
+              const consumer = getConsumerForPartition(p);
+              return (
+                <div
+                  key={p}
+                  className="flex items-center gap-2 rounded-lg border border-fd-border p-2.5 bg-fd-muted/10"
+                >
+                  <div
+                    className="w-2 h-2 rounded-full shrink-0"
+                    style={{ backgroundColor: consumer.color }}
+                  />
+                  <span className="text-xs font-mono font-bold text-fd-foreground">{p}</span>
+                  <span
+                    className="text-[9px] font-mono ml-auto px-1.5 py-0.5 rounded"
+                    style={{ backgroundColor: consumer.color + "20", color: consumer.color }}
+                  >
+                    {consumer.id}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function ServerEcosystem() {
+  const ring = [
+    { label: "Producers", sub: "Send messages", color: "#f59e0b", pos: "top" },
+    { label: "Consumers", sub: "Poll messages", color: "#10b981", pos: "top" },
+    { label: "Consumer Groups", sub: "Horizontal scaling", color: "#3b82f6", pos: "top" },
+    { label: "Web UI", sub: "Dashboard", color: "#a855f7", pos: "bottom", href: "/docs/web_ui/start" },
+    { label: "CLI", sub: "Terminal management", color: "#6366f1", pos: "bottom", href: "/docs/cli/start" },
+    { label: "MCP Server", sub: "LLM integration", color: "#ec4899", pos: "bottom", href: "/docs/ai/mcp" },
+    { label: "Connectors", sub: "Sources & Sinks", color: "#14b8a6", pos: "bottom", href: "/docs/connectors/introduction" },
+    { label: "Benchmarks", sub: "iggy-bench", color: "#f97316", pos: "bottom", href: "/docs/server/benchmarking" },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <div className="flex flex-col items-center mb-6">
+        <div className="relative rounded-2xl border-2 border-fd-primary/40 bg-gradient-to-br from-fd-primary/10 to-fd-primary/5 px-8 py-5 text-center shadow-lg shadow-fd-primary/10">
+          <div className="absolute -top-1 -right-1 w-3 h-3 rounded-full bg-fd-primary shard-pulse" />
+          <span className="text-lg font-bold text-fd-primary block">Iggy Server</span>
+          <span className="text-xs text-fd-muted-foreground block mt-1">Thread-per-core + io_uring</span>
+          <div className="flex justify-center gap-1.5 mt-2">
+            {["TCP :8090", "QUIC :8080", "HTTP :3000", "WS :8092"].map((p) => (
+              <span key={p} className="px-1.5 py-0.5 rounded text-[8px] font-mono font-medium bg-fd-primary/15 text-fd-primary">{p}</span>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+        {ring.map((item) => {
+          const inner = (
+            <>
+              <div className="flex items-center gap-1.5 mb-0.5">
+                <span className="w-2 h-2 rounded-full shrink-0" style={{ backgroundColor: item.color }} />
+                <span className="text-xs font-semibold text-fd-foreground group-hover:text-fd-primary transition-colors">{item.label}</span>
+              </div>
+              <span className="text-[10px] text-fd-muted-foreground pl-3.5">{item.sub}</span>
+            </>
+          );
+          const cls = "rounded-lg border border-fd-border bg-fd-muted/10 p-3 transition-all hover:border-fd-primary/30 hover:shadow-md hover:shadow-fd-primary/5 group";
+          if ("href" in item && item.href) {
+            return <a key={item.label} href={item.href} className={`${cls} no-underline`}>{inner}</a>;
+          }
+          return <div key={item.label} className={cls}>{inner}</div>;
+        })}
+      </div>
+
+      <div className="mt-4 rounded-lg bg-fd-muted/20 p-3">
+        <div className="flex flex-wrap justify-center gap-x-5 gap-y-1 text-[10px] text-fd-muted-foreground">
+          <span><strong className="text-fd-foreground">SDKs:</strong> Rust, Python, Java, Go, Node.js, C#, C++</span>
+          <span><strong className="text-fd-foreground">Security:</strong> TLS, Argon2id, AES-256-GCM, RBAC</span>
+          <span><strong className="text-fd-foreground">Observability:</strong> Prometheus, OpenTelemetry</span>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function ConnectorPipeline() {
+  const sources = [
+    { name: "PostgreSQL", color: "#336791" },
+    { name: "Elasticsearch", color: "#00bfb3" },
+    { name: "Random", color: "#6b7280" },
+  ];
+  const sinks = [
+    { name: "PostgreSQL", color: "#336791" },
+    { name: "MongoDB", color: "#47a248" },
+    { name: "Elasticsearch", color: "#00bfb3" },
+    { name: "Iceberg", color: "#4a90d9" },
+    { name: "Quickwit", color: "#a855f7" },
+    { name: "Stdout", color: "#6b7280" },
+  ];
+  const transforms = ["add_fields", "delete_fields", "filter_fields", "update_fields"];
+
+  const Arrow = () => (
+    <>
+      <svg width="40" height="16" viewBox="0 0 40 16" className="text-fd-primary hidden md:block shrink-0">
+        <path d="M0 8h32l-5-5M32 8l-5 5" stroke="currentColor" strokeWidth="1.5" fill="none" />
+      </svg>
+      <svg width="16" height="32" viewBox="0 0 16 32" className="text-fd-primary md:hidden shrink-0 mx-auto">
+        <path d="M8 0v24l-5-5M8 24l5-5" stroke="currentColor" strokeWidth="1.5" fill="none" />
+      </svg>
+    </>
+  );
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Source Flow (Ingest)</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-4">External systems push data into Iggy streams via source plugins</p>
+
+      <div className="flex flex-col md:flex-row items-center gap-3 mb-8">
+        <div className="flex-1 w-full rounded-lg border border-fd-border bg-fd-muted/20 p-4">
+          <span className="text-xs font-semibold text-fd-muted-foreground block mb-2">External System</span>
+          <div className="flex flex-wrap gap-1.5">
+            {sources.map((s) => (
+              <span key={s.name} className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-lg text-xs font-medium bg-fd-card text-fd-foreground border border-fd-border">
+                <span className="w-2 h-2 rounded-full" style={{ backgroundColor: s.color }} />
+                {s.name}
+              </span>
+            ))}
+          </div>
+        </div>
+
+        <Arrow />
+
+        <div className="flex-1 w-full rounded-lg border border-emerald-500/30 bg-emerald-500/5 p-4">
+          <span className="text-xs font-semibold text-emerald-400 block mb-1">Source Plugin</span>
+          <span className="text-[10px] text-fd-muted-foreground block mb-2">poll() via FFI/postcard</span>
+          <div className="rounded bg-fd-muted/30 px-2 py-1">
+            <span className="text-[10px] text-fd-muted-foreground">Transforms: </span>
+            {transforms.map((t, i) => (
+              <span key={t}>
+                <code className="text-[9px] text-fd-foreground">{t}</code>
+                {i < transforms.length - 1 && <span className="text-[10px] text-fd-muted-foreground">, </span>}
+              </span>
+            ))}
+          </div>
+        </div>
+
+        <Arrow />
+
+        <div className="shrink-0 rounded-lg border-2 border-fd-primary/40 bg-fd-primary/5 px-5 py-3 text-center">
+          <span className="text-sm font-bold text-fd-primary block">Iggy</span>
+          <span className="text-[10px] text-fd-muted-foreground">Stream / Topic</span>
+        </div>
+      </div>
+
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Sink Flow (Egress)</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-4">Iggy streams forward data to external systems via sink plugins</p>
+
+      <div className="flex flex-col md:flex-row items-center gap-3">
+        <div className="shrink-0 rounded-lg border-2 border-fd-primary/40 bg-fd-primary/5 px-5 py-3 text-center">
+          <span className="text-sm font-bold text-fd-primary block">Iggy</span>
+          <span className="text-[10px] text-fd-muted-foreground">Consumer Group</span>
+        </div>
+
+        <Arrow />
+
+        <div className="flex-1 w-full rounded-lg border border-blue-500/30 bg-blue-500/5 p-4">
+          <span className="text-xs font-semibold text-blue-400 block mb-1">Sink Plugin</span>
+          <span className="text-[10px] text-fd-muted-foreground block mb-2">consume() via FFI/postcard</span>
+          <div className="rounded bg-fd-muted/30 px-2 py-1">
+            <span className="text-[10px] text-fd-muted-foreground">Transforms: </span>
+            {transforms.map((t, i) => (
+              <span key={t}>
+                <code className="text-[9px] text-fd-foreground">{t}</code>
+                {i < transforms.length - 1 && <span className="text-[10px] text-fd-muted-foreground">, </span>}
+              </span>
+            ))}
+          </div>
+        </div>
+
+        <Arrow />
+
+        <div className="flex-1 w-full rounded-lg border border-fd-border bg-fd-muted/20 p-4">
+          <span className="text-xs font-semibold text-fd-muted-foreground block mb-2">External System</span>
+          <div className="flex flex-wrap gap-1.5">
+            {sinks.map((s) => (
+              <span key={s.name} className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-lg text-xs font-medium bg-fd-card text-fd-foreground border border-fd-border">
+                <span className="w-2 h-2 rounded-full" style={{ backgroundColor: s.color }} />
+                {s.name}
+              </span>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function WhyIggy() {
+  const comparisons = [
+    {
+      label: "Runtime",
+      traditional: "JVM / Go runtime with GC pauses",
+      iggy: "Native Rust, zero GC, predictable latency",
+      iggyColor: "#10b981",
+    },
+    {
+      label: "I/O model",
+      traditional: "epoll + blocking thread pool for disk",
+      iggy: "io_uring completion-based, kernel does the I/O",
+      iggyColor: "#f59e0b",
+    },
+    {
+      label: "Threading",
+      traditional: "Work-stealing across shared threads",
+      iggy: "Thread-per-core, CPU-pinned, NUMA-aware",
+      iggyColor: "#3b82f6",
+    },
+    {
+      label: "Serialization",
+      traditional: "Full deserialization on every read",
+      iggy: "Zero-copy views into raw buffers",
+      iggyColor: "#8b5cf6",
+    },
+    {
+      label: "Memory",
+      traditional: "Heap allocations on hot path",
+      iggy: "Pre-allocated 4 GiB pool, 32 bucket sizes",
+      iggyColor: "#ec4899",
+    },
+    {
+      label: "Binary",
+      traditional: "JVM + Zookeeper / KRaft + dependencies",
+      iggy: "Single ~20 MB binary, no dependencies",
+      iggyColor: "#14b8a6",
+    },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-border bg-fd-card p-6">
+      <h3 className="text-lg font-semibold text-fd-foreground m-0 mb-2">Why Iggy?</h3>
+      <p className="text-xs text-fd-muted-foreground m-0 mb-5">How Iggy compares to traditional message streaming platforms</p>
+
+      <div className="space-y-2">
+        <div className="grid grid-cols-[100px_1fr_1fr] md:grid-cols-[120px_1fr_1fr] gap-2 mb-1">
+          <span className="text-[10px] font-semibold text-fd-muted-foreground" />
+          <span className="text-[10px] font-semibold text-fd-muted-foreground text-center">Traditional</span>
+          <span className="text-[10px] font-semibold text-fd-primary text-center">Iggy</span>
+        </div>
+        {comparisons.map((c) => (
+          <div key={c.label} className="grid grid-cols-[100px_1fr_1fr] md:grid-cols-[120px_1fr_1fr] gap-2 items-center">
+            <span className="text-[11px] font-semibold text-fd-foreground">{c.label}</span>
+            <div className="rounded-md bg-fd-muted/30 px-3 py-2 text-center">
+              <span className="text-[10px] text-fd-muted-foreground">{c.traditional}</span>
+            </div>
+            <div className="rounded-md border px-3 py-2 text-center" style={{ borderColor: `${c.iggyColor}40`, backgroundColor: `${c.iggyColor}08` }}>
+              <span className="text-[10px] text-fd-foreground">{c.iggy}</span>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function QuickStartSnippet() {
+  const steps = [
+    { n: "1", label: "Start the server", code: "docker run --cap-add=SYS_NICE --security-opt seccomp=unconfined --ulimit memlock=-1:-1 -p 8090:8090 apache/iggy" },
+    { n: "2", label: "Add the SDK", code: "cargo add iggy" },
+    { n: "3", label: "Connect and send", code: 'let client = IggyClient::from_connection_string("iggy://iggy:iggy@localhost:8090")?;\nclient.connect().await?;' },
+  ];
+
+  return (
+    <div className="my-8 rounded-xl border border-fd-primary/20 bg-gradient-to-br from-fd-card to-fd-primary/3 p-6">
+      <div className="flex items-center justify-between mb-5">
+        <h3 className="text-lg font-semibold text-fd-foreground m-0">Quick start</h3>
+        <a href="/docs/introduction/getting-started" className="text-xs text-fd-primary no-underline hover:underline">Full tutorial →</a>
+      </div>
+
+      <div className="space-y-4">
+        {steps.map((s) => (
+          <div key={s.n} className="flex items-start gap-3">
+            <span className="inline-flex items-center justify-center w-6 h-6 rounded-full bg-fd-primary text-fd-primary-foreground text-xs font-bold shrink-0 mt-1">{s.n}</span>
+            <div className="flex-1 min-w-0">
+              <span className="text-sm font-semibold text-fd-foreground block mb-1.5">{s.label}</span>
+              <pre className="text-[12px] font-mono text-fd-muted-foreground bg-fd-muted/30 rounded-lg px-3 py-2 m-0 overflow-x-auto whitespace-pre"><code>{s.code}</code></pre>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <div className="flex flex-wrap gap-1.5 mt-4 pl-9">
+        <span className="text-[10px] text-fd-muted-foreground mr-1">SDKs:</span>
+        {["Rust", "Python", "Java", "Go", "Node.js", "C#", "C++"].map((l) => (
+          <span key={l} className="px-2 py-0.5 rounded-full text-[10px] font-medium bg-fd-muted/50 text-fd-muted-foreground">{l}</span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function DocsHero() {
+  const stats = [
+    { stat: "Sub-ms latency", accent: "Tail latency under 1ms at P99" },
+    { stat: "Millions msgs/sec", accent: "Multi GB/s throughput on a single node" },
+    { stat: "Zero-copy I/O", accent: "io_uring + vectored writes to disk" },
+  ];
+
+  const sources = [
+    { name: "PostgreSQL", color: "#336791" },
+    { name: "Elasticsearch", color: "#00bfb3" },
+    { name: "Random", color: "#6b7280" },
+  ];
+
+  const sinks = [
+    { name: "PostgreSQL", color: "#336791" },
+    { name: "MongoDB", color: "#47a248" },
+    { name: "Elasticsearch", color: "#00bfb3" },
+    { name: "Iceberg", color: "#4a90d9" },
+    { name: "Quickwit", color: "#a855f7" },
+  ];
+
+  const links = [
+    { title: "Getting Started", href: "/docs/introduction/getting-started", desc: "Install, configure, send your first messages", icon: "M13 10V3L4 14h7v7l9-11h-7z" },
+    { title: "Architecture", href: "/docs/introduction/architecture", desc: "Thread-per-core, io_uring, shared-nothing design", icon: "M4 5a1 1 0 011-1h14a1 1 0 011 1v2a1 1 0 01-1 1H5a1 1 0 01-1-1V5zm0 8a1 1 0 011-1h6a1 1 0 011 1v2a1 1 0 01-1 1H5a1 1 0 01-1-1v-2zm10 0a1 1 0 011-1h4a1 1 0 011 1v2a1 1 0 01-1 1h-4a1 1 0 01-1-1v-2z" },
+    { title: "Connectors", href: "/docs/connectors/introduction", desc: "Source & sink plugins for data integration", icon: "M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" },
+    { title: "SDKs", href: "/docs/sdk/introduction", desc: "Rust, Python, Java, Go, Node.js, C#, C++", icon: "M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4" },
+    { title: "Server Config", href: "/docs/server/configuration", desc: "Tune performance, storage, and security", icon: "M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.75 [...]
+    { title: "CLI & Web UI", href: "/docs/cli/start", desc: "Manage streams, topics, users from terminal or browser", icon: "M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" },
+  ];
+
+  return (
+    <div className="relative my-8 rounded-2xl border border-fd-primary/20 bg-gradient-to-br from-fd-card via-fd-card to-fd-primary/5 p-8 overflow-hidden">
+      <div className="absolute inset-0 bg-[radial-gradient(ellipse_at_top_right,var(--color-fd-primary)_0%,transparent_60%)] opacity-[0.07]" />
+      <div className="absolute top-0 right-0 w-64 h-64 bg-fd-primary/5 rounded-full blur-3xl -translate-y-1/2 translate-x-1/2" />
+
+      <div className="relative z-10">
+        <div className="flex flex-col items-center text-center mb-8">
+          <img src="/img/apache-iggy-color-darkbg0.5x.png" alt="Apache Iggy" width={200} className="mb-5" />
+          <h2 className="text-2xl md:text-3xl font-bold text-fd-foreground m-0 mb-2">
+            <span className="text-fd-primary">Hyper-Efficient</span> Message Streaming
+          </h2>
+          <h2 className="text-2xl md:text-3xl font-bold text-fd-foreground m-0 mb-3">
+            at <span className="text-fd-primary">Laser Speed</span>
+          </h2>
+          <p className="text-sm md:text-base text-fd-muted-foreground max-w-2xl m-0 mb-1">
+            High-performance, persistent message streaming platform written in Rust, capable of processing millions of messages per second with ultra-low latency.
+          </p>
+          <p className="text-xs text-fd-muted-foreground/60 m-0 italic">
+            Named after the Italian Greyhound - small yet extremely fast
+          </p>
+        </div>
+
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mb-8">
+          {stats.map((item) => (
+            <div key={item.stat} className="relative rounded-xl border border-fd-primary/20 bg-fd-card/80 backdrop-blur p-5 text-center group hover:border-fd-primary/40 transition-colors">
+              <div className="absolute inset-0 rounded-xl bg-fd-primary/5 opacity-0 group-hover:opacity-100 transition-opacity" />
+              <div className="relative">
+                <div className="w-2 h-2 rounded-full bg-fd-primary mx-auto mb-3 shadow-[0_0_8px_var(--color-fd-primary)]" />
+                <span className="text-base font-bold text-fd-foreground block">{item.stat}</span>
+                <span className="text-xs text-fd-muted-foreground mt-1 block">{item.accent}</span>
+              </div>
+            </div>
+          ))}
+        </div>
+
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-3 mb-8">
+          {links.map((link) => (
+            <a key={link.title} href={link.href} className="group rounded-xl border border-fd-border bg-fd-card/60 backdrop-blur p-4 no-underline transition-all hover:border-fd-primary/40 hover:shadow-lg hover:shadow-fd-primary/5">
+              <div className="flex items-center gap-2 mb-1">
+                <svg width="16" height="16" viewBox="0 0 24 24" className="text-fd-muted-foreground group-hover:text-fd-primary transition-colors shrink-0" fill="none" strokeWidth="1.5" stroke="currentColor">
+                  <path d={link.icon} strokeLinecap="round" strokeLinejoin="round" />
+                </svg>
+                <span className="text-sm font-semibold text-fd-foreground group-hover:text-fd-primary transition-colors">{link.title}</span>
+              </div>
+              <span className="text-xs text-fd-muted-foreground">{link.desc}</span>
+            </a>
+          ))}
+        </div>
+
+        <div className="rounded-xl border border-fd-border bg-fd-card/60 backdrop-blur p-5">
+          <div className="flex items-center gap-2 mb-4">
+            <div className="w-2 h-2 rounded-full bg-fd-primary shard-pulse" />
+            <a href="/docs/connectors/introduction" className="text-sm font-semibold text-fd-foreground no-underline hover:text-fd-primary transition-colors">Connectors: Data Integration Pipeline</a>
+          </div>
+
+          <div className="flex flex-col md:flex-row items-stretch gap-3">
+            <div className="flex-1 rounded-lg border border-emerald-500/20 bg-emerald-500/5 p-3">
+              <a href="/docs/connectors/introduction" className="text-xs font-semibold text-emerald-400 block mb-2 no-underline hover:underline">Sources</a>
+              <div className="flex flex-wrap gap-1.5">
+                {sources.map((s) => (
+                  <span key={s.name} className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-medium bg-fd-muted/50 text-fd-foreground">
+                    <span className="w-1.5 h-1.5 rounded-full" style={{ backgroundColor: s.color }} />
+                    {s.name}
+                  </span>
+                ))}
+              </div>
+            </div>
+
+            <div className="flex items-center justify-center px-2">
+              <svg width="32" height="16" viewBox="0 0 32 16" className="text-fd-primary hidden md:block">
+                <path d="M0 8h24l-5-5M24 8l-5 5" stroke="currentColor" strokeWidth="1.5" fill="none" />
+              </svg>
+              <svg width="16" height="24" viewBox="0 0 16 24" className="text-fd-primary md:hidden">
+                <path d="M8 0v18l-5-5M8 18l5-5" stroke="currentColor" strokeWidth="1.5" fill="none" />
+              </svg>
+            </div>
+
+            <a href="/docs/introduction/architecture" className="flex-1 rounded-lg border-2 border-fd-primary/30 bg-fd-primary/5 p-3 text-center no-underline group hover:border-fd-primary/50 transition-colors">
+              <span className="text-sm font-bold text-fd-primary block">Iggy Server</span>
+              <span className="text-[10px] text-fd-muted-foreground block mt-1">Thread-per-core + io_uring</span>
+              <div className="flex justify-center gap-1 mt-2">
+                {["TCP", "QUIC", "WS", "HTTP"].map((p) => (
+                  <span key={p} className="px-1.5 py-0.5 rounded text-[8px] font-mono font-bold bg-fd-primary/15 text-fd-primary">{p}</span>
+                ))}
+              </div>
+            </a>
+
+            <div className="flex items-center justify-center px-2">
+              <svg width="32" height="16" viewBox="0 0 32 16" className="text-fd-primary hidden md:block">
+                <path d="M0 8h24l-5-5M24 8l-5 5" stroke="currentColor" strokeWidth="1.5" fill="none" />
+              </svg>
+              <svg width="16" height="24" viewBox="0 0 16 24" className="text-fd-primary md:hidden">
+                <path d="M8 0v18l-5-5M8 18l5-5" stroke="currentColor" strokeWidth="1.5" fill="none" />
+              </svg>
+            </div>
+
+            <div className="flex-1 rounded-lg border border-blue-500/20 bg-blue-500/5 p-3">
+              <a href="/docs/connectors/introduction" className="text-xs font-semibold text-blue-400 block mb-2 no-underline hover:underline">Sinks</a>
+              <div className="flex flex-wrap gap-1.5">
+                {sinks.map((s) => (
+                  <span key={s.name} className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-medium bg-fd-muted/50 text-fd-foreground">
+                    <span className="w-1.5 h-1.5 rounded-full" style={{ backgroundColor: s.color }} />
+                    {s.name}
+                  </span>
+                ))}
+              </div>
+            </div>
+          </div>
+
+          <div className="flex justify-center gap-5 mt-4 pt-3 border-t border-fd-border/50">
+            {[
+              { label: "MCP Server", href: "/docs/ai/mcp", sub: "40+ LLM tools" },
+              { label: "Web UI", href: "/docs/web_ui/start", sub: "Dashboard" },
+              { label: "CLI", href: "/docs/cli/start", sub: "Terminal" },
+              { label: "7 SDKs", href: "/docs/sdk/introduction", sub: "All languages" },
+            ].map((t) => (
+              <a key={t.label} href={t.href} className="text-center no-underline group">
+                <span className="text-[10px] font-semibold text-fd-foreground group-hover:text-fd-primary transition-colors block">{t.label}</span>
+                <span className="text-[8px] text-fd-muted-foreground">{t.sub}</span>
+              </a>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/benchmark-chart.tsx b/src/components/benchmark-chart.tsx
new file mode 100644
index 00000000..b55edcfe
--- /dev/null
+++ b/src/components/benchmark-chart.tsx
@@ -0,0 +1,151 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import Link from "next/link";
+
+const WRITE_PATH =
+  "M0,128 L8,155 L16,161 L24,130 L32,125 L40,153 L48,165 L56,129 L64,154 L72,150 L80,118 L88,166 L96,131 L104,128 L112,157 L120,130 L128,131 L136,160 L144,132 L152,135 L160,166 L168,134 L176,137 L184,164 L192,122 L200,146 L208,148 L216,131 L224,130 L232,162 L240,126 L248,124 L256,163 L264,129 L272,135 L280,166 L288,131 L296,128 L304,163 L312,162 L320,131 L328,166 L336,133 L344,152 L352,158 L360,131 L368,128 L376,163 L384,120 L392,157 L400,164 L408,132 L416,115 L424,152 L432,125 L440,114  [...]
+
+const READ_PATH =
+  "M0,151 L8,154 L16,155 L24,154 L32,156 L40,154 L48,155 L56,152 L64,154 L72,154 L80,152 L88,154 L96,153 L104,154 L112,152 L120,156 L128,153 L136,154 L144,153 L152,156 L160,152 L168,153 L176,153 L184,156 L192,155 L200,154 L208,155 L216,153 L224,154 L232,153 L240,154 L248,152 L256,155 L264,152 L272,152 L280,155 L288,154 L296,155 L304,154 L312,153 L320,155 L328,155 L336,152 L344,152 L352,156 L360,154 L368,157 L376,156 L384,157 L392,156 L400,152 L408,153 L416,155 L424,157 L432,155 L440,157  [...]
+
+const CY = (ms: number) => 200 - ms * 60;
+const yTicks = [0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0];
+
+export function BenchmarkSection() {
+  const ref = useRef<HTMLDivElement>(null);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      setVisible(true);
+      return;
+    }
+    const observer = new IntersectionObserver(
+      ([entry]) => { if (entry.isIntersecting) { setVisible(true); observer.unobserve(el); } },
+      { threshold: 0.15 },
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const wrAvg = CY(1.01);
+  const wrP99 = CY(2.05);
+
+  return (
+    <div ref={ref}>
+      <style>{`
+        @keyframes iggy-draw { from { stroke-dashoffset: 2400 } to { stroke-dashoffset: 0 } }
+        @keyframes iggy-area-in { from { opacity: 0 } to { opacity: 1 } }
+        @keyframes iggy-label-in { from { opacity: 0; transform: translateX(8px) } to { opacity: 1; transform: translateX(0) } }
+        .iggy-line { stroke-dasharray: 2400; stroke-dashoffset: 2400 }
+        .iggy-area-wr, .iggy-area-rd { opacity: 0 }
+        .iggy-label { opacity: 0 }
+        .iggy-go .iggy-line { animation: iggy-draw 2s cubic-bezier(0.4,0,0.2,1) forwards }
+        .iggy-go .iggy-line-rd { animation-delay: 0.3s }
+        .iggy-go .iggy-area-wr { animation: iggy-area-in 0.8s ease 1s forwards }
+        .iggy-go .iggy-area-rd { animation: iggy-area-in 0.8s ease 1.3s forwards }
+        .iggy-go .iggy-label { animation: iggy-label-in 0.4s ease 2s forwards }
+      `}</style>
+
+      <div className="mb-6 grid grid-cols-2 md:grid-cols-5 gap-4">
+        {[
+          { value: "1M+", unit: "msg/s", label: "Throughput", sub: null },
+          { value: "+1 GB/s", unit: "write", label: "Producer throughput", sub: null },
+          { value: "+3 GB/s", unit: "read", label: "Consumer throughput", sub: null },
+          { value: "1.01", unit: "ms", label: "Avg write latency", sub: null },
+          { value: "2.05", unit: "ms", label: "P99 write latency", sub: null },
+        ].map((s) => (
+          <div key={s.label} className="rounded-xl border border-white/[0.06] bg-white/[0.03] px-5 py-5">
+            <div className="mb-1 flex items-baseline gap-1.5">
+              <span className="text-3xl font-extrabold text-white">{s.value}</span>
+              <span className="text-sm font-medium text-neutral-400">{s.unit}</span>
+            </div>
+            <div className="text-sm text-neutral-500">{s.label}</div>
+            {s.sub && <div className="mt-1 text-xs text-neutral-600">{s.sub}</div>}
+          </div>
+        ))}
+      </div>
+
+      <div className="rounded-xl border border-white/[0.06] bg-[#060a12] overflow-hidden">
+        <div className="flex items-center justify-between border-b border-white/[0.04] px-5 py-3">
+          <div className="flex items-center gap-6">
+            <div className="flex items-center gap-2">
+              <div className="h-[3px] w-5 rounded-full bg-[#ff9103]" />
+              <span className="text-xs text-neutral-400">Write</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <div className="h-[3px] w-5 rounded-full bg-[#38bdf8]" />
+              <span className="text-xs text-neutral-400">Read</span>
+            </div>
+          </div>
+          <span className="text-xs text-neutral-600">Latency (ms) · 40M messages</span>
+        </div>
+
+        <div className="flex">
+          <div className="flex w-10 shrink-0 flex-col justify-between py-3 pr-1 text-right font-mono text-[9px] text-neutral-600 sm:w-12">
+            {[...yTicks].reverse().map((ms) => (
+              <div key={ms} className="leading-none">{ms.toFixed(1)}</div>
+            ))}
+          </div>
+
+          <div className="min-w-0 flex-1 py-3 pr-3">
+            <svg
+              viewBox="0 0 600 200"
+              className={visible ? "iggy-go" : ""}
+              preserveAspectRatio="none"
+              style={{ width: "100%", height: "auto", aspectRatio: "600 / 200" }}
+            >
+              <defs>
+                <linearGradient id="iggy-wr-g" x1="0" y1="0" x2="0" y2="1">
+                  <stop offset="0%" stopColor="#ff9103" stopOpacity="0.15" />
+                  <stop offset="100%" stopColor="#ff9103" stopOpacity="0" />
+                </linearGradient>
+                <linearGradient id="iggy-rd-g" x1="0" y1="0" x2="0" y2="1">
+                  <stop offset="0%" stopColor="#38bdf8" stopOpacity="0.08" />
+                  <stop offset="100%" stopColor="#38bdf8" stopOpacity="0" />
+                </linearGradient>
+              </defs>
+
+              {yTicks.map((ms) => (
+                <line key={ms} x1="0" y1={CY(ms)} x2="600" y2={CY(ms)} stroke="white" strokeOpacity="0.03" />
+              ))}
+
+              <path d={WRITE_PATH + " L600,200 L0,200 Z"} fill="url(#iggy-wr-g)" className="iggy-area-wr" />
+              <path d={WRITE_PATH} fill="none" stroke="#ff9103" strokeWidth="2" strokeLinejoin="round" className="iggy-line" />
+
+              <path d={READ_PATH + " L600,200 L0,200 Z"} fill="url(#iggy-rd-g)" className="iggy-area-rd" />
+              <path d={READ_PATH} fill="none" stroke="#38bdf8" strokeWidth="1.5" strokeLinejoin="round" className="iggy-line iggy-line-rd" />
+
+              <g className="iggy-label">
+                <line x1="0" y1={wrAvg} x2="600" y2={wrAvg} stroke="#ff9103" strokeOpacity="0.25" strokeDasharray="4 3" />
+                <rect x="540" y={wrAvg - 11} width="56" height="18" rx="4" fill="#ff9103" fillOpacity="0.12" />
+                <text x="568" y={wrAvg + 2} textAnchor="middle" fill="#ff9103" fontSize="10" fontFamily="monospace" fontWeight="600">AVG</text>
+
+                <line x1="0" y1={wrP99} x2="600" y2={wrP99} stroke="#ff9103" strokeOpacity="0.15" strokeDasharray="4 3" />
+                <rect x="540" y={wrP99 - 11} width="56" height="18" rx="4" fill="#ff9103" fillOpacity="0.08" />
+                <text x="568" y={wrP99 + 2} textAnchor="middle" fill="#ff9103" fontSize="10" fontFamily="monospace" fillOpacity="0.7">P99</text>
+              </g>
+            </svg>
+          </div>
+        </div>
+      </div>
+
+      <div className="mt-4 flex flex-wrap items-center justify-between gap-3 rounded-xl border border-white/[0.06] bg-white/[0.03] px-5 py-3.5">
+        <span className="font-mono text-sm text-neutral-500">
+          <span className="text-neutral-400">Machine:</span> AWS i3en.3xlarge · Intel Xeon 8259CL @ 2.50GHz
+        </span>
+        <div className="flex gap-5">
+          <Link href="https://benchmarks.iggy.apache.org/benchmarks/2c6a0f6a-fb4d-4e84-8ac0-bfca60c75b21" target="_blank" className="font-mono text-sm text-[#ff9103] no-underline hover:underline">
+            Producer →
+          </Link>
+          <Link href="https://benchmarks.iggy.apache.org/benchmarks/63607acc-5861-47c7-9673-5c1ce649ed0c" target="_blank" className="font-mono text-sm text-[#38bdf8] no-underline hover:underline">
+            Consumer →
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/code-tabs.tsx b/src/components/code-tabs.tsx
new file mode 100644
index 00000000..253b00b9
--- /dev/null
+++ b/src/components/code-tabs.tsx
@@ -0,0 +1,267 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+"use client";
+
+import { useState } from "react";
+import { highlight } from "sugar-high";
+
+const snippets = [
+  {
+    lang: "Rust",
+    file: "producer.rs",
+    href: "/docs/sdk/rust/intro",
+    code: `use iggy::prelude::*;
+
+let client = IggyClient::from_connection_string(
+    "iggy://iggy:iggy@localhost:8090"
+)?;
+client.connect().await?;
+
+client.create_stream("orders").await?;
+client.create_topic(
+    &"orders".try_into()?,
+    "events", 3,
+    CompressionAlgorithm::None,
+    None, IggyExpiry::NeverExpire,
+    MaxTopicSize::ServerDefault,
+).await?;
+
+let msg = IggyMessage::from_str("order-123")?;
+client.send_messages(
+    &"orders".try_into()?,
+    &"events".try_into()?,
+    &Partitioning::balanced(),
+    &mut [msg],
+).await?;`,
+  },
+  {
+    lang: "Python",
+    file: "producer.py",
+    href: "/docs/sdk/python/intro",
+    code: `from apache_iggy import IggyClient, SendMessage
+
+client = IggyClient.from_connection_string(
+    "iggy://iggy:iggy@localhost:8090"
+)
+await client.connect()
+
+await client.create_stream(name="orders")
+await client.create_topic(
+    stream="orders",
+    name="events",
+    partitions_count=3,
+)
+
+message = SendMessage(
+    payload=b"order-123"
+)
+await client.send_messages(
+    stream="orders",
+    topic="events",
+    partition_id=1,
+    messages=[message],
+)`,
+  },
+  {
+    lang: "Java",
+    file: "Producer.java",
+    href: "/docs/sdk/java/intro",
+    code: `var client = IggyTcpClient.builder()
+    .host("localhost")
+    .port(8090)
+    .credentials("iggy", "iggy")
+    .buildAndLogin();
+
+client.streams().createStream("orders");
+client.topics().createTopic(
+    "orders", "events", 3
+);
+
+client.messages().sendMessages(
+    "orders", "events",
+    Partitioning.balanced(),
+    Message.of("order-123")
+);
+
+client.close();`,
+  },
+  {
+    lang: "Go",
+    file: "producer.go",
+    href: "/docs/sdk/go/intro",
+    code: `cli, _ := client.NewIggyClient(
+    client.WithTcp("127.0.0.1", 8090),
+)
+cli.LogIn(iggcon.LogInRequest{
+    Username: "iggy",
+    Password: "iggy",
+})
+
+cli.CreateStream(iggcon.CreateStreamRequest{
+    Name: "orders",
+})
+cli.CreateTopic(iggcon.CreateTopicRequest{
+    StreamId: iggcon.NewIdentifier(1),
+    Name:     "events",
+    PartitionsCount: 3,
+})
+
+msg := iggcon.NewIggyMessage(
+    []byte("order-123"),
+)
+cli.SendMessages(iggcon.SendMessagesRequest{
+    StreamId: iggcon.NewIdentifier(1),
+    TopicId:  iggcon.NewIdentifier(1),
+    Messages: []iggcon.IggyMessage{msg},
+})`,
+  },
+  {
+    lang: "Node.js",
+    file: "producer.ts",
+    href: "/docs/sdk/node/intro",
+    code: `import { Client, Partitioning } from 'apache-iggy';
+
+const client = new Client({
+  transport: 'TCP',
+  options: { port: 8090, host: '127.0.0.1' },
+  credentials: {
+    username: 'iggy', password: 'iggy'
+  },
+});
+
+await client.stream.create({
+  name: 'orders'
+});
+await client.topic.create({
+  streamId: 'orders',
+  name: 'events',
+  partitionsCount: 3,
+});
+
+await client.message.send({
+  streamId: 'orders',
+  topicId: 'events',
+  partitioning: Partitioning.Balanced(),
+  messages: [
+    { payload: Buffer.from('order-123') }
+  ],
+});`,
+  },
+  {
+    lang: "C#",
+    file: "Producer.cs",
+    href: "/docs/sdk/csharp/intro",
+    code: `var client = IggyClientFactory.CreateClient(
+    new IggyClientConfigurator() {
+        BaseAddress = "127.0.0.1:8090",
+        Protocol = Protocol.Tcp,
+    }
+);
+await client.LoginAsync("iggy", "iggy");
+
+await client.CreateStreamAsync("orders");
+await client.CreateTopicAsync(
+    "orders", "events",
+    partitionsCount: 3
+);
+
+await client.SendMessagesAsync(
+    "orders", "events",
+    partitionId: 1,
+    messages: new[] {
+        new Message("order-123")
+    }
+);`,
+  },
+  {
+    lang: "C++ (WIP)",
+    file: "producer.cpp",
+    href: "/docs/sdk/cpp/intro",
+    code: `#include "lib.rs.h"
+
+// Connect and authenticate
+auto* client = iggy::ffi::new_connection(
+    "iggy://iggy:iggy@localhost:8090"
+);
+client->connect();
+client->login_user("iggy", "iggy");
+
+// Create stream and topic
+client->create_stream("orders");
+
+iggy::ffi::Identifier stream_id;
+stream_id.kind = "string";
+stream_id.length = 6;
+for (char c : std::string("orders"))
+    stream_id.value.push_back(
+        static_cast<uint8_t>(c));
+
+client->create_topic(
+    stream_id, "events", 3
+);
+
+// Cleanup
+iggy::ffi::delete_connection(client);`,
+  },
+];
+
+export function LandingCodeTabs() {
+  const [active, setActive] = useState(0);
+  const s = snippets[active];
+
+  return (
+    <div className="rounded-2xl border border-white/[0.08] bg-[#0c1220] overflow-hidden">
+      <div className="flex items-center border-b border-white/[0.06] overflow-x-auto">
+        {snippets.map((sn, i) => (
+          <button
+            key={sn.lang}
+            onClick={() => setActive(i)}
+            className={`px-4 py-2.5 text-xs font-medium whitespace-nowrap transition-colors ${
+              i === active
+                ? "text-[#ff9103] border-b-2 border-[#ff9103] bg-white/[0.03]"
+                : "text-[#636b75] hover:text-[#aaafb6]"
+            }`}
+          >
+            {sn.lang}
+          </button>
+        ))}
+      </div>
+      <div className="p-5">
+        <div className="flex items-center justify-between mb-3">
+          <div className="flex items-center gap-2">
+            <div className="w-3 h-3 rounded-full bg-[#ff5f57]" />
+            <div className="w-3 h-3 rounded-full bg-[#febc2e]" />
+            <div className="w-3 h-3 rounded-full bg-[#28c840]" />
+            <span className="ml-2 text-xs text-[#636b75] font-mono">{s.file}</span>
+          </div>
+          <a
+            href={s.href}
+            className="text-[10px] text-[#ff9103] no-underline hover:underline"
+          >
+            SDK docs →
+          </a>
+        </div>
+        <pre className="text-[13px] leading-relaxed font-mono overflow-x-auto m-0 whitespace-pre">
+          <code dangerouslySetInnerHTML={{ __html: highlight(s.code) }} />
+        </pre>
+      </div>
+    </div>
+  );
+}
diff --git a/src/mdx-components.tsx b/src/mdx-components.tsx
index e4aa3398..d321daee 100644
--- a/src/mdx-components.tsx
+++ b/src/mdx-components.tsx
@@ -19,12 +19,44 @@
 
 import defaultMdxComponents from "fumadocs-ui/mdx";
 import { Mermaid } from "@/components/mermaid";
+import {
+  MessageFlowDiagram,
+  ShardDiagram,
+  IoUringComparison,
+  SegmentVisualization,
+  MessageHeaderDiagram,
+  BenchmarkChart,
+  NamespacePacking,
+  StreamHierarchy,
+  AppendOnlyLogViz,
+  ConsumerGroupViz,
+  ConnectorPipeline,
+  ServerEcosystem,
+  WhyIggy,
+  QuickStartSnippet,
+  DocsHero,
+} from "@/components/architecture-diagrams";
 import type { MDXComponents } from "mdx/types";
 
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...defaultMdxComponents,
     Mermaid,
+    MessageFlowDiagram,
+    ShardDiagram,
+    IoUringComparison,
+    SegmentVisualization,
+    MessageHeaderDiagram,
+    BenchmarkChart,
+    NamespacePacking,
+    StreamHierarchy,
+    AppendOnlyLogViz,
+    ConsumerGroupViz,
+    ConnectorPipeline,
+    ServerEcosystem,
+    WhyIggy,
+    QuickStartSnippet,
+    DocsHero,
     ...components,
   };
 }