If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/openimsdk/open-im-server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 7w ago
• 12 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live openimsdk/open-im-server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/openimsdk/open-im-server.

What it runs against: a local clone of openimsdk/open-im-server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in openimsdk/open-im-server | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 80 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of openimsdk/open-im-server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/openimsdk/open-im-server.git
#   cd open-im-server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of openimsdk/open-im-server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "openimsdk/open-im-server(\\.git)?\\b" \\
  && ok "origin remote is openimsdk/open-im-server" \\
  || miss "origin remote is not openimsdk/open-im-server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/main.go" \\
  && ok "cmd/main.go" \\
  || miss "missing critical file: cmd/main.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"
test -f "build/images" \\
  && ok "build/images" \\
  || miss "missing critical file: build/images"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 80 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~50d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/openimsdk/open-im-server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Open-IM-Server is a production-grade, open-source instant messaging backend written in Go that provides a scalable foundation for chat applications. It implements real-time message delivery, group management, user presence, and push notifications through gRPC and WebSocket protocols, with multi-tenant support and cloud-native deployment via Docker/Kubernetes. Monorepo organized by service boundaries: likely cmd/ for service entrypoints, internal/ for business logic (message handling, user management), pkg/ for reusable utilities, and docs/ for deployment guides. Infrastructure-as-code via Dockerfile and .env templates; protocol definitions imported from github.com/openimsdk/protocol (v0.0.73-alpha.19).

Backend engineers and DevOps teams building self-hosted or SaaS chat platforms who need a feature-complete, Apache-2.0 licensed IM infrastructure without vendor lock-in. Also relevant for organizations requiring on-premise message storage and compliance control (healthcare, financial services).

Production-ready and actively maintained: 1.5M+ Go lines of code, strong GitHub activity (reflected in 500+ Slack community), comprehensive CI/CD workflows (.github/workflows/ shows CodeQL, Docker builds, Go testing), and semantic versioning (v3 in go.mod). Latest changes tracked in CHANGELOG/ with 3.8+ versions indicate stable APIs.

Moderate dependency risk: monolithic codebase with 60+ external dependencies (Firebase, MongoDB, gRPC, Kafka via IBM Sarama, Redis, etcd) means supply-chain complexity. No visible single-maintainer risk due to openimsdk organization structure, but breaking changes between major versions (v3) require careful migration planning. Contributions are gated by CLA (cla-assistant workflow), which slows onboarding.

Active development targeting Kubernetes-native deployments (k8s imports visible in go.mod) and recent Go 1.25 support. Workflows show ongoing work on Docker multi-registry publishing, automated changelog generation, and issue triage automation. Version 3.x track indicates refactoring for improved scalability.

Clone and set up with: git clone https://github.com/openimsdk/open-im-server.git && cd open-im-server && go mod download && docker-compose up (inferred from Dockerfile presence and standard Go project layout). Check .env template for required configuration (database, Redis, Kafka endpoints).

Daily commands: Likely docker-compose up for full stack or make run (inferred from openimsdk/gomake dependency). Individual services probably invoked via go run ./cmd/[service-name] with env vars from .env. Kubernetes deployment via k8s client libraries (k8s.io/client-go, k8s.io/api).

• cmd/main.go — Primary entry point for the Open-IM server application; orchestrates service initialization and startup.
• go.mod — Dependency management manifest; defines all external libraries including gRPC, MongoDB, Gin, and protocol buffers.
• .golangci.yml — Linter configuration enforcing code quality standards across the entire codebase; must be understood for local development.
• build/images — Dockerfile definitions for each microservice (API, RPC services, message gateway); critical for understanding deployment architecture.
• Dockerfile — Primary containerization definition; shows how the application is packaged for production deployment.
• bootstrap.sh — Shell script for environment setup and initialization; essential for developers to bootstrap local development environments.
• README.md — Project overview, architecture description, and contribution guidelines; foundational documentation for all contributors.

Add a new RPC microservice

