From 2af9396766a962b56705094bfeb2dd4e642295ea Mon Sep 17 00:00:00 2001 From: Leslie Tilton <23057410+Banrion@users.noreply.github.com> Date: Mon, 23 Feb 2026 08:47:16 -0600 Subject: [PATCH] Initial bitwarden team core docs (#19048) --- .../bit-common/src/dirt/docs/README.md | 73 ++++ .../src/dirt/docs/documentation-structure.md | 277 +++++++++++++ .../src/dirt/docs/getting-started.md | 96 +++++ .../src/dirt/docs/integration-guide.md | 378 ++++++++++++++++++ 4 files changed, 824 insertions(+) create mode 100644 bitwarden_license/bit-common/src/dirt/docs/README.md create mode 100644 bitwarden_license/bit-common/src/dirt/docs/documentation-structure.md create mode 100644 bitwarden_license/bit-common/src/dirt/docs/getting-started.md create mode 100644 bitwarden_license/bit-common/src/dirt/docs/integration-guide.md diff --git a/bitwarden_license/bit-common/src/dirt/docs/README.md b/bitwarden_license/bit-common/src/dirt/docs/README.md new file mode 100644 index 00000000000..f07f5c8b44c --- /dev/null +++ b/bitwarden_license/bit-common/src/dirt/docs/README.md @@ -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 diff --git a/bitwarden_license/bit-common/src/dirt/docs/documentation-structure.md b/bitwarden_license/bit-common/src/dirt/docs/documentation-structure.md new file mode 100644 index 00000000000..7d7e20b5d31 --- /dev/null +++ b/bitwarden_license/bit-common/src/dirt/docs/documentation-structure.md @@ -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 diff --git a/bitwarden_license/bit-common/src/dirt/docs/getting-started.md b/bitwarden_license/bit-common/src/dirt/docs/getting-started.md new file mode 100644 index 00000000000..0077019fe02 --- /dev/null +++ b/bitwarden_license/bit-common/src/dirt/docs/getting-started.md @@ -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 diff --git a/bitwarden_license/bit-common/src/dirt/docs/integration-guide.md b/bitwarden_license/bit-common/src/dirt/docs/integration-guide.md new file mode 100644 index 00000000000..0d7bf3db847 --- /dev/null +++ b/bitwarden_license/bit-common/src/dirt/docs/integration-guide.md @@ -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` + - 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