Update Makefile and README with diagrams

Makefile

@@ -1,16 +1,57 @@
-# Makefile for MemoryStore
-
-.PHONY: build clean test
-
-build:
-    @echo "Building MemoryStore..."
-    go build -o memory_store
-
-test:
-    @echo "Running tests..."
-    go test ./...
-
-clean:
-    @echo "Cleaning up..."
-    go clean
-    rm -f memory_store
+# Makefile for MemoryStore
+
+.PHONY: all build clean test bench lint fmt vet help
+
+# Default target
+all: clean fmt vet lint test build
+
+# Build the project
+build:
+	@echo "Building MemoryStore..."
+	go build -o memory_store
+
+# Run tests with race detection
+test:
+	@echo "Running tests..."
+	go test -race -cover ./...
+
+# Run benchmarks
+bench:
+	@echo "Running benchmarks..."
+	go test -bench=. ./...
+
+# Run linter
+lint:
+	@echo "Running linter..."
+	golangci-lint run ./...
+
+# Format code
+fmt:
+	@echo "Formatting code..."
+	go fmt ./...
+
+# Vetting code
+vet:
+	@echo "Vetting code..."
+	go vet ./...
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning up..."
+	go clean
+	rm -f memory_store
+
+# Show help
+help:
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Targets:"
+	@echo "  all       Run clean, fmt, vet, lint, test, and build"
+	@echo "  build     Build the project"
+	@echo "  test      Run tests with race detector"
+	@echo "  bench     Run benchmarks"
+	@echo "  lint      Run linter (golangci-lint)"
+	@echo "  fmt       Format code (go fmt)"
+	@echo "  vet       Vet code (go vet)"
+	@echo "  clean     Remove build artifacts"
+	@echo "  help      Show this help message"

README.md

@@ -238,6 +238,68 @@ defer func() {
 }()
 ```
 
+## Architecture
+
+Here's an overview of how MemoryStore is architected:
+
+```mermaid
+graph TD
+    subgraph Client Layer
+        User[User Application]
+    end
+
+    subgraph MemoryStore System
+        API[MemoryStore API]
+
+        subgraph "Storage Engine"
+            Shards[Sharded Storage Map]
+            Metrics[Metrics Collector]
+        end
+
+        subgraph "Background Services"
+            Cleaner[Cleanup Routine]
+        end
+
+        subgraph "Pub/Sub System"
+            PS_Interface[PubSub Interface]
+            PS_Mem[In-Memory Broker]
+            PS_GCP[Google Cloud PubSub]
+        end
+    end
+
+    User -->|Set/Get| API
+    User -->|Subscribe| API
+
+    API -->|Read/Write| Shards
+    API -->|Record| Metrics
+    API -->|Publish| PS_Interface
+
+    Cleaner -->|Periodically Scan| Shards
+    Cleaner -->|Remove Expired| Shards
+
+    PS_Interface -->|Default| PS_Mem
+    PS_Interface -->|Configured| PS_GCP
+```
+
+### PubSub Data Flow
+
+```mermaid
+sequenceDiagram
+    participant P as Publisher
+    participant MS as MemoryStore
+    participant S as Subscriber
+
+    S->>MS: Subscribe("topic-A")
+    activate MS
+    MS-->>S: Returns Channel
+    deactivate MS
+
+    P->>MS: Publish("topic-A", "payload")
+    activate MS
+    MS->>S: Sends "payload" to Channel
+    deactivate MS
+```
+
 ## Performance Considerations
 
 - Uses `github.com/goccy/go-json` for faster JSON operations
@@ -253,11 +315,20 @@ Use the provided Makefile:
 # Build the project
 make build
 
-# Run tests
+# Run tests (with race detection)
 make test
 
 # Run benchmarks
 make bench
+
+# Run linter
+make lint
+
+# Format code
+make fmt
+
+# Show all targets
+make help
 ```
 
 ## Contributing