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/wildfirechat/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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1w ago
• 2 active contributors
• Other licensed
• CI configured
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{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 wildfirechat/im-server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wildfirechat/im-server.

What it runs against: a local clone of wildfirechat/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 wildfirechat/im-server | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch wildfirechat exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wildfirechat/im-server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wildfirechat/im-server.git
#   cd 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 wildfirechat/im-server and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "broker/config/wildfirechat.conf" \\
  && ok "broker/config/wildfirechat.conf" \\
  || miss "missing critical file: broker/config/wildfirechat.conf"
test -f "broker/migrate/h2/V1__baseline.sql" \\
  && ok "broker/migrate/h2/V1__baseline.sql" \\
  || miss "missing critical file: broker/migrate/h2/V1__baseline.sql"
test -f "broker/pom.xml" \\
  && ok "broker/pom.xml" \\
  || miss "missing critical file: broker/pom.xml"
test -f "broker/migrate/mysql/V1__baseline.sql" \\
  && ok "broker/migrate/mysql/V1__baseline.sql" \\
  || miss "missing critical file: broker/migrate/mysql/V1__baseline.sql"
test -f ".travis.yml" \\
  && ok ".travis.yml" \\
  || miss "missing critical file: .travis.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
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/wildfirechat/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).

WildFireChat im-server is a production-grade instant messaging (IM) backend service that handles all core messaging operations using MQTT + Protocol Buffers. It processes user authentication, message routing, group management, voice/video signaling, and device synchronization with claimed support for 1M+ concurrent users and minimal resource footprint (128MB RAM minimum). Maven monorepo: broker/ directory contains the MQTT broker implementation and configuration (wildfirechat.conf, hazelcast.xml), broker/migrate/h2/ holds all database migrations (flyway pattern V1–V49), with core IM logic embedded in Java modules. The parent pom.xml coordinates versioning across moquette-broker, common utilities, and related services.

Platform engineers and DevOps teams deploying private instant messaging infrastructure; mobile app developers integrating a self-hosted IM backend; enterprises requiring on-premises messaging without third-party dependencies.

Production-ready. The codebase shows extensive schema evolution (49 versioned H2 migrations in broker/migrate/h2/), comprehensive feature set (secret chats, super groups, channel management, read receipts), and active ecosystem with 6+ companion services (app-server, robot_server, push_server). However, commit recency and test coverage data are not visible in the provided manifest.

Moderate risk: single repository structure with tight coupling between broker logic and database migrations; large codebase (2.3MB Java) may have maintenance burden; migration strategy (H2 flyway versioning) requires careful upgrades; dependency on Moquette MQTT broker and Hazelcast clustering adds operational complexity.

Unable to determine from static file manifest; no recent commit timestamps or GitHub Actions workflows visible. The presence of V49 migration (domain_table) suggests ongoing feature development, but active development status requires checking .github/workflows or recent commits.

git clone https://github.com/wildfirechat/im-server.git
cd im-server
mvn clean install -DskipTests
cd broker
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.config.location=config/wildfirechat.conf"

Daily commands:

mvn clean package
cd broker
java -Xmx512m -jar moquette-broker-1.4.6.jar --config config/wildfirechat.conf

OR start with Spring Boot: mvn spring-boot:run from broker/. Configure database and MQTT ports in config/wildfirechat.conf.

• broker/config/wildfirechat.conf — Core configuration file for IM server deployment; all developers must understand broker settings, database connection, MQTT parameters, and clustering configuration
• broker/migrate/h2/V1__baseline.sql — Baseline database schema; essential for understanding the data model, message storage structure, user sessions, groups, channels, and relationships
• broker/pom.xml — Maven parent project definition; defines dependencies (MQTT, Protobuf, database drivers) and build configuration for the entire IM server
• broker/migrate/mysql/V1__baseline.sql — MySQL baseline schema variant; critical for contributors deploying to MySQL instead of H2, ensures consistency across database backends
• .travis.yml — CI/CD pipeline configuration; shows how the project is built, tested, and validated on each commit
• README.md — Project overview and feature documentation; establishes scope, architecture philosophy (MQTT+Protobuf), and platform support across all major OS/platforms
• LICENSE — Primary software license; determines commercial use restrictions and open-source obligations for contributors and users

Add a New Database Table / Domain Entity

