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​

  • DOM Access Investigation - Research on DOM access requirements and React breaking changes
  • Logout Indicator Investigation - Comprehensive research on tray icon logout indicator feature (#1987)
    • Multi-signal authentication detection strategy
    • Visual indicator and notification implementation plan
    • Critical technical validation spikes required before implementation
    • Estimated effort: 38-60 hours with technical validation
  • External Browser Authentication Investigation - Investigation into enabling Microsoft Teams authentication in system browser (Issue #2017)
    • Comprehensive analysis of current authentication architecture
    • Research on external browser OAuth patterns in Electron apps
    • Feasibility assessment and technical challenges
    • Conclusion: Not currently feasible - Teams web app manages authentication internally without exposed APIs
    • Clarification: ssoBasicAuthPasswordCommand is only for proxy/network auth, not Teams login
  • For implemented solutions, see ADR-002: Token Cache and ADR-003: Token Refresh

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

Strategic Analysis​

  • Configuration Organization Research - Analysis of configuration system organization and proposed improvements
    • ✅ Phase 1 Complete: Documentation reorganization
    • Three-phase migration plan from flat to nested structure
    • Phases 2-3: Nested structure with auto-migration (planned)

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​

Privacy & Media​

  • Screen Lock Media Privacy Investigation - Auto-disable camera/mic on screen lock (Issue #2015)
    • Linux-first philosophy: Expose commands for user scripts (D-Bus listeners, systemd hooks)
    • Electron powerMonitor limited on Linux; user-script approach recommended
    • Feasible via MQTT commands that users invoke from their own lock scripts

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