writing-server-code

Architectural Rationale

Command Query Separation (CQS)

New features should use the CQS pattern — discrete action classes instead of large entity-focused services. See ADR-0008.

Why CQS matters at Bitwarden: The codebase historically grew around entity-focused services (e.g., CipherService) that accumulated hundreds of methods. CQS breaks these into single-responsibility classes (CreateCipherCommand, GetOrganizationApiKeyQuery), making code easier to test, reason about, and modify without unintended side effects.

Commands = write operations. Change state, may return result. Named after the action: RotateOrganizationApiKeyCommand.

Queries = read operations. Return data, never change state.

When NOT to use CQS: When modifying existing service-based code, follow the patterns already in the file. Don't refactor to CQS unless explicitly asked. If asked to refactor, apply the pattern only to the scope requested.

Caching

When caching is needed, follow the conventions in CACHING.md. Use IFusionCache instead of IDistributedCache.

Don't implement caching unless requested. If a user describes a performance problem where caching might help, suggest it — but don't implement without confirmation.