diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f748448
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,35 @@
+# kmsvc Architecture Clarifications
+
+## Inter-Pod Message Brokering (Parallel Processing)
+
+**kmsvc is a distributed, inter-pod SQS-compatible message queue service.** Multiple pods run in parallel sharing the same Kafka cluster and Redis coordination layer.
+
+### Message Flow
+```
+Client Service Pod 1 ----\
+Client Service Pod 2 ------ gRPC/REST → kmsvc Service (N replicas, stateless)
+Client Service Pod N ----/                    ↓
+                                           Kafka (3 brokers, KRaft)
+                                              ↓
+                                          Redis (state coordination)
+```
+
+### Key Facts
+1. **Kafka is the message broker** (durable, distributed) — not in-memory, not per-pod
+2. **Redis coordinates** in-flight state, dedup, FIFO gating via atomic Lua ops—no leader election
+3. **Service replicas are stateless** — any replica can handle send/receive/delete
+4. **Consumer groups** (Kafka native) + Redis low-watermark strategy = at-least-once delivery
+5. **External services** can:
+   - Call kmsvc gRPC/REST API (REST via ingress-nginx)
+   - Produce/consume Kafka topics directly (same cluster)
+
+### Design References
+- `design.md §1`: Architecture diagram
+- `design.md §2`: API surface (CRD for lifecycle, gRPC/REST for messages)
+- `design.md §3`: Offset-commit + FIFO gating (inter-pod coordination)
+- `design.md §9`: Multi-replica scaling (no leader needed)
+
+### Operational
+- Horizontal scaling: add more `kmsvc` service replicas—Kafka rebalances automatically
+- HA: Redis Sentinel/Cluster recommended for production (design.md §9) — currently standalone
+- Monitoring: Kafka consumer-group lag, Redis pending/inflight keys, visibility timeouts
diff --git a/go.mod b/go.mod
index 3551727..5d7da4e 100644
--- a/go.mod
+++ b/go.mod
@@ -3,7 +3,7 @@ module github.com/rockliang/kafka-management-service
 go 1.26.0
 
 require (
-	forgejo.riotpiao.homelab.com/rock/kmsvc-proto v1.1.0
+	forgejo.riotpiao.homelab.com/homelab/kmsvc-proto v1.1.0
 	github.com/alicebob/miniredis/v2 v2.38.0
 	github.com/google/uuid v1.6.0
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0
@@ -14,6 +14,7 @@ require (
 	github.com/twmb/franz-go/pkg/kfake v0.0.0-20260615024848-f17c00130060
 	google.golang.org/grpc v1.81.1
 	google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af
+	k8s.io/api v0.36.2
 	k8s.io/apimachinery v0.36.2
 	k8s.io/client-go v0.36.2
 	sigs.k8s.io/controller-runtime v0.24.1
@@ -77,7 +78,6 @@ require (
 	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/api v0.36.2 // indirect
 	k8s.io/apiextensions-apiserver v0.36.0 // indirect
 	k8s.io/klog/v2 v2.140.0 // indirect
 	k8s.io/kube-openapi v0.0.0-20260317180543-43fb72c5454a // indirect