1. Create a new Flyway migration file: broker/migrate/h2/VNN__<description>.sql (copy latest version number, increment NN) (broker/migrate/h2/VNN__add_new_entity.sql)
2. Define the table schema in H2 dialect SQL; follow naming conventions (snake_case, include created_at, updated_at timestamps) (broker/migrate/h2/VNN__add_new_entity.sql)
3. Create the same migration for MySQL: broker/migrate/mysql/VNN__<description>.sql, using MySQL-compatible syntax (broker/migrate/mysql/VNN__add_new_entity.sql)
4. If this entity is frequently accessed, consider adding sharding logic in broker/migrate/h2/V3__create_sharding_table.sql by adding a sharding rule (broker/migrate/h2/V3__create_sharding_table.sql)

Add a New Configuration Option

1. Open broker/config/wildfirechat.conf and add your option in the appropriate section (mqtt, database, cluster, etc.) with inline documentation (broker/config/wildfirechat.conf)
2. If clustering is affected, update broker/config/hazelcast.xml to handle distributed state or caching (broker/config/hazelcast.xml)
3. Document the new option in README.md Features section, especially if it's user-facing (README.md)

Initialize New Feature Data (Bootstrap)

1. Create a new Flyway migration file: broker/migrate/h2/VNN__create_<feature>_bootstrap.sql (broker/migrate/h2/VNN__create_feature_bootstrap.sql)
2. Insert default records (e.g., system users, preset channels) using INSERT INTO statements (broker/migrate/h2/VNN__create_feature_bootstrap.sql)
3. Create the equivalent MySQL migration: broker/migrate/mysql/VNN__create_<feature>_bootstrap.sql (broker/migrate/mysql/VNN__create_feature_bootstrap.sql)
4. Reference this migration in README.md if it introduces a new subsystem (e.g., bots, admin roles) (README.md)

Update Build Dependencies

1. Open broker/pom.xml and add <dependency> block under <dependencies> section with groupId, artifactId, version (broker/pom.xml)
2. If the dependency impacts protocol handling, verify it's compatible with existing MQTT + Protobuf stack; document in comments (broker/pom.xml)
3. Run Maven build locally to validate no conflicts; ensure parent version (1.4.6) compatibility (broker/pom.xml)
4. Update .travis.yml if the new dependency requires additional environment setup or has native binaries (.travis.yml)

• MQTT + Protobuf — Minimizes network bandwidth and computational overhead; enables real-time message routing on low-memory devices (as low as 128MB); Protobuf provides compact binary serialization and backward compatibility
• Hazelcast — Distributed in-memory data grid for cluster coordination, session replication, and caching without external services; enables horizontal scaling and multi-node deployments
• Flyway Migrations — Version-controlled database schema evolution; supports both H2 (development) and MySQL (production); enables zero-downtime updates across multiple deployment environments
• H2 + MySQL Dual Support — H2 for embedded/development deployments (low-resource, self-contained); MySQL for large-scale production (distributed, high availability, proven ops history)
• Message Sharding (V3 migration) — Partitions large message tables by user_id to prevent query slowdowns and enable independent scaling; critical for million-user scale

• MQTT over WebSocket/HTTP REST

  • Why: Binary protocol reduces overhead and latency; persistent connections minimize connection teardown cost; better suited for mobile networks with high latency variance
  • Consequence: Requires stateful connection management; more complex client libraries; incompatible with simple REST clients

• Monolithic broker with embedded Hazelcast

  • Why: Reduces operational complexity; avoids external service dependencies; faster deployment
  • Consequence: Cluster state tied to broker lifecycle; memory footprint increases with cluster size; failure of one node requires re-syncing

• Dual H2 + MySQL schemas

  • Why: Single codebase supports both embedded and distributed deployments; easy local development
  • Consequence: Schema drift risk; must maintain two migration paths in parallel; slightly higher test burden

• Message sharding in application layer (not database)

  • Why: Database-agnostic; allows manual re-sharding without full table locks; flexible partition key selection
  • Consequence: Distributed join queries become complex; requires client-side aggregation logic; potential for uneven load distribution

• Not a managed SaaS platform—requires self-hosting on infrastructure (bare metal, K8s, VM)

Database initialization: must run Flyway migrations on fresh DB; no auto-create without explicit config. MQTT networking: requires MQTT_PORT (default 1883) and TLS setup (see hazelcast.xml for security). Clustering: Hazelcast multicast discovery may not work across subnets; requires explicit member configuration for cloud deployments. Schema compatibility: H2 migrations are version-locked; downgrading DB schema is not supported. Memory: Default heap (-Xmx512m) may exhaust under 100k+ concurrent users; tune via JVM args. No embedded docs: API documentation not visible in repo structure; refer to companion app-server for REST endpoint examples.

