Development Documentation

This directory contains technical documentation for Teams for Linux developers and contributors.

Structure

Active Development Docs

• token-cache-architecture.md - Token cache implementation, secure storage architecture, and authentication persistence
• security-architecture.md - Security architecture, threat model, and compensating controls
• ADR-002: Token Cache Secure Storage - Architecture decision for secure token storage implementation
• ADR-003: Token Refresh Implementation - Architecture decision for authentication persistence
• module-index.md - Catalog of all application modules
• ADR Index - All architecture decision records
• Research Index - Feature research and investigations
• plan/roadmap.md - Development priorities and feature status

For Contributors

When working on Teams for Linux:

1. Review token cache architecture for authentication and secure storage patterns
2. Read the security architecture to understand security trade-offs and requirements
3. Review research documents in research/ for context on current implementation choices
4. Check ADR documents for architecture decisions and rationale
5. Check planning documents for background on feature decisions and research
6. Run npm run lint and npm run test:unit before submitting PRs; CI runs the Playwright e2e suite

Key Development Patterns

Token Cache Integration

When working with authentication-related features:

• Use the existing tokenCache singleton from app/browser/tools/tokenCache.js
• Follow the established async/await patterns for storage operations
• Implement graceful fallback mechanisms for storage failures
• Maintain PII-safe logging practices

Secure Storage Guidelines

• Prefer the unified token cache over direct localStorage access
• Let the system handle storage backend selection automatically
• Don't assume secure storage availability - always implement fallbacks
• Use the getStorageInfo() method for debugging and diagnostics

Documentation Standards

Follow the project's Markdown Standards in contributing.md, including:

• Use Docusaurus admonitions for callouts (:::note, :::tip, :::warning, :::danger, :::info)
• Include table of contents with <!-- toc -->
• Use proper markdown standards and syntax highlighting

Related Documentation

• Configuration Options - User-facing configuration documentation
• IPC API - Inter-process communication reference
• Contributing Guidelines - General contribution guidelines
• Architecture Decision Records - Technical decisions and rationale

Testing

Teams for Linux uses automated end-to-end testing with Playwright to ensure application stability and prevent regressions.

Running Tests

# Run the unit suite first (fast, run before every commit)
npm run test:unit

# Run all E2E tests locally; CI runs this suite automatically on PRs
npm run test:e2e

# Run in debug mode
npx playwright test --debug

Testing Strategy

The project uses a multi-layered testing approach:

• E2E Tests (Playwright): Full application testing with real Electron runtime
• Clean State Testing: Each test runs with isolated temporary userData directory
• Microsoft Authentication: Tests validate redirect to login without requiring credentials

For comprehensive testing documentation, see:

• Contributing Guide - Testing Section
• ADR-009: Automated Testing Strategy