Build production-grade admin & AI-native backends in minutes, not months.
Spring Boot 4 · JDK 25 · MyBatis-Flex · Sa-Token · Nacos · MCP · Spring Cloud · Vue 3 · Element Plus · OpenTelemetry · Resilience4j
English · 简体中文
Most enterprise backends are either too heavy (slow to start, hard to extend) or too light (no auth, no audit, no observability). xarch sits in the sweet spot: a modular Spring Boot starter platform that gives you production-grade defaults without locking you in.
- 🧩 8 pluggable starters — bring only what you need (core, db, web, cache, tracing, resilience, storage, MCP)
- 🤖 AI-First — 4 native MCP servers (database, knowledge/RAG, filesystem, vector DB) plus a Spring AI integration path
- 🛡️ Production security — Sa-Token + JWT, BCrypt, XSS filter, rate limit, CSRF, audit log baked in
- 📊 Observability by default — OpenTelemetry tracing, Micrometer metrics, Prometheus + Grafana + Loki profiles
- 🧱 Spring Cloud ready — built-in Nacos discovery, Spring Cloud Gateway with per-route rate limit + circuit breaker
- 🚀 Deployment everywhere — docker-compose for dev, Kustomize for K8s base+overlays, full Helm chart with 6 sub-charts
- 🧪 Quality gates — JUnit 5, Mockito, AssertJ, Testcontainers, Playwright E2E, GitHub Actions CI
- 🌐 i18n — Vue-i18n with zh-CN + en-US, Element Plus localized components
- 📚 Real sample apps — full CMS / OA / CRM examples to copy patterns from
- 🧰 AI Agent platform — built-in SSH terminal, command audit + approval workflow, risk scoring (low/medium/high)
⭐ If xarch helps your team, please star the repo — it tells us what to prioritize next.
git clone https://github.com/processcrash/xarch.git
cd xarch
docker compose up -d
# Wait ~30s, then:
open http://localhost:8080 # Admin UI (admin / 123456)
open http://localhost:8848/nacos # Nacos (nacos / nacos)# 1. Start infrastructure
docker compose up -d postgres redis nacos
# 2. Backend
cd backend
./gradlew :xarch-example:bootRun # API on :8080
# 3. Frontend
cd ../vue3-admin
npm install && npm run dev # UI on :5173helm repo add xarch https://processcrash.github.io/xarch
helm install xarch xarch/xarch \
--namespace xarch --create-namespace \
--set global.imageTag=1.0.0That's it. The admin UI is up, with 18 prebuilt modules (users, roles, menus, depts, dicts, configs, files, messages, server monitor, cache monitor, jobs, online users, OAuth clients, audit, RAG, etc.) ready to use.
┌──────────────────────┐
│ Browser / Mobile │
└──────────┬───────────┘
│ HTTPS
┌──────────▼───────────┐
│ Spring Cloud │ Gateway
│ Gateway │ ─ rate limit
│ (port 9000) │ ─ circuit breaker
└──────────┬───────────┘
│
┌──────────┬───────────────┼───────────────┬──────────┐
▼ ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ service│ │service │ │service │ │service │ │service │
│ -auth │ │-system │ │ -file │ │ -ai │ │-message│
│ :9001 │ │ :9002 │ │ :9003 │ │ :9005 │ │ :9006 │
└───┬────┘ └────┬───┘ └────┬───┘ └────┬───┘ └────┬───┘
│ │ │ │ │
└───────────┴─────────────┴──────────────┴──────────┘
│ (Feign)
┌──────────▼───────────┐
│ Nacos 3.2 │ Discovery + Config
│ + Config Center │
└──────────┬───────────┘
│
┌───────────┬───────────────┼───────────────┬────────────┐
▼ ▼ ▼ ▼ ▼
PostgreSQL Redis Spring AI MCP Servers Observability
MySQL Redisson (LLM bridge) (4 servers) (Prom+Grafana)
Key design decisions (full rationale):
- MyBatis-Flex over MyBatis-Plus — 30% smaller footprint, no reflection, better Kotlin interop
- Sa-Token over Spring Security — 1/10 the config, native JWT, multi-tenant built in
- JDK 25 features — records, sealed types, virtual threads (Project Loom) for I/O
- In-process vector store in
xarch-mcp-vector— swap for Qdrant/Milvus with one config change - MCP as integration boundary — AI tools are first-class, not bolted on
The xarch monorepo also ships a Go-based AI Agent platform built on Google's official adk-go framework. While xarch's main backend is Java/Spring Boot, the Go companion targets teams that want a lightweight, statically-linked, single-binary AI agent runtime for greenfield agentic products or to embed as a library.
# Build the CLI + HTTP server binaries
cd go-ai-agent-base
make build
# Try the local REPL
./bin/agent chat --config configs/agent.example.yaml
# Or run the HTTP server (default :8080)
./bin/server --config configs/agent.example.yaml
curl -X POST http://localhost:8080/api/v1/agents/assistant/sessions \
-H 'Content-Type: application/json' \
-d '{"user_id":"alice"}'Highlights
- Built on
google/adk-go— same Agent/Tool/Session/Memory model, full Google lineage - 4 LLM providers out of the box — Gemini, OpenAI, Anthropic, Ollama — all behind one
agent.LLMinterface - Pluggable storage — in-memory (default), Redis, Postgres for sessions and long-term memory
- Tool framework — built-in time/calculator/HTTP tools + MCP bridge to
java-mcp-servers/ - REST + SSE —
/api/v1/agents/{name}/sessions/{sid}/streamfor real-time responses - CLI REPL for local development (
agent chat) with/help,/clear,/exit - Enterprise defaults — JWT auth (HS256/RS256), structured logging (Zap), OTel tracing, Prometheus metrics
- Public Go SDK —
pkg/sdkfor embedding the agent runtime from other Go services - Distroless Docker + Helm-friendly K8s manifests + HPA
Architecture at a glance
┌──────────────────────┐
│ HTTP / CLI / SDK │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ Runtime │
│ (orchestration, │
│ memory recall, │
│ tool loop) │
└──────────┬───────────┘
│
┌─────────┬──────────┼──────────┬─────────┐
▼ ▼ ▼ ▼ ▼
Gemini OpenAI Anthropic Ollama Tools
(HTTP/MCP/local)
See go-ai-agent-base/README.md, docs/ARCHITECTURE.md, and docs/QUICKSTART.md for details.
| Starter | What it gives you |
|---|---|
| xarch-core | ApiResult, PageResult, exceptions, ID generator, validators |
| xarch-db | MyBatis-Flex, multi-DB, audit fields, soft delete, multi-tenant interceptor |
| xarch-web | Sa-Token, XSS filter, rate limit, CORS, Knife4j, global exception handler |
| xarch-cache | Redis/Redisson auto-config, distributed locks, rate limit storage |
| xarch-tracing | OpenTelemetry SDK, W3C traceparent, MDC injection, OTLP/Zipkin exporters |
| xarch-resilience | Resilience4j annotations: @RateLimit, @CircuitBreaker, @Retry, @Bulkhead |
| xarch-storage | Unified FileStorageService for local / MinIO / Aliyun OSS / AWS S3 |
| xarch-mcp-vector | In-process vector store + KNN search + 10 MCP tools |
| Server | Language | Tools |
|---|---|---|
| database-mcp | Java + Node + Python | query, schema inspect, DDL, EXPLAIN |
| knowledge-mcp | Java + Node + Python | RAG index, semantic search, document CRUD |
| filesystem-mcp | Java + Node + Python | safe file ops, path-traversal protection |
| vector-mcp | Java + Node + Python | collection CRUD, KNN search, metadata filter |
All three languages produce semantically identical APIs — pick whichever your team prefers. The Python and Node versions are great for hooking up to Claude Desktop, Cursor, or any MCP client.
- cms — Content management (articles, categories, tags, comments)
- oa — Office automation (leave requests, expense reports, approval workflow)
- crm — Customer relationship (leads, opportunities, sales pipeline analytics)
Each ships with entities, services, controllers, DDL, OpenAPI annotations, and unit tests — copy-paste the patterns into your own domain.
Reference decomposition of the monolith into 7 Spring Cloud services:
| Service | Port | Responsibility |
|---|---|---|
| service-auth | 9001 | Login, JWT, user mgmt |
| service-system | 9002 | RBAC, menus, depts, dicts, configs |
| service-file | 9003 | Upload/download, storage adapters |
| service-monitor | 9004 | Server metrics, cache stats, jobs |
| service-ai | 9005 | AI chat, RAG, MCP tool execution |
| service-message | 9006 | In-app messages, OAuth clients |
| common | — | Shared DTOs, constants, Feign fallbacks |
Includes per-service Dockerfile (multi-stage, non-root, healthcheck) and full Helm chart.
- 27 views, 24 API modules, full role-based menu
- i18n (zh-CN default, en-US, Element Plus localized)
- Playwright E2E suite (60+ test cases)
- TypeScript strict, ESLint, Prettier
- Pinia stores, route guards, dynamic permission loading
Backend — Java 25 · Spring Boot 4.0 · Spring Cloud 2025 · MyBatis-Flex 1.9 · MySQL 8 / PostgreSQL 16 / MongoDB · Redis 7 / Redisson · Sa-Token · Resilience4j 2.2 · OpenTelemetry 1.42 · Spring AI 1.0 · Knife4j 5
AI Agent — Go 1.23+ · google/adk-go · Gin · Cobra · Viper · Zap · OpenTelemetry SDK · Prometheus client · golang-jwt · pgx · go-redis · testcontainers-go
MCP — @modelcontextprotocol/sdk (Node) · mcp[cli] (Python) · raw JSON-RPC (Java)
Frontend — Vue 3.5 · Vite 6 · TypeScript 5 · Element Plus 2.8 · Pinia 2 · Axios · Vue Router 4 · Vue I18n 9
DevOps — Gradle 8 + Kotlin DSL · Docker multi-stage · Helm 3.16 · Kustomize · GitHub Actions (CI, security, release) · Prometheus + Grafana + Loki · Trivy + CodeQL + Gitleaks
| Doc | What it covers |
|---|---|
| 📘 docs/ARCHITECTURE.md | Design decisions, layer breakdown, data flow, performance |
| 📗 docs/MCP_GUIDE.md | MCP protocol, all 4 servers, adding a new tool |
| 📕 docs/DEPLOYMENT.md | Dev → staging → prod, K8s, Helm, monitoring, DR |
| 📙 docs/API.md | REST API reference, auth, pagination, error codes |
| 📔 docs/STORAGE.md | MinIO / Aliyun OSS / S3 adapters, presigned URLs, CDN |
| 📓 docs/RESILIENCE.md | Rate limit, circuit breaker, retry, bulkhead |
| 📒 docs/TRACING.md | OpenTelemetry setup, sampling, MDC integration |
| 📕 docs/FAQ.md | Common questions, troubleshooting |
| 🇨🇳 docs/i18n/README.zh-CN.md | 简体中文文档 |
# Unit + integration tests (89 test classes across starters + MCP)
cd backend && ./gradlew test
# E2E (60+ Playwright cases, headless)
cd vue3-admin && npm run test:e2e
# UI mode for debugging
npm run test:e2e:ui
# Helm chart lint + dry-run
./deploy/helm/scripts/lint.shCoverage report is uploaded to Codecov on every PR. See .github/workflows/ for the full matrix.
We welcome contributions of any size — typo fixes, doc improvements, new starters, new MCP servers, new sample apps.
- ⭐ Star this repo (helps us prioritize)
- 🍴 Fork & create a branch from
main - 💻 Make your change + add a test
- 📝 Run
pre-commit(auto-fmt + lint) - 🚀 Open a PR — small PRs (<300 LOC) get reviewed fastest
- ✅ Pass CI (build + test + lint + security + helm-lint)
See CONTRIBUTING.md for conventions and CODE_OF_CONDUCT.md for community standards.
New to the codebase? Look for issues labeled
good first issue— they're hand-picked for newcomers.
We follow a "discuss before code" model. Please don't open a PR for a non-trivial change without first creating an issue:
- 🔍 Search existing issues to avoid duplicates
- 💡 Open an issue using the appropriate template (bug report / feature request / question)
- 💬 Discuss with maintainers — we may suggest a different approach or pair you with a reviewer early
- ✅ Get a green light (label
status: ready-for-pr) - 🚀 Open the PR referencing the issue (e.g.
Closes #123) - 🔁 Iterate based on review
This avoids wasted effort and keeps the roadmap coherent. See ISSUE_WORKFLOW.md for the full triage playbook.
| Quarter | Focus | Status |
|---|---|---|
| Q1 2026 | Core framework + 4 MCP servers + 18 controllers + CI/CD | ✅ shipped |
| Q2 2026 | vue-i18n, Resilience4j, multi-cloud storage, OpenTelemetry, Playwright E2E, Helm chart | ✅ shipped |
| Q3 2026 | AI Agent platform enhancements, MCP Marketplace, plugin system, low-code generator | 🚧 in progress |
| Q4 2026 | Edge runtime (GraalVM native), WASM frontend, mobile (uni-app), GraphQL gateway | 📋 planned |
See the open issues for the live backlog and vote on what matters most with 👍 reactions.
- ~180k LOC across Java / TypeScript / Python / Vue / Gradle / K8s / Helm
- 89 test classes in the backend, 60+ Playwright E2E cases
- 27 Vue views, 24 API modules, 35+ REST endpoints per micro-service
- 81 Helm chart files covering 6 services + observability + ingress
- 10 MCP tools per server, 3 language implementations (Java / Node / Python)
- 💡 Discussions — github.com/processcrash/xarch/discussions for Q&A, ideas, show & tell
- 🐛 Issues — github.com/processcrash/xarch/issues for bugs and feature requests
- 🔒 Security — see SECURITY.md for private disclosure process
- 📜 Changelog — CHANGELOG.md
- 🌐 i18n — docs/i18n/ (中文 README available)
MIT © xarch contributors
Built with care by the xarch community · ⭐ star us if this helped you build something