Mix Space

Monorepo for the Mix Space personal-CMS stack — the core server, admin dashboard, native iOS client, privacy-preserving push relay, telemetry, and the shared SDKs that bind them.

---

Overview

Mix Space is an AI-powered, headless CMS for personal blogs, creator homepages, and content websites. This repository is the workspace that builds the entire stack — it grew out of the core server and now ships the backend, the admin UI, a native mobile client, an independent push relay, and the packages every client shares.

flowchart LR
  WEB["Yohaku frontend<br/>(external)"]
  ADMIN["Admin SPA"]
  IOS["iOS · Space"]
  CORE["Core server<br/>NestJS · PostgreSQL · Redis"]
  RELAY["Push Relay<br/>(APNs boundary)"]
  TELE["Telemetry<br/>(Cloudflare Worker)"]

  WEB -->|"@mx-space/api-client"| CORE
  ADMIN -->|"/proxy/qaqdmin"| CORE
  IOS -->|"OpenAPI client"| CORE
  CORE -->|"comment id only"| RELAY -->|APNs| IOS
  CORE -.->|webhook| EXT["external services"]
  CORE -.->|anonymous| TELE

Apps

Path	Package	What it is
apps/core	@mx-space/core	The heart of the stack — AI-powered headless CMS server (NestJS + Fastify + PostgreSQL + Redis).
apps/admin	@mx-admin/admin	React 19 admin dashboard SPA, built into the server and served at /proxy/qaqdmin.
apps/ios	Space	Native iOS admin client — UIKit shell with SwiftUI leaf screens (XcodeGen).
apps/push-relay-rs	push-relay (Rust)	Independently deployable, privacy-preserving APNs relay.
apps/telemetry	@mx-space/telemetry	Anonymous instance-telemetry collector (Cloudflare Worker + D1).

Packages

Path	Package	What it is
packages/api-client	@mx-space/api-client	Typed SDK for frontends and third-party clients.
packages/cli	@mx-space/cli (mxs)	Owner-side CLI for content + config (Effect-TS, OIDC device auth).
packages/db-schema	@mx-space/db-schema	Shared Drizzle schema + Snowflake utilities (private).
packages/editor	@mx-space/editor	Lexical editor contracts and projection utilities.
packages/ai	@mx-space/ai	Shared AI contracts (SSE event unions) for server and clients.
packages/push-protocol	@mx-space/push-protocol	Versioned protocol shared by mx-core and Push Relay.
packages/webhook	@mx-space/webhook	Signature-verified webhook handler SDK.
packages/mongo-pg-cli	@mx-space/mongo-pg-cli	One-shot v11→v12 (MongoDB→PostgreSQL) data migration.
packages/e2e	—	End-to-end test suite (Vitest + testcontainers).

Layout

mx-core/
├── apps/
│   ├── core/        # NestJS server
│   ├── admin/       # React 19 admin SPA
│   ├── ios/         # native iOS client (XcodeGen)
│   ├── push-relay-rs/ # independent APNs relay (Rust + SQLite)
│   └── telemetry/   # telemetry collector (CF Worker)
├── packages/        # shared SDKs, schema, editor & AI contracts, CLI, tests
├── docker-compose.yml        # dev stack (PostgreSQL + Redis + mx-migrate)
├── docker-compose.server.yml # production deployment template
└── dockerfile                # multi-stage production build

Quick Start

corepack enable
pnpm install

# Start PostgreSQL + Redis (via Docker)
docker compose up -d postgres redis

# Core dev server → http://localhost:2333
pnpm dev

# Admin SPA dev server → http://localhost:9528 (run alongside core)
pnpm dev:admin

Per-app setup, deployment, and operational docs live in each app's own README — start at apps/core for the server.

Commands

Run from the repo root:

Command	Effect
pnpm dev	Core dev server (watch mode)
pnpm dev:admin	Admin SPA dev server
pnpm build	Build the core application
pnpm bundle	Production bundle (Vite)
pnpm test	Core test suite (Vitest)
pnpm e2e	End-to-end suite
pnpm typecheck	Core typecheck + controller/validate guards
pnpm lint / pnpm format	ESLint / Prettier

Conventions

• Response envelope — success: { data, meta? }; error: { error: { code, message, details? } }. Code is camelCase end-to-end; the wire format is snake_case. Full detail in the core README.
• Migrations — forward SQL migrations run as a one-shot release-phase step, never on boot. Historical MongoDB → PostgreSQL data lives in packages/mongo-pg-cli. Upgrade notes: core README · Upgrading.

Related Projects

Project	Description
Yohaku	Next.js frontend (recommended)
Shiro	Minimalist frontend
Kami	Anime-flavored frontend (legacy)
@haklex/rich-headless	Lexical editor (server-side)

License

AGPLv3 + MIT — see ADDITIONAL_TERMS.md.