Skip to main content

Research Documentation

This directory contains research, analysis, and strategic insights generated during the development and improvement of Teams for Linux.

Research Context

These documents capture in-depth analysis and strategic insights that inform development decisions and provide context for major features.

Contents​

Authentication & Security​

Testing & Development​

  • Automated Testing Strategy - Testing frameworks for Electron apps with MS authentication constraints
    • Playwright for E2E, Vitest for unit/integration
    • Key learning: MS authentication makes automated testing complex

Electron & Framework​

  • Electron 38 Migration Analysis - Analysis of Electron 37 → 38 upgrade
  • useSystemPicker Investigation - ✅ Moved to ADR 008 - Electron 38's native screen picker rejected due to incomplete Linux Wayland support

Architecture​

Notification System Research​

  • Custom Notification System Research - Comprehensive investigation into alternative notification modal system
    • Investigation of existing libraries and solutions
    • Architectural constraints analysis (Electron wrapper vs React app)
    • Custom BrowserWindow-based implementation plan
    • Decision: Build custom system following IncomingCallToast pattern
    • Timeline: ~1 week for ultra-minimal MVP (toast notifications only)

MQTT & Integration​

Purpose​

These documents capture:

  • Strategic insights that inform development decisions
  • Comprehensive analysis that might not fit in traditional documentation
  • Research findings that provide objective evaluation of project components
  • Context and rationale for major feature decisions
  • Investigation results for proposed features and technologies

Target Audience​

These research documents are intended for:

  • Project maintainers making strategic decisions
  • Contributors understanding the broader context of features
  • Future developers needing historical context
  • Documentation of the decision-making process for major features

Maintenance Guidelines​

Document Lifecycle​

Research documents follow this lifecycle:

  1. Active Research Phase: Document findings, analysis, and recommendations
  2. Decision Phase: Use research to inform final decisions (implemented or rejected)
  3. Archive Phase: Move content to appropriate location after decision:
    • Implemented features: Compress findings into feature documentation, update architecture docs
    • Rejected features: Create/update ADR with concise decision record (e.g., ADR 008)
    • Superseded research: Close with reference to superseding document
  4. History: Git commit history preserves full investigation context

Maintenance Guidelines​

Research documents that are in active research phase should be:

  • Updated when significant changes affect the analysis
  • Referenced in PRDs and major feature discussions
  • Used to inform future project direction decisions

Archiving Research​

Once a decision is made (feature implemented or rejected):

  • DO: Move content to appropriate permanent location (ADR, feature docs, architecture guide)
  • DO: Compress findings into concise decision format
  • DO: Remove from active research navigation if no longer relevant
  • DO NOT: Keep full research documents as "historical context"—use git for history

Examples:

  • useSystemPicker investigation → ADR 008 (rejected decision)
  • Automated testing strategy → Preserved as research (informs future implementation decisions)
  • Architecture modernization → Marked as archived with cross-reference to current approach

Contributing Research​

When adding new research documents:

  1. Follow naming convention: Use descriptive, kebab-case filenames
  2. Include context: Date, scope, and purpose of analysis
  3. Link related documents: Cross-reference relevant files
  4. Update this index: Add entries for new research documents
  5. Provide actionable outcomes: Include clear recommendations or decisions

Document Template​

Research documents should include:

  • Status - Current state (Research Complete, Ongoing, Superseded)
  • Date - When the research was conducted
  • Summary - Executive summary of findings
  • Analysis - Detailed investigation and findings
  • Decision/Recommendation - Clear outcome or next steps
  • References - External sources and related documentation