1. Create new service directory structure under cmd/openim-rpc-<service-name>/ (cmd/openim-api/main.go)
2. Define protobuf messages and services in protocol package (dependency: github.com/openimsdk/protocol) (go.mod)
3. Implement service handlers following existing RPC service patterns (cmd/openim-rpc-user)
4. Create Dockerfile for service containerization (build/images/openim-rpc-user/Dockerfile)
5. Add service entry point in cmd/openim-rpc-<service>/main.go (cmd/main.go)
6. Update bootstrap.sh to include new service initialization (bootstrap.sh)

Add a new HTTP API endpoint

1. Define new route handler in API service following Gin framework patterns (cmd/openim-api/main.go)
2. Implement request validation using go-playground/validator (go.mod)
3. Call appropriate RPC service backend (user, message, group, etc.) (cmd/openim-api/main.go)
4. Add middleware for authentication using golang-jwt (go.mod)
5. Register route in API service router configuration (cmd/openim-api/main.go)

Deploy a new version

1. Update version in relevant configuration files and rebuild binaries (build/goreleaser.yaml)
2. Push changes to main branch; GitHub Actions auto-triggers docker-build-and-release-services-images.yml (.github/workflows/docker-build-and-release-services-images.yml)
3. Images are built for each service using build/images/<service>/Dockerfile (build/images)
4. Pull updated Docker images in production environment using docker-compose or Kubernetes manifests (Dockerfile)
5. Verify deployment using health checks and monitoring dashboards (cmd/openim-api/main.go)

Add a new data model and MongoDB schema

1. Define protobuf message structure in protocol package (go.mod)
2. Implement repository/DAO layer in appropriate RPC service (cmd/openim-rpc-user)
3. Use go.mongodb.org/mongo-driver for database operations (go.mod)
4. Implement caching layer using rockscache for frequently accessed data (go.mod)
5. Expose model via RPC service endpoint in corresponding RPC service (cmd/openim-api/main.go)

• Go 1.25.0 + gRPC — High-performance, low-latency microservice communication with built-in concurrency and efficient serialization via Protocol Buffers
• MongoDB (go.mongodb.org/mongo-driver) — Flexible schema for message and user data; document-oriented storage aligns with chat message and user profile structures
• Redis (rockscache) — In-memory caching layer for session management, conversation state, and reducing database load on frequently accessed data
• Gin Framework + gorilla/websocket — Lightweight HTTP routing for REST APIs combined with WebSocket for persistent real-time bidirectional messaging
• Protocol Buffers (openimsdk/protocol) — Language-agnostic, compact binary serialization for cross-service RPC communication and API contract definition
• Docker + Docker Compose — Containerization enables service isolation, easy deployment scaling, and reproducible environments across dev/staging/production
• GitHub Actions — Automated CI/CD for build validation, linting, testing, and Docker image publication on every commit

• Microservices architecture (separate RPC services for user, message, friend, group, conversation, auth, third-party, push)

  • Why: Allows independent scaling and deployment of high-load services (message, gateway) vs. low-frequency services (user, friend)
  • Consequence: Increased operational complexity; requires distributed tracing and cross-service debugging; network latency between services

• Synchronous RPC (gRPC) for inter-service communication

  • Why: Simpler transactional consistency for operations like message delivery confirmation and user state updates
  • Consequence: Potential bottleneck if downstream service is slow; cascading failures if one RPC service becomes unavailable

• MongoDB for primary data store

  • Why: Flexibility for message schema evolution and horizontal sharding for large-scale deployments
  • Consequence: Lacks ACID guarantees across documents; eventual

Multiple required external services must be running before start: MongoDB, Redis, Kafka, and etcd (visible in go.mod imports for etcd/client/v3). Firebase credentials required for push notifications (firebase.google.com/go/v4). CLA signature mandatory for any PR (cla-assistant workflow will block merges). Docker images published to multiple registries per .github/workflows/docker-build-and-release-services-images.yml; ensure correct registry auth in your environment.

