Bleu

Bleu is a Bun/TypeScript workspace for community operations and native community services.

• CMMC is the administrative control plane for accounts, communities, policy, membership, cases, privacy, audit, product provisioning, and fleet management.
• BleuBridge imports external community state and applies CMMC-owned actions through versioned service APIs.
• BleuSocial owns native channels, threads, messages, events, engagement, notifications, news, profiles, and media-room metadata.
• Bleu Client is the member-facing web app and same-origin gateway to community BleuSocial services.
• BleuAgent is the outbound-only deployment agent used by CMMC-managed targets.

Release scope and known pre-release risks are tracked in docs/release-readiness.md. Planning material is directional and is not a release claim.

Quick start

Requirements: Bun and Git. The optional pinned Nix shell also supplies Node, Docker Compose, SQLite, curl, and common POSIX tools.

git clone <repository-url>
cd bleu
nix develop # optional
bun install --frozen-lockfile
bun run dev:cmmc

CMMC listens on http://127.0.0.1:3000 and stores development data in data/cmmc.sqlite by default. On first start, use the one-time setup token printed in the service log. Prototype databases from the pre-baseline migration chain must be reset with bun run dev:cmmc:reset or migrated with an explicit operator script.

Start another component in a separate terminal when needed:

# Bridge requires a Bridge-scoped CMMC service credential.
BLEUBRIDGE_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUBRIDGE_SERVICE_TOKEN=cmmc_svc_... \
BLEUBRIDGE_ADMIN_TOKEN=bridge_admin_local_dev_token \
bun run dev:bleubridge

# Social may start unconfigured; these values enable CMMC bootstrap.
BLEUSOCIAL_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUSOCIAL_SERVICE_TOKEN=cmmc_svc_... \
bun run dev:bleusocial

# Client needs a generic token with communities:read for gateway routing.
BLEU_CLIENT_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEU_CLIENT_SERVICE_TOKEN=cmmc_svc_... \
bun run dev:bleuclient

# Agent credentials are generated by CMMC Fleet Management.
BLEUAGENT_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUAGENT_TARGET_ID=<deployment-target-id> \
BLEUAGENT_TOKEN=cmmc_agent_... \
bun run dev:bleuagent

Default local ports are CMMC 3000, BleuBridge 3001, BleuSocial 3002, and Bleu Client 3003.

Validate a change

bun test
bun run check
bun run build

Run one workspace suite with bun run --cwd apps/<name> test, where <name> is cmmc, bleubridge, bleusocial, bleuclient, or bleuagent. bun run check:repo-health performs the fast repository hygiene check used by documentation changes.

Docker development

docker compose -f infra/docker/compose.yml up --build

The base stack starts CMMC and Bleu Client. Optional profiles start internal product services:

COMPOSE_PROFILES=bridge BLEUBRIDGE_SERVICE_TOKEN=cmmc_svc_... \
docker compose -f infra/docker/compose.yml up --build

COMPOSE_PROFILES=social BLEUSOCIAL_SERVICE_TOKEN=cmmc_svc_... \
docker compose -f infra/docker/compose.yml up --build

Bridge and Social bind to host loopback; CMMC and Bleu Client are published on ports 3000 and 3003. Data is held in separate cmmc-data and bleusocial-data volumes. Do not treat this development Compose file as a complete internet-facing deployment: add TLS and a trusted reverse proxy, and follow the security and operations guides.

For the published :indev sandbox, use bun run indev:test, bun run indev:launch, bun run indev:console, or bun run indev:cleanup --dry-run. See the incident runbooks before destructive cleanup.

Repository layout

• apps/cmmc: control plane, REST API, WebUI, SQLite store, and tests.
• apps/bleubridge: synchronization service and generic/Discord adapters.
• apps/bleusocial: native community API and independent SQLite store.
• apps/bleuclient: member web app and CMMC-routed Social gateway.
• apps/bleuagent: outbound deployment agent.
• packages/http, shared, social-web, ssr, ui, db: shared runtime and UI packages.
• infra/docker: image, Compose, and indev tooling.

Documentation

The current documentation contract is v1:

• Documentation index
• Architecture
• API guide
• Security guide
• Backup and restore
• Incident runbooks
• Release readiness

Versioning applies to the documentation contract, not to every browser route. Service integrations should use /api/service/v1/*; unversioned administrative and member routes may evolve with the application release.