• MQTT (Message Queuing Telemetry Transport) — im-server uses MQTT as the core protocol for client-server messaging instead of HTTP/WebSocket; enables efficient pub-sub with minimal bandwidth on mobile networks.
• Protocol Buffers (Protobuf) — Message serialization format for im-server; more compact and faster than JSON, critical for IM performance at scale.
• Flyway Database Migrations — im-server uses versioned SQL migrations (V1–V49) for schema evolution; allows safe multi-version deployments and rollback safety.
• Hazelcast In-Memory Data Grid — Provides distributed caching and cluster coordination in hazelcast.xml; enables multi-node im-server deployments without external Redis/Memcached.
• Message-Oriented Middleware (MOM) — im-server acts as MOM, decoupling message producers (clients) from consumers via MQTT broker and persistent queues; enables offline delivery and read receipts.
• Sharding (Database Partitioning) — broker/migrate/h2/V3__create_sharding_table.sql indicates sharding support; allows scaling beyond single-node DB limits by partitioning user/message data.
• End-to-End Encryption (E2EE) with Secret Chats — V42__create_secret_chat_table.sql shows im-server supports encrypted channels; critical for compliance and privacy-conscious deployments.

• wildfirechat/app-server — Demo application server showing how to integrate with im-server for user authentication, IM account management, and REST API wrappers.
• wildfirechat/robot_server — Bot framework for automating message flows and third-party service integration; consumes im-server's messaging APIs.
• wildfirechat/push_server — Push notification relay; handles offline message delivery by queuing to FCM/APNs/vendor services when clients disconnect from im-server.
• wildfirechat/wf-janus — High-performance WebRTC media server for voice/video calls; im-server routes signaling to wf-janus for peer-to-peer and group calls.
• tencent/mars — WeChat's connection library used by im-server clients; provides resilient multiplexing for unreliable mobile networks (referenced in README as key advantage).

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 database migration validation and testing for multi-database support

The repo has 58+ migration files for H2 and MySQL (broker/migrate/h2/ and broker/migrate/mysql/) but no apparent test coverage. New contributors could create a test suite that validates migration consistency across both database engines, ensuring schema parity and catching drift early. This is critical for a production IM system that supports multiple databases.

• [ ] Create broker/src/test/java/migration/ directory for migration tests
• [ ] Add integration tests using Flyway's test utilities to verify all H2 migrations execute without error
• [ ] Add parallel tests for MySQL migrations to ensure schema equivalence between V1-V58 across both engines
• [ ] Document any discovered schema differences between H2 and MySQL in broker/migrate/README.md
• [ ] Add a GitHub Action workflow (.github/workflows/migration-tests.yml) to run these tests on PR

Create Docker Compose setup with health checks and initialization scripts

The repo lacks a docker-compose.yml for local development. Given the complex broker configuration (broker/config/wildfirechat.conf, hazelcast.xml) and multiple migration files, contributors could create a complete Docker Compose stack with health checks for the IM server, database initialization, and configuration validation. This would significantly lower the barrier for new contributors.

• [ ] Create docker-compose.yml in root with services for: broker (moquette), MySQL, H2 (optional), and optionally Redis for caching
• [ ] Create broker/docker/Dockerfile and broker/docker/entrypoint.sh that applies migrations automatically
• [ ] Add healthcheck scripts that validate broker connectivity via MQTT port and database connectivity
• [ ] Create docker-compose.override.yml.example showing common development customizations
• [ ] Add DOCKER_SETUP.md documentation with quick-start commands and troubleshooting

Add comprehensive API documentation and contract tests for broker endpoints

The README mentions 'API丰富' (rich APIs) but the repo structure shows no OpenAPI/Swagger specs or contract test files. For a production IM system, this is critical. Contributors could document and test the broker's HTTP/MQTT API contracts to prevent breaking changes and help integration partners.

• [ ] Create broker/docs/api/ directory for OpenAPI 3.0 specification files
• [ ] Document main IM server endpoints (user registration, authentication, message sending, group operations) in separate OpenAPI specs
• [ ] Create broker/src/test/java/api/contract/ for Spring Cloud Contract or Pact-based contract tests
• [ ] Add a GitHub Action workflow (.github/workflows/api-contract-tests.yml) that validates spec compliance on each PR
• [ ] Generate HTML documentation from OpenAPI specs and publish to docs/ or GitHub Pages on release