• gRPC + Protocol Buffers — Core transport for inter-service communication and client-server messaging in this IM platform; enables polyglot SDKs (Web, Android, iOS) via code generation from .proto contracts
• WebSocket connection pooling — Real-time message delivery to clients requires persistent bidirectional channels; gorilla/websocket v1.5.1 and related pooling logic are critical for concurrent user scalability
• JWT (JSON Web Tokens) for stateless auth — golang-jwt/jwt v4.5.1 enables serverless, horizontally-scalable authentication without sticky sessions; typical IM use case avoiding session store bottlenecks
• Event-driven architecture via Kafka — IBM/sarama integration for async message delivery, presence updates, and notifications decouples services and improves fault tolerance in distributed IM systems
• Redis caching with rockscache — dtm-labs/rockscache layered over go-redis/v9 provides distributed caching for user presence, group metadata, and message offsets; critical for sub-100ms latency guarantees
• MongoDB document storage — Flexible schema for messages, users, and groups (go.mongodb.org/mongo-driver v1.14.0); allows schema evolution without migrations typical of relational DBs in fast-moving IM features
• Prometheus metrics + Grafana observability — grpc-ecosystem/go-grpc-prometheus integration exposes request latency, error rates, and throughput; production IM systems require real-time alerting on service health

• openimsdk/open-im-sdk-web — Official Web SDK client that connects to open-im-server via gRPC-Web; essential for frontend integration and end-to-end testing
• openimsdk/protocol — Shared Protocol Buffer definitions (v0.0.73-alpha.19 in go.mod); all gRPC messages and service contracts defined here; changes here trigger server rebuilds
• openimsdk/open-im-sdk-android — Official Android SDK consuming the same gRPC services; client reference implementation for mobile platforms
• openimsdk/open-im-sdk-ios — Official iOS SDK; complements Android client for cross-platform IM application support
• openimsdk/tools — Shared utility library (v0.0.50-alpha.113 in go.mod) providing logging, config parsing, and common middleware used across server services

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for gRPC service endpoints with go-grpc-prometheus metrics validation

The repo uses grpc-ecosystem/go-grpc-prometheus for metrics collection but lacks visible integration tests validating that metrics are properly emitted. Given the presence of multiple gRPC services (inferred from protocol dependency v0.0.73-alpha.19) and Prometheus client_golang v1.18.0, contributors could add tests that verify counter/histogram metrics are correctly recorded during gRPC calls. This ensures observability infrastructure works as designed and catches regressions.

• [ ] Locate gRPC service definitions in pkg//service or internal//service directories
• [ ] Create tests/integration/grpc_metrics_test.go with test cases for each service method
• [ ] Validate prometheus metrics using promauto or prometheus.DefaultRegisterer
• [ ] Run tests against both unary and streaming RPC methods
• [ ] Document metric expectations in a new tests/METRICS.md file

Add GitHub Actions workflow for dependency vulnerability scanning with go-releaser config integration

The repo has build/goreleaser.yaml for releases but lacks a dedicated workflow for continuous vulnerability scanning of Go dependencies. With 40+ direct dependencies including Firebase, MongoDB, Kafka (sarama), and etcd, contributors should add a GitHub Actions workflow using tools like nancy, trivy, or go list -json -m all | nancy sleuth to detect CVEs early. This should integrate with existing workflows (.github/workflows/) and block merges on critical issues.

• [ ] Create .github/workflows/dependency-security-scan.yml workflow file
• [ ] Configure nancy or trivy to scan go.mod against OSV/NVD databases
• [ ] Set workflow to run on PR opens, pushes to main, and daily schedule
• [ ] Add failure condition for CRITICAL/HIGH severity findings
• [ ] Document results in SECURITY.md and link from CONTRIBUTING.md

Add comprehensive test suite for Redis and MongoDB adapter layers with mock implementations

