MX Space Core

AI-powered CMS Core for personal blogs, creator homepages & content websites.

---

Overview

MX Space Core is a headless CMS server built with NestJS, MongoDB, and Redis. Beyond standard blog features (posts, pages, notes, comments, categories, feeds, search), it ships with a full AI content workflow — summary generation, multi-language translation, comment moderation, and writing assistance — powered by pluggable LLM providers.

Key Features

Category	Capabilities
Content Management	Posts, notes, pages, drafts, categories, topics, comments, snippets, projects, friend links, subscriptions
AI Workflow	Summary generation, multi-language translation, comment moderation, writing assistance, streaming responses
LLM Providers	OpenAI, OpenAI-compatible, Anthropic, OpenRouter
Real-time	WebSocket via Socket.IO with Redis adapter for multi-instance broadcast
Distribution	RSS/Atom feeds, sitemap, local search, aggregate API
Auth	JWT sessions, passkeys, OAuth, API keys (via better-auth)
Deployment	Docker (multi-arch), PM2, standalone binary

Tech Stack

• Runtime: Node.js >= 22 + TypeScript 5.9
• Framework: NestJS 11 + Fastify
• Database: MongoDB 7 (Mongoose / TypeGoose)
• Cache: Redis (ioredis)
• Validation: Zod 4
• WebSocket: Socket.IO + Redis Emitter
• AI: OpenAI SDK, Anthropic SDK
• Editor: Lexical (via @haklex/rich-headless)
• Auth: better-auth (session, passkey, API key)
• Testing: Vitest + in-memory MongoDB/Redis

Monorepo Structure

mx-core/
├── apps/
│   └── core/                 # Main server application (NestJS)
├── packages/
│   ├── api-client/           # @mx-space/api-client — SDK for frontend & third-party clients
│   └── webhook/              # @mx-space/webhook — Webhook integration SDK
├── docker-compose.yml        # Development stack (Mongo + Redis)
├── dockerfile                # Multi-stage production build
└── docker-compose.server.yml # Production deployment template

Core Architecture (apps/core/src/)

src/
├── modules/          # 44 business modules
│   ├── ai/           #   AI summary, translation, writer, task queue
│   ├── auth/         #   JWT, OAuth, passkey, API key
│   ├── post/         #   Blog posts
│   ├── note/         #   Short notes with topic support
│   ├── comment/      #   Nested comments + AI moderation
│   ├── configs/      #   Runtime configuration
│   ├── webhook/      #   Event dispatch to external services
│   ├── serverless/   #   User-defined serverless functions
│   └── ...           #   page, draft, category, topic, feed, search, etc.
├── processors/       # Infrastructure services
│   ├── database/     #   MongoDB connection + model registry
│   ├── redis/        #   Cache, pub/sub, emitter
│   ├── gateway/      #   WebSocket (admin, web, shared namespaces)
│   ├── task-queue/   #   Distributed job queue (Redis + Lua)
│   └── helper/       #   Email, image, JWT, Lexical, URL builder, etc.
├── common/           # Guards, interceptors, decorators, filters, pipes
├── constants/        # Business events, cache keys, error codes
├── transformers/     # Response transformation (snake_case, pagination)
├── migration/        # Versioned DB migrations (v2 → v10)
└── utils/            # 34 utility modules

Quick Start

Prerequisites

Dependency	Version
Node.js	>= 22
pnpm	Latest (via Corepack)
MongoDB	7.x
Redis	7.x

Local Development

# Enable Corepack for pnpm
corepack enable

# Install dependencies
pnpm install

# Start MongoDB + Redis (via Docker)
docker compose up -d mongo redis

# Start dev server (port 2333)
pnpm dev

The API is available at http://localhost:2333. In development mode, routes have no /api/v2 prefix.

Docker Deployment

The fastest way to get a production instance running:

# Clone and enter the project
git clone https://github.com/mx-space/core.git && cd core

# Edit environment variables
cp docker-compose.server.yml docker-compose.prod.yml
# Edit docker-compose.prod.yml — set JWT_SECRET, ALLOWED_ORIGINS, etc.

# Start all services
docker compose -f docker-compose.prod.yml up -d

Or use the prebuilt image directly:

docker pull innei/mx-server:latest

The image supports linux/amd64 and linux/arm64.

Available Commands

Run from the repository root:

Command	Description
pnpm dev	Start development server (watch mode)
pnpm build	Build the core application
pnpm bundle	Create production bundle (tsdown)
pnpm test	Run test suite (Vitest)
pnpm lint	Run ESLint with auto-fix
pnpm typecheck	TypeScript type checking
pnpm format	Format code with Prettier

Running Tests

# Run all tests
pnpm test

# Run a specific test file
pnpm test -- test/src/modules/user/user.service.spec.ts

# Run tests matching a pattern
pnpm test -- --testNamePattern="should create user"

# Watch mode
pnpm -C apps/core run test:watch

Environment Variables

Variable	Description	Default
JWT_SECRET	Secret for JWT signing	Required
ALLOWED_ORIGINS	CORS allowed origins (comma-separated)	—
DB_HOST	MongoDB host	localhost
REDIS_HOST	Redis host	localhost
REDIS_PORT	Redis port	6379
REDIS_PASSWORD	Redis password	—
MONGO_CONNECTION	Full MongoDB connection string (overrides DB_HOST)	—
ENCRYPT_ENABLE	Enable field encryption	false
ENCRYPT_KEY	64-char hex encryption key	—
THROTTLE_TTL	Rate limit window (seconds)	10
THROTTLE_LIMIT	Max requests per window	100
PORT	Server port	2333
TZ	Timezone	Asia/Shanghai
DISABLE_CACHE	Disable Redis caching	false

Configuration can also be provided via CLI arguments or YAML files. See apps/core/src/app.config.ts for the full config schema.

API Response Format

All responses are automatically transformed by interceptors:

• Array → { data: [...] }
• Object → returned as-is
• Paginated (via @Paginator) → { data: [...], pagination: {...} }
• Bypass (via @Bypass) → raw response

All response keys are converted to snake_case (e.g., createdAt → created_at).

Upgrading

v10 → v11

v11 refactors the Aggregate API: categories and pageMeta are removed from GET /aggregate; a new GET /aggregate/site endpoint is added for lightweight site metadata. See Upgrading to v11.

v9 → v10

v10 includes a breaking auth system refactor. See Upgrading to v10.

Related Projects

Project	Description
Shiroi	Next.js frontend
mx-admin	Vue 3 admin dashboard
@mx-space/api-client	TypeScript API client SDK
@haklex/rich-headless	Lexical editor (server-side)

License

• apps/ — AGPLv3 with Additional Terms
• Everything else — MIT

See LICENSE for full details.