• Add integration test suite for V49 domain table (multi-domain federation); currently no test migrations visible in broker/migrate/. This is critical before users adopt federation.
• Create broker/config/wildfirechat-example.conf with all options documented (SMTP, file storage paths, clustering modes); deployment guides reference it but no annotated example exists.
• Extract Moquette MQTT interceptor logic into broker/src/main/java/moquette/interceptors/ with unit tests; currently tightly coupled, blocking extensibility for custom message preprocessing (encryption, DLP).

• High · Outdated Log4j Dependency with Known Vulnerabilities — pom.xml - log4j-core, log4j-api dependencies. The project uses log4j-core version 2.17.2 and log4j-api 2.17.2. While these versions address CVE-2021-44228 (Log4Shell), they are outdated. The current stable version is 2.22.1 (as referenced in log4j-slf4j2-impl), creating inconsistency and potential security gaps. Additionally, version mismatch between log4j-core/api (2.17.2) and log4j-slf4j2-impl (2.22.1) may lead to unexpected behavior. Fix: Update log4j-core and log4j-api to version 2.22.1 to match the log4j-slf4j2-impl version. Ensure all Log4j family dependencies are consistent.
• High · Incomplete Maven Dependency Declaration — pom.xml - mysql-connector dependency section. The MySQL connector dependency is incomplete - the line ends with '<!-- https://mvnrepository.com/artifact/mysql/mysql-connector-' without specifying the artifact ID, version, or closing tag. This indicates either truncated configuration or missing dependency management that could affect database connectivity security. Fix: Complete the MySQL connector dependency declaration with proper artifact ID and version (e.g., mysql-connector-java 8.0.33 or mysql-connector-java 8.1.x for Java 8+ compatibility). Use parameterized version management in parent POM.
• Medium · Potential SQL Injection via Database Migration Scripts — broker/migrate/h2/ and broker/migrate/mysql/ directories. The project contains 58+ SQL migration files (V1__baseline.sql through V58__conference_add_column.sql) across multiple database systems (H2, MySQL). Without visibility into the application code that executes these migrations, there's a risk of SQL injection if user input is not properly sanitized in code that generates or modifies SQL dynamically. Database migrations should be version-controlled and validated. Fix: Ensure all SQL migrations use parameterized queries and prepared statements. Implement code review processes for migration scripts. Use Flyway or Liquibase with strict validation. Never concatenate user input into SQL queries.
• Medium · Missing MQTT Security Configuration Details — broker/config/wildfirechat.conf, broker/config/hazelcast.xml. The project is an MQTT-based IM server (as indicated in README mentioning MQTT+Protobuf), but the provided hazelcast.xml and wildfirechat.conf configuration files are not visible in their content. MQTT servers commonly have insecure defaults (unencrypted connections, default credentials, open ports). Fix: Verify MQTT broker configuration enforces: TLS/SSL for all connections, strong authentication, disabled anonymous access, restricted listening ports (1883 TLS only, not plain), message validation, and rate limiting. Review hazelcast.xml for proper authentication and network binding.
• Medium · Travis CI Configuration Visible in Repository — .travis.yml. The .travis.yml file is present in the repository root. Travis CI configurations can expose secrets, API keys, or build tokens if not properly configured, especially in public repositories. Fix: Ensure .travis.yml does not contain any hardcoded secrets, API keys, or credentials. Use Travis CI environment variables for sensitive data. Consider using GitHub Actions with OIDC tokens instead of Travis CI. Regularly audit CI/CD configuration for secret leakage.
• Medium · Disruptor Library Potentially Outdated — pom.xml - disruptor dependency. The project uses disruptor version 3.4.1 (released in 2015). While Disruptor is a high-performance library with fewer security-critical updates, using very old versions may miss performance improvements and potential bug fixes. Fix: Update disruptor to the latest stable version (4.0.1 or higher). Test compatibility with the application to ensure the upgrade doesn't break existing functionality.
• Low · Missing Security Headers and Input Validation Documentation — undefined. While the file structure shows a comprehensive IM system with API exposure (implied by 'API丰富' in README), there's no visible documentation of security headers, CORS policies, or input validation strategies in the provided file listing. 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.