The repo uses both redis/go-redis/v9 and go-redis/redismock/v9, plus go.mongodb.org/mongo-driver, but test coverage for data layer adapters is unclear. Contributors should create dedicated test files (internal/repo//redis_test.go, internal/repo//mongo_test.go) with redismock and mtest patterns. This improves reliability of cache and persistence layers, validates failover behavior, and catches concurrency bugs common in distributed systems.

• [ ] Identify all Redis client instantiation points in internal/repo and pkg/common
• [ ] Create internal/repo/cache/redis_adapter_test.go using redismock/v9.ClientMock
• [ ] Create internal/repo/persistence/mongo_adapter_test.go using mtest.New()
• [ ] Add tests for connection failures, timeouts, and concurrent access patterns
• [ ] Update codecov.yml thresholds in .github/.codecov.yml to enforce coverage for adapter code

• Add missing test files for internal/msggateway or internal/user packages (test coverage gaps visible in sparse *_test.go presence relative to LOC count); start with unit tests for error conditions in a single handler function.
• Document gRPC service interfaces in docs/ (protocol definitions in github.com/openimsdk/protocol are external; create docs/GRPC_API.md with examples of message send, group create, and presence subscription flows).
• Add health check endpoints to services (k8s imports suggest Kubernetes readiness probe support is desired but Gin handlers for /health, /ready, /live routes appear absent from standard HTTP layer)

• High · Deprecated Go Redis Client in Use — go.mod - dependencies section. The codebase includes 'github.com/go-redis/redis v6.15.9+incompatible' which is an old, deprecated version of the Redis client. This version is no longer maintained and may contain unpatched security vulnerabilities. The codebase also includes 'github.com/redis/go-redis/v9 v9.4.0', indicating a migration is partially complete but the old version remains as a dependency. Fix: Remove the deprecated 'github.com/go-redis/redis v6.15.9+incompatible' dependency. Ensure all imports are migrated to 'github.com/redis/go-redis/v9' and run 'go mod tidy' to clean up unused dependencies.
• High · Potential Hardcoded Credentials in Docker Compose — .env file and docker-compose.yml. The docker-compose.yml file references environment variables for MongoDB credentials (MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD, MONGO_OPENIM_USERNAME, MONGO_OPENIM_PASSWORD), but the .env file is present in the repository. If the .env file contains actual credentials, it creates a risk of credential exposure in version control history. Fix: Ensure .env is listed in .gitignore (verify it is properly ignored). Never commit actual credentials to the repository. Use environment variable files only for development with placeholder/dummy values, and document expected variables. For production, use secure secret management (e.g., Docker Secrets, Kubernetes Secrets, HashiCorp Vault).
• High · Deprecated Go Version in Dockerfile — Dockerfile (FROM golang:1.22-alpine). The Dockerfile uses Go 1.22-alpine as the base image, but the go.mod file specifies 'go 1.25.0'. This version mismatch could lead to compilation inconsistencies, missed security patches, and behavioral differences between development and production builds. Fix: Update the Dockerfile to use 'FROM golang:1.25-alpine' to match the go.mod requirement. Ensure all build and runtime stages use consistent Go versions.
• Medium · Incomplete Dockerfile - Missing Binary Copy — Dockerfile - final stage. The Dockerfile's final stage does not include a COPY instruction to transfer the compiled binaries from the builder stage. The comment indicates this was intended ('Copy the compiled binaries and mage from the builder image to the final image') but the actual commands are missing, which would result in an empty or non-functional container. Fix: Add proper COPY instructions: 'COPY --from=builder /openim-server/bin/* /openim-server/bin/' and an ENTRYPOINT or CMD to execute the application. Ensure all necessary binaries and runtime dependencies are included.
• Medium · Missing Security Headers in Web Framework Configuration — API server configuration (files not fully provided). The codebase uses Gin web framework (github.com/gin-gonic/gin v1.9.1) for API endpoints, but no evidence of security middleware is visible in the provided file structure (e.g., missing CORS, CSP, X-Frame-Options headers configuration). Fix: Implement security headers middleware in Gin: CORS policy, Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security (HSTS), and X-XSS-Protection headers. Use established middleware like 'github.com/gin-contrib/cors'.
• Medium · Potential SQL Injection via MongoDB Operations — Database layer (specific files not fully visible). The codebase uses go.mongodb.org/mongo-driver v1.14.0. While MongoDB driver itself is safe from SQL injection, improper usage patterns (e.g., string concatenation in filter construction) could introduce vulnerabilities. No evidence of parameterized query enforcement is visible. Fix: Ensure all MongoDB queries use the driver's query construction methods (bson.M, bson.D) rather than string concatenation. Implement input validation and use prepared statements/filters. Conduct code review of all database access patterns.
• Medium · gRPC Service Exposed Without TLS Configuration Verification — undefined. The codebase implements multiple gRPC services (openim-rpc-auth, openim-rpc-conversation, etc Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.