botsu.app/docs/adr/0001-development-isolation.md

ADR 0001: Isolate collaborative-suite development from production

• Status: Accepted
• Date: 2026-08-03

Context

client.botsu.net is the active Matrix client for BOTSU members. It depends on Synapse, MAS, Authentik, LiveKit, coturn, and Traefik. The collaborative-suite work will substantially extend Cinny and must not destabilize messaging, SSO, room navigation, or calls.

The current production client is a branded static build of Cinny v4.12.6 served from CT 210. The source workspace is a separate monorepo at /root/botsu.app with a private Gitea origin and the official Cinny repository configured as upstream.

Decision

Development will remain isolated from production:

1. Application code lives only in /root/botsu.app until a canary is explicitly approved.
2. Cinny remains under apps/client; BOTSU-specific code will be isolated under apps/client/src/botsu and shared packages/ where practical.
3. Local development servers bind to 127.0.0.1 by default and are stopped after verification.
4. No development command writes to /opt/services/client-botsu.
5. No DNS, Traefik, firewall, SSH, NAT, or public-port change is part of normal development.
6. No Matrix access token or other production secret is committed or exposed to embedded applications.
7. Code changes follow test-driven development: failing test, minimal implementation, passing test, refactor, relevant full suite.
8. Each completed task receives a local commit and is pushed to Gitea only after task validation, as explicitly authorized by the user.
9. A production switch requires a separate immutable image, a private canary, an explicit network/routing confirmation, two-user testing, and a verified rollback.

Baseline quality policy

The untouched Cinny v4.12.6 source builds successfully, but its current locked dependency set does not pass the upstream typecheck or lint scripts. These failures are recorded as inherited baseline debt; they must not be hidden.

BOTSU code will have scoped green tests, type checking, linting, and build gates from its first implementation. The inherited failures will be investigated and resolved or isolated before a release candidate. No new failure may be added to the recorded baseline.

Consequences

Positive

• Production behavior remains unchanged during development.
• Rollback remains independent of the source repository.
• BOTSU extensions can be reviewed and tested separately from inherited Cinny debt.
• Future Cinny updates retain a documented upstream path.

Trade-offs

• Development and production artifacts temporarily use different delivery paths.
• Full-repository quality gates cannot be declared green until inherited Cinny issues are addressed.
• Canary deployment needs an explicit later infrastructure decision.

Rejected alternatives

• Editing the static production files directly: not maintainable and unsafe.
• Replacing client.botsu.net immediately with each development build: no isolation or reliable rollback.
• Suppressing inherited type/lint failures globally: would conceal regressions.
• Introducing Redis, MinIO, or additional microservices before demonstrated need: unnecessary for the MVP.