bitwarden/browser
1
0
Fork 0
mirror of https://github.com/bitwarden/browser synced 2026-02-24 08:33:29 +00:00
Code Issues Releases Wiki Activity

Initial bitwarden team core docs (#19048)

Browse Source
This commit is contained in:
Leslie Tilton
2026-02-23 08:47:16 -06:00
committed by GitHub
parent 494dd7d329
commit 2af9396766
4 changed files with 824 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
bitwarden_license/bit-common/src/dirt/docs/README.md Normal file
View File

@@ -0,0 +1,73 @@
# DIRT Team Documentation
**Location:** `bitwarden_license/bit-common/src/dirt/docs/`
**Purpose:** Overview of DIRT team documentation with navigation to detailed guides
---
## 🎯 Start Here
**New to the DIRT team?** → [Getting Started](./getting-started.md)
**Looking for something specific?**
- **"What should I read for my task?"** → [Getting Started](./getting-started.md)
- **"How are docs organized?"** → [Documentation Structure](./documentation-structure.md)
- **"How do I implement a feature?"** → [Playbooks](./playbooks/)
- **"What are the coding standards?"** → [Standards](./standards/)
- **"How do services integrate with components?"** → [Integration Guide](./integration-guide.md)
---
## 📁 What's in This Folder
| Document/Folder | Purpose |
| -------------------------------------------------------------- | ------------------------------------------------- |
| **[getting-started.md](./getting-started.md)** | Navigation hub - what to read for your task |
| **[documentation-structure.md](./documentation-structure.md)** | Complete structure guide - how docs are organized |
| **[integration-guide.md](./integration-guide.md)** | Service ↔ Component integration patterns |
| **[playbooks/](./playbooks/)** | Step-by-step implementation guides |
| **[standards/](./standards/)** | Team coding and documentation standards |
| **[access-intelligence/](./access-intelligence/)** | Migration guides and architecture comparisons |
---
## 🏗️ DIRT Team Features
The DIRT team (Data, Insights, Reporting & Tooling) owns:
- **Access Intelligence** - Organization security reporting and password health
- **Organization Integrations** - Third-party integrations
- **External Reports** - Organization reports (weak passwords, member access, etc.)
- **Phishing Detection** - Browser-based phishing detection
**Documentation is organized by package:**
- **bit-common** - Platform-agnostic services (work on all platforms)
- **bit-web** - Angular web components (web client only)
- **bit-browser** - Browser extension components
For detailed feature documentation locations, see [Getting Started](./getting-started.md).
---
## 📝 Creating New Documentation
**Before creating new docs, follow these steps:**
1. **Read the standards:** [Documentation Standards](./standards/documentation-standards.md)
2. **Check for overlaps:** Review existing docs to avoid duplication
3. **Follow the playbook:** [Documentation Playbook](./playbooks/documentation-playbook.md)
4. **Update navigation:** Add to [getting-started.md](./getting-started.md) if it's a primary entry point
5. **Update this README:** If adding a new category or top-level document
**For detailed guidance on where to place docs, see:**
- [Documentation Standards § Document Location Rules](./standards/documentation-standards.md#document-location-rules)
- [Documentation Structure](./documentation-structure.md)
---
**Document Version:** 1.0
**Last Updated:** 2026-02-17
**Maintainer:** DIRT Team

277
bitwarden_license/bit-common/src/dirt/docs/documentation-structure.md Normal file
View File

@@ -0,0 +1,277 @@
# DIRT Team Documentation Structure
**Purpose:** Navigation guide for all DIRT team documentation organized by team/feature hierarchy
---
## 📁 Documentation Organization
DIRT team documentation follows a **team/feature** hierarchy organized across multiple locations based on separation of concerns:
### Team-Level Documentation
**Location:** `bitwarden_license/bit-common/src/dirt/docs/`
**Scope:** Applies to all DIRT features (Access Intelligence, Phishing Detection, etc.)
**Contains:**
- Team playbooks (service, component, documentation)
- Team coding standards
- Integration guides
- Getting started guide
### Feature-Level Documentation
**Pattern:** Feature docs live **next to the feature code**, not in the team `docs/` folder.
**Location:** `dirt/[feature]/docs/`
**Examples:**
- **Access Intelligence:** `dirt/access-intelligence/v2/docs/` (or `dirt/access-intelligence/docs/` for current version)
- **Phishing Detection (future):** `dirt/phishing-detection/docs/`
**Feature docs contain:**
- Feature-specific architecture
- Feature-specific implementation guides
- Feature-specific patterns
**Exception:** Migration/transition documentation can live in team `docs/` as **team-level knowledge**. Example: `docs/access-intelligence/` contains migration guides from v1 to v2, which is team-level context about the transition, not feature-specific architecture.
### 1. Services & Architecture (Platform-Agnostic)
**Pattern:** `bitwarden_license/bit-common/src/dirt/[feature]/docs/`
**Purpose:** Feature-specific documentation lives next to the feature code
**Example for Access Intelligence:**
- Location: `dirt/access-intelligence/v2/docs/` (for v2 architecture)
- Contains: Architecture docs, implementation guides specific to that version
**Note:** Team-level migration docs may live in `docs/access-intelligence/` as team knowledge about the transition between versions.
### 2. Components (Angular-Specific)
**Pattern:** `bitwarden_license/bit-web/src/app/dirt/[feature]/docs/`
**Purpose:** Angular-specific UI components for web client only
**Example for Access Intelligence:**
- Location: `dirt/access-intelligence/docs/`
- Contains: Component inventory, migration guides, Storybook
---
## 🎯 Where to Start?
**For navigation guidance (what to read), see:** [getting-started.md](./getting-started.md)
This document focuses on **how** the documentation is organized, not **what** to read.
---
## 🗂️ Complete File Structure
```
# ============================================================================
# SERVICES & ARCHITECTURE (bit-common)
# Platform-agnostic - Used by web, desktop, browser, CLI
# ============================================================================
bitwarden_license/bit-common/src/dirt/
├── docs/ ← TEAM-LEVEL documentation only
│ ├── README.md ← Team docs overview
│ ├── getting-started.md ← Entry point for team
│ ├── documentation-structure.md ← This file
│ ├── integration-guide.md ← Service ↔ Component integration
│ │
│ ├── playbooks/ ← Team playbooks (service, component, docs)
│ │ └── README.md ← Playbook navigation
│ │
│ ├── standards/ ← Team coding standards
│ │ └── standards.md ← Core standards
│ │
│ └── access-intelligence/ ← EXCEPTION: Migration guides (team knowledge)
│ ├── README.md ← Migration overview
│ ├── ... ← Migration analysis files
│ ├── architecture/ ← Migration architecture comparison
│ │ └── ... ← Architecture comparison files
│ └── implementation/ ← Implementation guides
│ └── ... ← Integration guides
│
└── [feature]/ ← FEATURE CODE + FEATURE DOCS
└── docs/ ← Feature-specific documentation
├── README.md ← Feature docs navigation
├── architecture/ ← Feature architecture (lives with code)
│ └── ... ← Architecture files
└── implementation/ ← Feature implementation guides
└── ... ← Implementation guide files
# Example for Access Intelligence v2:
bitwarden_license/bit-common/src/dirt/access-intelligence/
├── v2/ ← V2 implementation
│ ├── services/ ← V2 services
│ ├── models/ ← V2 models
│ └── docs/ ← V2-SPECIFIC documentation
│ ├── README.md ← V2 docs overview
│ ├── architecture/ ← V2 architecture
│ │ └── ... ← Architecture files
│ └── implementation/ ← V2 implementation guides
│ └── ... ← Implementation guide files
└── v1/ ← V1 implementation (legacy)
# ============================================================================
# COMPONENTS (bit-web)
# Angular-specific - Web client only
# ============================================================================
bitwarden_license/bit-web/src/app/dirt/[feature]/
├── docs/ ← Component documentation
│ └── README.md ← Component docs navigation
├── [component folders]/ ← Angular components
└── v2/ ← V2 components (if applicable)
# Example for Access Intelligence:
bitwarden_license/bit-web/src/app/dirt/access-intelligence/
├── docs/ ← Component documentation
│ ├── README.md ← Component docs navigation
│ └── ... ← Component guides
├── [components]/ ← Angular components
└── v2/ ← V2 components (if applicable)
└── ... ← V2 component files
```
---
## 🔄 When to Update This Structure
Update this document when:
- [ ] Adding new documentation categories
- [ ] Changing file locations
- [ ] Restructuring documentation organization
---
## 📝 Architecture Decisions
**Where decisions are tracked:**
- **Company-wide ADRs:** Stored in the `contributing-docs` repository
- **Feature-specific decisions:** Tracked in Confluence (link to be added)
- **Local decision notes (optional):** `~/Documents/bitwarden-notes/dirt/decisions/[feature]/` for personal reference before moving to Confluence
- Example: `~/Documents/bitwarden-notes/dirt/decisions/access-intelligence/`
**What goes in repo architecture docs:**
- Current architecture state
- Migration plans and roadmaps
- Technical constraints
- Implementation patterns
**What goes in Confluence:**
- Decision discussions and rationale
- Alternative approaches considered
- Stakeholder input
- Links to Slack discussions
---
## ✏️ Creating New Documentation
**Before creating new documentation, see:** [docs/README.md](./README.md) § Documentation Best Practices
**Key principles:**
- **Single responsibility** - Each document should answer one question
- **Check for overlaps** - Read related docs first
- **Follow naming conventions** - See [documentation-standards.md](./standards/documentation-standards.md)
- **Cross-reference standards** - See [documentation-standards.md § Cross-Reference Standards](./standards/documentation-standards.md#cross-reference-standards)
- **Update navigation** - Add to getting-started.md if it's a primary entry point
---
## 📊 Why This Structure?
### Documentation Placement Principles
**Team-Level Documentation (`docs/`):**
- Applies to all DIRT features
- Playbooks, standards, getting-started guides
- Migration guides and transition documentation (team knowledge about rewrites)
- Cross-feature integration patterns
**Feature-Level Documentation (`dirt/[feature]/docs/`):**
- Lives **next to the feature code**
- Feature-specific architecture
- Version-specific implementation details
- Feature-specific patterns
**Rationale:**
- **Discoverability:** Architecture docs are found where the code lives
- **Versioning:** v1 and v2 can have separate docs directories
- **Maintainability:** Update feature docs without touching team docs
- **Clarity:** Clear separation between "what applies to all features" vs "what applies to this feature"
### Separation of Concerns
**Platform-Agnostic (bit-common):**
- Services work on all platforms (web, desktop, browser, CLI)
- Domain models are platform-independent
- Architecture decisions affect all clients
- **Feature docs live with feature code:** `dirt/[feature]/docs/`
**Angular-Specific (bit-web):**
- Components only used in web client
- Storybook is web-only
- Angular-specific patterns (OnPush, Signals, etc.)
- **Component docs live with components:** `dirt/[feature]/docs/`
### Benefits
1. **Clarity:** Developers know where to look based on what they're working on
2. **Separation:** Team docs vs feature docs, Angular code vs platform-agnostic code
3. **Discoverability:** Feature docs are near feature code
4. **Maintainability:** Easier to update feature docs without affecting team docs
5. **Scalability:** Can add versioned docs (v1/, v2/) next to versioned code
6. **Migration clarity:** Team `docs/` can hold migration guides while feature `docs/` hold version-specific architecture
---
## 🆘 Need Help?
### Can't Find Documentation?
1. **Start with getting-started.md:** [getting-started.md](./getting-started.md)
- Navigation hub for all DIRT team documentation
- Links to all major documentation categories
2. **Check README files:**
- [Team Documentation README](./README.md)
- [Component README](/bitwarden_license/bit-web/src/app/dirt/access-intelligence/docs/README.md)
3. **Check feature-specific docs:**
- Look in `dirt/[feature]/docs/` next to the feature code
- Example: `dirt/access-intelligence/v2/docs/`
### Links Broken?
- Check if file was moved
- Update cross-references following [documentation-standards.md § Cross-Reference Standards](./standards/documentation-standards.md#cross-reference-standards)
- Update navigation in README.md files
---
**Document Version:** 1.0
**Last Updated:** 2026-02-17
**Maintainer:** DIRT Team

96
bitwarden_license/bit-common/src/dirt/docs/getting-started.md Normal file
View File

@@ -0,0 +1,96 @@
# DIRT Team - Getting Started
**Purpose:** Navigation hub showing what documentation is available for your work
---
## 🎯 DIRT Team Features
The **DIRT team** (Data, Insights, Reporting & Tooling) owns:
- **Access Intelligence** (formerly Risk Insights)
- Organization security reporting and password health analysis
- Location: `dirt/reports/risk-insights/` (v1 services), `bit-web/.../access-intelligence/` (UI)
- Note: `risk-insights` is the v1 codebase name for Access Intelligence
- **Organization Integrations**
- Third-party organization integrations
- Location: `dirt/organization-integrations/`
- **External Reports**
- Various organization reports (weak password report, member access report, etc.)
- Documentation: Coming soon
- **Phishing Detection**
- Documentation: Coming soon
**Note:** Access Intelligence has the most documentation as it's the first feature we're documenting comprehensively.
---
## 📚 What's Available
### Development Resources
| Resource Type | What It Provides | Where to Find It |
| ----------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Playbooks** | Step-by-step implementation guides for common dev tasks | [Playbooks Hub](./playbooks/) |
| **Standards** | Coding conventions, patterns, and best practices | [Standards Hub](./standards/README.md) |
| **Architecture** | Feature architecture reviews and migration plans | [Access Intelligence Architecture](./access-intelligence/architecture/) |
| **Integration Guides** | How services and components work together | [Generic Guide](./integration-guide.md), [Access Intelligence](./access-intelligence/service-component-integration.md) |
| **Documentation Guide** | How docs are organized and where to find things | [Documentation Structure](./documentation-structure.md) |
### Standards by Area
| Area | Standard Document |
| ---------------------- | -------------------------------------------------------------------------- |
| **General Coding** | [Standards Hub](./standards/README.md) |
| **Services** | [Service Standards](./standards/service-standards.md) |
| **Domain Models** | [Model Standards](./standards/model-standards.md) |
| **Service Testing** | [Service Testing Standards](./standards/testing-standards-services.md) |
| **Angular Components** | [Angular Standards](./standards/angular-standards.md) |
| **Component Testing** | [Component Testing Standards](./standards/testing-standards-components.md) |
| **RxJS Patterns** | [RxJS Standards](./standards/rxjs-standards.md) |
| **Code Organization** | [Code Organization Standards](./standards/code-organization-standards.md) |
| **Documentation** | [Documentation Standards](./standards/documentation-standards.md) |
### Playbooks by Task
| Task | Playbook |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| **Implement or refactor a service** | [Service Implementation Playbook](./playbooks/service-implementation-playbook.md) |
| **Migrate or create a UI component** | [Component Migration Playbook](./playbooks/component-migration-playbook.md) |
| **Create or update documentation** | [Documentation Playbook](./playbooks/documentation-playbook.md) |
| **Browse all playbooks** | [Playbooks Hub](./playbooks/) |
---
## 🚀 Quick Reference by Task
| What are you working on? | Start here |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Services** (implementation, architecture, testing) | [Service Playbook](./playbooks/service-implementation-playbook.md) + [Service Standards](./standards/service-standards.md) |
| **Domain Models** (view models, query methods) | [Service Playbook](./playbooks/service-implementation-playbook.md) + [Model Standards](./standards/model-standards.md) |
| **UI Components** (Angular, migration, testing) | [Component Playbook](./playbooks/component-migration-playbook.md) + [Angular Standards](./standards/angular-standards.md) |
| **Storybook** (create or update stories) | [Component Playbook](./playbooks/component-migration-playbook.md) + [Component Testing Standards § Storybook](./standards/testing-standards-components.md#storybook-as-living-documentation) |
| **Component Tests** (Jest, OnPush, Signals) | [Component Playbook](./playbooks/component-migration-playbook.md) + [Component Testing Standards](./standards/testing-standards-components.md) |
| **Service Tests** (mocks, observables, RxJS) | [Service Playbook](./playbooks/service-implementation-playbook.md) + [Service Testing Standards](./standards/testing-standards-services.md) |
| **Documentation** (create, update, organize) | [Documentation Playbook](./playbooks/documentation-playbook.md) + [Documentation Standards](./standards/documentation-standards.md) |
| **Architecture Review** (feature planning) | [Access Intelligence Architecture](./access-intelligence/architecture/) |
| **Feature Architecture Decisions** | Document in [docs/[feature]/architecture/](./documentation-structure.md#feature-level-documentation) (decisions tracked in Confluence) |
---
## 🆘 Need Help?
**Can't find what you're looking for?**
- **Understand how docs are organized:** See [Documentation Structure](./documentation-structure.md)
- **Browse all team documentation:** See [Team Docs README](./README.md)
- **Component-specific docs:** See [Component Docs](/bitwarden_license/bit-web/src/app/dirt/access-intelligence/docs/README.md)
---
**Document Version:** 1.0
**Last Updated:** 2026-02-17
**Maintainer:** DIRT Team

378
bitwarden_license/bit-common/src/dirt/docs/integration-guide.md Normal file
View File

@@ -0,0 +1,378 @@
# Service ↔ Component Integration Guide
**Purpose:** Coordination guide for features that span both platform-agnostic services (bit-common) and Angular UI components (bit-web/bit-browser)
**Scope:** This guide applies to **any DIRT feature** requiring work in both service and component layers. For feature-specific integration patterns and detailed examples, see the feature's documentation:
- [Access Intelligence Integration](/bitwarden_license/bit-common/src/dirt/docs/access-intelligence/service-component-integration.md)
**Focus:** This document focuses on **coordination and handoffs** between service and component developers. For code patterns and standards, see [Standards Documentation](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md).
---
## 📋 When You Need Both
Many DIRT features require coordinated work across service AND component layers:
| Feature Type | Service Work | Component Work |
| -------------------------- | ----------------------------- | --------------------------------- |
| **New report/data type** | Generate, persist, load data | Display data, filters, navigation |
| **New data visualization** | Aggregate/query data | Charts, cards, tables |
| **User actions** | Business logic on models | UI interactions, forms |
| **Settings/preferences** | Persist settings | Settings UI |
| **Integrations** | API communication, sync logic | Configuration UI, status display |
---
## 🔄 Integration Pattern
```
┌─────────────────────────────────────────────────┐
│ Component (bit-web/bit-browser) │
│ - User interactions │
│ - Display logic │
│ - Converts Observables → Signals (toSignal()) │
│ - OnPush + Signal inputs/outputs │
├─────────────────────────────────────────────────┤
│ Data Service (Feature-specific) │
│ - Exposes Observable streams │
│ - Coordinates feature data │
│ - Delegates business logic to models │
│ - Delegates persistence to services │
├─────────────────────────────────────────────────┤
│ Domain Services (bit-common) │
│ - Business logic orchestration │
│ - Pure transformation │
│ - Platform-agnostic │
├─────────────────────────────────────────────────┤
│ View Models │
│ - Smart models (CipherView pattern) │
│ - Query methods: getData(), filter(), etc. │
│ - Mutation methods: update(), delete(), etc. │
└─────────────────────────────────────────────────┘
```
**Key principle:** Services do the work, components coordinate the UI. Business logic lives in view models, not components.
---
## 🔀 Service → Component Handoff
**When:** Service implementation is complete, ready for UI integration
### Readiness Checklist
Before handing off to component developer, ensure:
- [ ] **Service is complete and tested**
- [ ] Abstract defined with JSDoc
- [ ] Implementation complete
- [ ] Tests passing (`npm run test`)
- [ ] Types validated (`npm run test:types`)
- [ ] **View models have required methods**
- [ ] Query methods for component data needs (documented)
- [ ] Mutation methods for user actions (documented)
- [ ] Methods follow naming conventions
- [ ] **Data service exposes observables**
- [ ] Observable(s) are public and documented
- [ ] Observable emits correct view models
- [ ] Observable handles errors gracefully
- [ ] **Component requirements documented**
- [ ] What data the component needs
- [ ] What user actions the component handles
- [ ] What the component should display
- [ ] Any performance considerations
### Handoff Communication Template
When handing off to component developer, provide:
1. **What service to inject**
- Example: `FeatureDataService`
2. **What observable(s) to use**
- Example: `data$: Observable<FeatureView | null>`
- Type signature and nullability
3. **What model methods are available**
- Query methods: `feature.getData()`, `feature.filter(criteria)`
- Mutation methods: `feature.update(data)`, `feature.delete(id)`
- Link to model documentation or JSDoc
4. **How to integrate in component**
- Reference [Standards: Observable to Signal Conversion](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
- Basic pattern: inject service → convert observable to signal → use in template
5. **Any gotchas or special considerations**
- Performance notes (large datasets, expensive operations)
- Error handling requirements
- Special states (loading, empty, error)
### Communication Methods
- **Slack:** Quick handoff for simple integrations
- **Jira comment:** Document handoff details on feature ticket
- **Documentation:** Update feature docs with integration examples
- **Pair session:** For complex integrations, schedule pairing
---
## 🔀 Component → Service Handoff
**When:** Component needs new data/functionality not yet available in services
### Discovery Checklist
Before creating a service request, identify:
- [ ] **What's missing**
- [ ] New query method needed on view model?
- [ ] New mutation method needed on view model?
- [ ] New service needed entirely?
- [ ] New data needs to be loaded/persisted?
- [ ] **Document the requirement clearly**
- [ ] What data the component needs (shape, type)
- [ ] What format the data should be in
- [ ] What user action triggers this need
- [ ] Performance requirements (dataset size, frequency)
- [ ] **Assess scope**
- [ ] Is this a new method on existing model? (small change)
- [ ] Is this a new service? (medium-large change)
- [ ] Does this require API changes? (involves backend team)
- [ ] **File appropriate ticket**
- [ ] Link to component/feature that needs it
- [ ] Link to design/mockup if applicable
- [ ] Tag service developer or tech lead
### Handoff Communication Template
When requesting service work, provide:
1. **What the component needs**
- Clear description: "Component needs list of filtered items based on user criteria"
2. **Proposed API (if you have one)**
- Example: `model.getFilteredItems(criteria): Item[]`
- This is negotiable, service developer may suggest better approach
3. **Why (user story/context)**
- Example: "User clicks 'Show only critical' filter, UI should update to show subset"
4. **Data format expected**
- Example: "Array of `{ id: string, name: string, isCritical: boolean }`"
- Or reference existing model type if reusing
5. **Performance/scale considerations**
- Example: "Could be 1000+ items for large organizations"
- Helps service developer optimize
6. **Timeline/priority**
- Is this blocking component work?
- Can component proceed with stub/mock for now?
### Communication Methods
- **Jira ticket:** For non-trivial work requiring tracking
- **Slack:** For quick questions or small additions
- **Planning session:** For large features requiring design discussion
- **ADR:** If architectural decision needed
---
## 🤝 Collaboration Patterns
### Pattern 1: Parallel Development
**When to use:** Service and component work can be developed simultaneously
**How:**
1. Service developer creates interface/abstract first
2. Component developer uses interface with mock data
3. Both develop in parallel
4. Integration happens at the end
**Benefits:** Faster delivery, clear contracts
### Pattern 2: Sequential Development (Service First)
**When to use:** Component needs complete service implementation
**How:**
1. Service developer implements fully
2. Service developer documents integration
3. Component developer integrates
4. Component developer provides feedback
**Benefits:** Fewer integration issues, clearer requirements
### Pattern 3: Sequential Development (Component First)
**When to use:** UI/UX needs to be proven before service investment
**How:**
1. Component developer builds with mock data
2. Component developer documents data needs
3. Service developer implements to match needs
4. Integration and refinement
**Benefits:** User-driven design, avoids unused service work
### Pattern 4: Paired Development
**When to use:** Complex integration, unclear requirements, new patterns
**How:**
1. Service and component developer pair on design
2. Develop together or in short iterations
3. Continuous feedback and adjustment
**Benefits:** Fastest problem solving, shared understanding
---
## 🧪 Testing Integration Points
### Service Layer Testing
**Service developers should test:**
- Services return correct view models
- Observables emit expected data
- Error handling works correctly
- Performance is acceptable for expected dataset sizes
**Reference:** [Service Implementation Playbook - Testing](/bitwarden_license/bit-common/src/dirt/docs/playbooks/service-implementation-playbook.md)
### Component Layer Testing
**Component developers should test:**
- Services are correctly injected
- Observables are correctly converted to signals
- View model methods are called appropriately
- Data is displayed correctly
- User interactions trigger correct model methods
**Reference:** [Component Migration Playbook - Testing](/bitwarden_license/bit-common/src/dirt/docs/playbooks/component-migration-playbook.md)
### Integration Testing
**Both should coordinate on:**
- Full user flows work end-to-end
- Data flows correctly from service → component
- UI updates when data changes
- Error states are handled gracefully
---
## 🚨 Common Integration Pitfalls
### 1. Component Bypasses Data Service
**Problem:** Component directly calls API services or persistence layers
**Why it's bad:** Breaks abstraction, duplicates logic, harder to test
**Solution:** Always go through feature's data service layer
**Reference:** [Standards: Service Layer Pattern](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
### 2. Service Returns Plain Objects
**Problem:** Service returns `{ ... }` instead of view model instances
**Why it's bad:** Loses model methods, breaks encapsulation, business logic leaks to components
**Solution:** Always return view model instances with query/mutation methods
**Reference:** [Standards: View Models](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
### 3. Business Logic in Components
**Problem:** Component implements filtering, calculations, state changes
**Why it's bad:** Logic not reusable, harder to test, violates separation of concerns
**Solution:** Business logic belongs in view models or domain services
**Reference:** [Standards: Component Responsibilities](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
### 4. Manual Observable Subscriptions
**Problem:** Component uses `.subscribe()` instead of `toSignal()`
**Why it's bad:** Memory leaks, manual cleanup needed, doesn't leverage Angular signals
**Solution:** Use `toSignal()` for automatic cleanup and signal integration
**Reference:** [Standards: Observable to Signal Conversion](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
### 5. Unclear Handoff
**Problem:** Service developer finishes work but doesn't communicate to component developer
**Why it's bad:** Delays integration, component developer doesn't know work is ready
**Solution:** Use handoff communication templates above, update Jira tickets, notify in Slack
---
## 📞 Who to Contact
### Service Questions
- Check: [Service Implementation Playbook](/bitwarden_license/bit-common/src/dirt/docs/playbooks/service-implementation-playbook.md)
- Check: [Standards](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
- Ask: DIRT team service developers
### Component Questions
- Check: [Component Migration Playbook](/bitwarden_license/bit-common/src/dirt/docs/playbooks/component-migration-playbook.md)
- Check: [Standards](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
- Ask: DIRT team component developers
### Architecture Questions
- Check: [Architecture Docs](/bitwarden_license/bit-common/src/dirt/docs/access-intelligence/architecture/)
- Check: [Getting Started](/bitwarden_license/bit-common/src/dirt/docs/getting-started.md)
- Ask: DIRT team tech lead
### Coordination/Process Questions
- Ask: DIRT team lead or scrum master
---
## 📚 Related Documentation
### General Guides
- [Getting Started](/bitwarden_license/bit-common/src/dirt/docs/getting-started.md)
- [Standards](/bitwarden_license/bit-common/src/dirt/docs/standards/standards.md)
- [Documentation Structure](/bitwarden_license/bit-common/src/dirt/docs/documentation-structure.md)
### Implementation Playbooks
- [Service Implementation Playbook](/bitwarden_license/bit-common/src/dirt/docs/playbooks/service-implementation-playbook.md)
- [Component Migration Playbook](/bitwarden_license/bit-common/src/dirt/docs/playbooks/component-migration-playbook.md)
### Feature-Specific Integration Guides
- [Access Intelligence Integration](/bitwarden_license/bit-common/src/dirt/docs/access-intelligence/service-component-integration.md)
---
**Document Version:** 1.0
**Last Updated:** 2026-02-17
**Maintainer:** DIRT Team