android/.claude/CLAUDE.md

Bitwarden Android - Claude Code Configuration

Official Android application for Bitwarden Password Manager and Bitwarden Authenticator, providing secure password management, two-factor authentication, and credential autofill services with zero-knowledge encryption.

Overview

• Multi-module Android application: :app (Password Manager), :authenticator (2FA TOTP generator)
• Zero-knowledge architecture: encryption/decryption happens client-side via Bitwarden SDK
• Target users: End-users via Google Play Store and F-Droid

Key Concepts

• Zero-Knowledge Architecture: Server never has access to unencrypted vault data or encryption keys
• Bitwarden SDK: Rust-based cryptographic SDK handling all encryption/decryption operations
• DataState: Wrapper for streaming data states (Loading, Loaded, Pending, Error, NoNetwork)
• Result Types: Custom sealed classes for operation results (never throw exceptions from data layer)
• UDF (Unidirectional Data Flow): State flows down, actions flow up through ViewModels

---

Architecture

User Request (UI Action)
         |
    Screen (Compose)
         |
    ViewModel (State/Action/Event)
         |
    Repository (Business Logic)
         |
    +----+----+----+
    |    |    |    |
  Disk  Network  SDK
   |      |      |
 Room  Retrofit  Bitwarden
  DB    APIs     Rust SDK

Key Principles

1. No Exceptions from Data Layer: All suspending functions return Result<T> or custom sealed classes
2. State Hoisting to ViewModel: All state that affects behavior must live in the ViewModel's state
3. Interface-Based DI: All implementations use interface/...Impl pairs with Hilt injection
4. Encryption by Default: All sensitive data encrypted via SDK before storage

Core Patterns

• BaseViewModel: Enforces UDF with State/Action/Event pattern. See ui/src/main/kotlin/com/bitwarden/ui/platform/base/BaseViewModel.kt.
• Repository Result Pattern: Type-safe error handling using custom sealed classes for discrete operations and DataState<T> wrapper for streaming data.
• Common Patterns: Flow collection via Internal actions, error handling via when branches, DataState streaming with .map { } and .stateIn().

For complete architecture patterns, code templates, and module organization, see docs/ARCHITECTURE.md.

---

Development Guide

Workflow Skills

Quick start: Use the bitwarden-tech-lead:bitwarden-tech-lead agent (or /plan-android-work <task>) to refine requirements and plan, then the bitwarden-software-engineer:bitwarden-software-engineer agent (or /work-on-android <task>) for implementation, then /review-android <PR#> to review the result.

Skills & Commands

Skill	Triggers
build-test-verify	"build", "run tests", "lint", "format", "verify build"
implementing-android-code	"implement", "write code", "add screen", "create feature"
planning-android-implementation	"plan implementation", "architecture design", "phased task breakdown"
refining-android-requirements	"refine requirements", "analyze ticket", "gap analysis"
reviewing-changes	"review", "code review", "check PR"
testing-android-code	"write tests", "add test coverage", "unit test"

Command	Usage
/plan-android-work <task>	Fetch ticket → refine requirements → design implementation approach
/work-on-android <task>	Full workflow: implement → test → verify → preflight → commit → review → PR
/review-android <PR#>	Full review workflow: PR context gathering → Android checklist → output

---

Security Rules

MANDATORY - These rules have no exceptions:

1. Zero-Knowledge Architecture: Never transmit unencrypted vault data or master passwords to the server. All encryption happens client-side via the Bitwarden SDK.
2. No Plaintext Key Storage: Encryption keys must be stored using Android Keystore (biometric unlock) or encrypted with PIN/master password.
3. Sensitive Data Cleanup: On logout, all sensitive data must be cleared from memory and storage via UserLogoutManager.logout().
4. Input Validation: Validate all user inputs before processing, especially URLs and credentials.
5. SDK Isolation: Use scoped SDK sources (ScopedVaultSdkSource) to prevent cross-user crypto context leakage.

---

Code Style & Standards

• Formatter: Android Studio with bitwarden-style.xml | Line Limit: 100 chars | Detekt: Enabled
• Naming: camelCase (vars/fns), PascalCase (classes), SCREAMING_SNAKE_CASE (constants), ...Impl (implementations)
• KDoc: Required for all public APIs
• String Resources: Add new strings to :ui module (ui/src/main/res/values/strings.xml). Use typographic quotes/apostrophes (" " ') not escaped ASCII (\" \'). Name each resource from its own text content in snake_case — not with generic suffixes (_message, _title). E.g., one_or_more_email_addresses_are_incorrect, not invalid_email_addresses_message.

For complete style rules (imports, formatting, documentation, Compose conventions), see docs/STYLE_AND_BEST_PRACTICES.md.

---

Anti-Patterns

In addition to the Key Principles above, follow these rules:

DO

• Map async results to internal actions before updating state
• Inject Clock for time-dependent operations
• Return early to reduce nesting

DON'T

• Update state directly inside coroutines (use internal actions)
• Use any types or suppress null safety
• Catch generic Exception (catch specific types)
• Use e.printStackTrace() (use Timber logging)
• Create new patterns when established ones exist
• Skip KDoc for public APIs

---

Quick Reference

• Code style: Full rules: docs/STYLE_AND_BEST_PRACTICES.md
• Before writing code: Use implementing-android-code skill for Bitwarden-specific patterns, gotchas, and templates
• Before writing tests: Use testing-android-code skill for test patterns and templates
• Building/testing: Use build-test-verify skill | App tests: ./gradlew app:testStandardDebugUnitTest
• Before committing: Use bitwarden-delivery-tools:perform-preflight skill, then bitwarden-delivery-tools:committing-changes skill for message format
• Code review: Use /review-android for the full review workflow; reviewing-changes skill for checklist-only
• Creating PRs: Use bitwarden-delivery-tools:creating-pull-request skill for PR workflow and templates
• Troubleshooting: See docs/TROUBLESHOOTING.md
• Architecture: docs/ARCHITECTURE.md | Bitwarden SDK | Jetpack Compose | Hilt DI