diff --git a/README.md b/README.md
new file mode 100644
index 0000000..587bf7d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# vstamp
+
+Viewstamped Replication implementation in Rust.
+
+**Repository:** https://github.com/levchik/vstamp
+
+## Overview
+
+vstamp is a Rust library implementing the **Viewstamped Replication (VR)** consensus protocol, based on the paper ["Viewstamped Replication Revisited"](https://dspace.mit.edu/handle/1721.1/72181) by Barbara Liskov and James Cowling.
+
+Viewstamped Replication is a distributed consensus algorithm that provides fault tolerance for state machine replication, ensuring that multiple replicas maintain consistent state even in the presence of failures.
+
+## Features
+
+- **Fault Tolerant**: Tolerates up to f failures with 2f+1 replicas
+- **Leader-based**: Primary replica orders client requests
+- **Quorum-based**: Uses quorum intersection for consistency
+- **Testable**: Network simulator with failure injection for testing
+
+## Building
+
+```bash
+cargo build
+```
+
+## Running Tests
+
+```bash
+cargo test
+```
+
+## Architecture
+
+The library is structured around several core components:
+
+- **`Replica`**: Main replica implementation maintaining state (view number, operation log, client table)
+- **`ReplicaCore`**: Core logic handling VR protocol messages (Prepare, PrepareOk, Commit)
+- **`Client`**: Trait for client implementations
+- **`Network`**: Trait abstraction for network communication
+- **`App`**: Trait for application-specific request/response processing
+
+## Usage
+
+```rust
+use vstamp::{App, AppRequest, AppResponse, Config, Replica};
+
+// Define your application request/response types
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+enum MyRequest {
+    Get { key: String },
+    Set { key: String, value: String },
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+struct MyResponse(Option<String>);
+
+impl AppRequest for MyRequest {}
+impl AppResponse for MyResponse {}
+
+// Implement your application logic
+struct MyApp { /* ... */ }
+
+impl App<MyRequest, MyResponse> for MyApp {
+    fn new() -> Self { /* ... */ }
+    fn process_request(&mut self, req: MyRequest) -> MyResponse { /* ... */ }
+}
+
+// Create a 3-replica cluster (tolerates 1 failure)
+let config = Config::new(3);
+// ... set up network and replicas
+```
+
+## Documentation
+
+- [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md) - Feature implementation plan
+- [TEST_AUDIT.md](./TEST_AUDIT.md) - Test coverage analysis
+- [QWEN.md](./QWEN.md) - Development guide
+
+## License
+
+MIT