RCS Internal Architecture Docs

⚠️ INTERNAL ONLY — Platform + Website Architecture
Not intended for public distribution.

This handbook is the single source of truth for the RCS platform. It covers how the monorepo is structured, how we build and deploy, and the security posture that every change must respect. Nothing in this space is suitable for external publication.

Platform Snapshot

• apps/site — Public marketing surface (Astro 6.0.0-beta.3) served at http://localhost:4321 in Docker.
• apps/docs — Internal documentation (Astro 5.16.15 + Starlight 0.37.4) served at http://localhost:4322 in Docker.
• Target deployment — Cloudflare Pages for both applications, with Cloudflare Access shielding docs in the future.

How To Use This Hub

1. Start with the Architecture overview to understand major components and boundaries.
2. Review Principles before proposing changes; they drive every decision and roadmap adjustment.
3. Consult ADRs whenever altering platform behaviour—you must document new or amended decisions.
4. Follow the Ops runbooks for deterministic local development and future Cloudflare publishing.
5. Keep Security guidance in mind; Zero Trust and no-secrets-in-repo are non-negotiable.

Governance Expectations

• Every material change ships with an ADR or ADR update.
• New diagrams belong in the Diagrams library and must render client-side via Mermaid or D2.
• Marketing launches follow the Marketing releases checklist.
• Security reviews start with Threat model (lite), then escalate as scope grows.

Reference Commands

Canonical local dev workflow (recommended)

# 1) Start the dev container (idle but ready)
docker compose up -d dev

# 2) Install dependencies (deterministic)
docker compose exec dev bash -lc "pnpm install"

# 3) Run site + docs (two terminals recommended)
docker compose exec dev bash -lc "pnpm dev:site"   # http://localhost:4321
docker compose exec dev bash -lc "pnpm dev:docs"   # http://localhost:4322

One-shot alternative (useful for quick checks)

# Publishes ports and runs the server in a disposable container
docker compose run --rm --service-ports dev bash -lc "pnpm dev:site"
docker compose run --rm --service-ports dev bash -lc "pnpm dev:docs"

Build verification (CI-equivalent)

docker compose run --rm -T dev bash -lc "pnpm install"
docker compose run --rm -T dev bash -lc "pnpm build:site"
docker compose run --rm -T dev bash -lc "pnpm build:docs"

---

1. Open or update an ADR whenever a platform or marketing decision impacts governance.
2. Keep runbooks deterministic by documenting Docker and pnpm commands exactly as executed.
3. Label sensitive topics as INTERNAL ONLY; nothing in this site is intended for external publication.