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, reactions, events, engagement, notifications, news, profiles, and media-room metadata; its live WebSocket gateway has polling fallback.
• Bleu Client is the member-facing web app and same-origin HTTP/WebSocket gateway to community BleuSocial services. Sign-in delegates to CMMC, which remains authoritative for identity and authorization.
• 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, serves its branded landing page at /, and stores development data in data/cmmc.sqlite by default. On first start, use the one-time setup token printed in the service log. In the Instance step, enter browser-facing CMMC and Bleu Client origins; single-label container hosts such as http://cmmc:3000 are not prefilled and produce a warning because members' browsers may not resolve them. Loopback origins remain supported for local development. Only a clean database is supported: nightly and prototype CMMC databases are not migrated. Back up any data that must be retained, then run bun run dev:cmmc:reset only for disposable local state (the command is destructive). CMMC creates schema version 26; BleuSocial creates its clean migration sequence (versions 1 and 2).

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_CMMC_PUBLIC_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. The token must
# be in an owner-only file; BLEUAGENT_TOKEN is intentionally rejected.
umask 077
mkdir -p data
printf '%s' 'cmmc_agent_...' > data/bleuagent-token
BLEUAGENT_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUAGENT_TARGET_ID=<deployment-target-id> \
BLEUAGENT_TOKEN_FILE=data/bleuagent-token \
bun run dev:bleuagent

Default local ports are CMMC 3000, BleuBridge 3001, BleuSocial 3002, and Bleu Client 3003. BLEU_CLIENT_CMMC_BASE_URL is the internal server-to-server origin. Optional BLEU_CLIENT_CMMC_PUBLIC_URL is an origin-only browser-facing override; without it, Bleu Client uses the public CMMC origin advertised by gateway metadata, then falls back to the internal origin. Bleu Client /login redirects to CMMC's /login flow; after authentication, the member shell provides sign-out and community switching. Social message, thread, and profile reads are cursor-paginated, message pages carry reaction summaries, and the browser consumes live message/reaction/notification deltas through the same-origin /api/gateway WebSocket with polling fallback.

Validate a change

bun run check:repo-health
bun run check
bun test
bun run test:coverage
bun run audit
bun run build
bun run backup:drill
bun scripts/sensitive-scan.ts

bun run ci:pr is the canonical fast pull-request gate and bun run ci:release is the canonical local release gate. Run one workspace suite with bun run --cwd apps/<name> test, where <name> is cmmc, bleubridge, bleusocial, bleuclient, or bleuagent.

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. Compose passes BLEU_BUILD_VERSION and BLEU_BUILD_COMMIT as build arguments to all five images; runtime status and rendered build footnotes therefore identify the built version and commit. This is development topology, not an internet-facing deployment. Production must combine the base file with the security overlay, use immutable image digests and mounted secret files, terminate TLS at a trusted reverse proxy, and keep internal services and Docker authority off public networks. Follow the deployment guide, security guide, and backup/restore guide.

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.
  • src/server/: server composition plus implemented route-family modules such as agent-routes.ts, audit-routes.ts, deployment-routes.ts, and privacy-routes.ts.
  • src/store/repositories/: domain persistence implementations behind src/store/sqlite-store.ts and the store contracts.
  • src/ui/views/: bounded server-rendered layouts, pages, and primitives composed through src/ui/views.ts.
  • src/static/app/: bounded browser runtime, route, tab, form, and incremental-rendering modules; src/static/styles.css is the served entry point for the consolidated src/static/styles/ layer set.
• apps/bleubridge: synchronization service and generic/Discord adapters.
• apps/bleusocial: native community API, route-family modules, /api/gateway WebSocket transport, and independent SQLite store.
• apps/bleuclient: member web app and CMMC-routed same-origin HTTP/WebSocket Social gateway. The former src/unreleased/ tree has been removed; target product-registry/platform work remains documentation-only.
• apps/bleuagent: outbound deployment agent.
• packages/http, shared, social-web, ssr, ui, db: shared runtime and UI packages. SQLite remains the supported store adapter; experimental PostgreSQL is isolated behind @bleu/db/experimental-postgres.
• 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.