[Research]: architecture modernization approaches (#1936)

* docs: comprehensive architecture modernization research and critique

Analyzes why the Oct 2025 DDD+Plugin architecture plan was never implemented.

Key findings:
- 374 lines (49%) of index.js extractable with minimal risk
- DDD+Plugin approach over-engineered for actual problems
- Recommends incremental refactoring instead

Includes 3 research documents:
1. ARCHITECTURE_RESEARCH_SUMMARY.md - Executive summary
2. ARCHITECTURE_MODERNIZATION_CRITICAL_ANALYSIS.md - Detailed analysis
3. INCREMENTAL_REFACTORING_PLAN.md - Practical alternative

Related to: #1799

* docs: add incremental refactoring plan and archive DDD+Plugin approach

Adds new active architecture plan to replace the archived DDD+Plugin research.

Changes:
1. NEW: incremental-refactoring-plan.md - Active plan for #1799
   - 4-8 week incremental extraction approach
   - Reduces index.js by 49% (755 → 381 lines)
   - Low risk, continuous value delivery
   - Week-by-week implementation guide

2. UPDATED: architecture-modernization-research.md - Marked as archived
   - Added deprecation notice at top
   - Explains why plan was not adopted (too complex)
   - Points to new incremental plan
   - Preserved as reference and historical context

3. UPDATED: research/README.md - Added Architecture & Refactoring section
   - Links to active incremental plan
   - Links to archived DDD+Plugin research
   - Clear status indicators (ACTIVE vs ARCHIVED)

4. UPDATED: sidebars.ts - Added Architecture & Refactoring category
   - Incremental plan listed first (active)
   - Archived research listed second

Related to: #1799

* docs: remove redundant root-level architecture docs

All information consolidated into docs-site documentation:
- Removed INCREMENTAL_REFACTORING_PLAN.md (duplicate of docs-site version)
- Removed ARCHITECTURE_RESEARCH_SUMMARY.md (summary in incremental plan)
- Removed ARCHITECTURE_MODERNIZATION_CRITICAL_ANALYSIS.md (critique in archive notice)

Updated archive notice to inline key reasons instead of referencing deleted file.

Single source of truth: docs-site/docs/development/research/

* fix: resolve MDX compilation error in incremental refactoring plan

MDX interprets '<' followed by numbers as invalid HTML tags.

Changes:
- '<400 lines' → 'less than 400 lines'
- '<50' → 'less than 50'

This is the same issue that was fixed in the original architecture research doc.

* docs: update issue references - #1799 is closed

Issue #1799 was for the DDD+Plugin approach and is now closed.

Changes:
- incremental-refactoring-plan.md: Changed 'Issue' to 'Supersedes' with note
- architecture-modernization-research.md: Added '(Closed)' to issue reference
- README.md: Changed 'Adopted approach for #1799' to 'Supersedes closed #1799'

The incremental plan addresses the same architectural concerns but with
a different, lower-risk approach.

* docs: remove broken references to deleted analysis files

Removed links to:
- ARCHITECTURE_MODERNIZATION_CRITICAL_ANALYSIS.md (deleted)
- ARCHITECTURE_RESEARCH_SUMMARY.md (deleted)

The archived architecture document already contains the critique in its
deprecation notice, so the references are no longer needed.

* docs: add architecture modernization research to appdata.xml

Added entry documenting the comprehensive architecture research completed
for v2.6.13 release, noting the incremental refactoring approach that
supersedes the DDD+Plugin plan (#1799).

---------

Co-authored-by: Claude <[email protected]>

Author: IsmaelMartinez

com.github.IsmaelMartinez.teams_for_linux.appdata.xml

@@ -21,6 +21,7 @@
 					<li>Refactor: Remove excessive comments from feature flag handling functions for improved code clarity</li>
 					<li>Feature: Add automated PR binary artifact uploads for all platforms - contributors and testers can now download pre-built packages directly from GitHub Actions to test PR changes without building from source (closes #1940)</li>
 					<li>Documentation: Streamline CONTRIBUTING.md to be a quick reference guide with links to comprehensive Docusaurus documentation</li>
+					<li>Research: Complete architecture modernization analysis - comprehensive research revealing that the codebase is well-structured with 49% of index.js extractable through low-risk incremental refactoring instead of large-scale architectural overhaul (supersedes #1799 DDD+Plugin approach)</li>
 				</ul>
 			</description>
 		</release>

docs-site/docs/development/research/README.md

@@ -31,6 +31,18 @@ These documents capture in-depth analysis and strategic insights that inform dev
 - **[Documentation Health Analysis](documentation-health-analysis.md)** - Comprehensive assessment of documentation structure, quality, and maintainability
 - **[UI System Strategic Analysis](ui-system-strategic-analysis.md)** - Strategic evaluation of the in-app UI system proposal and its alignment with project goals
 
+### Architecture & Refactoring
+- **[Incremental Refactoring Plan](incremental-refactoring-plan.md)** ⭐ **ACTIVE PLAN** - Practical 4-8 week plan to modernize architecture through incremental extraction
+  - Reduces index.js by 49% (755 → 381 lines)
+  - Low risk, continuous value delivery
+  - Adds 20+ automated tests
+  - Supersedes closed #1799 (DDD+Plugin approach)
+- **[Architecture Modernization Research (DDD+Plugin)](architecture-modernization-research.md)** - 🗄️ **ARCHIVED** - Comprehensive DDD+Plugin research deemed too complex
+  - Preserved as reference and historical context
+  - 10-week big-bang migration plan
+  - Excellent research but over-engineered for actual needs
+  - See Critical Analysis for why this was not adopted
+
 ## Purpose
 
 These documents capture:

docs-site/docs/development/research/architecture-modernization-research.md

@@ -1,8 +1,25 @@
-# Architecture Modernization Research
+# Architecture Modernization Research (DDD+Plugin Approach)
 
-**Issue**: [#1799 - Architecture Modernization](https://github.com/IsmaelMartinez/teams-for-linux/issues/1799)
+:::danger ARCHIVED - PLAN NOT ADOPTED
+**Status**: Archived - Research complete but plan deemed too complex
+
+**Date Created**: 2025-10-30
+**Date Archived**: 2025-11-08
+
+**Reason**: After critical analysis, this DDD+Plugin approach was determined to be over-engineered for the actual problems in the codebase:
+- 10-week big-bang migration of all 35 modules (too risky)
+- 8+ new abstractions introduced (PluginManager, EventBus, etc.)
+- Over-engineered for actual pain points (374 lines extractable with minimal risk)
+- Implementation paralysis (plan so big, nothing was started)
+
+**See instead**: [Incremental Refactoring Plan](./incremental-refactoring-plan.md) - The adopted approach that delivers 49% reduction in index.js with lower risk through incremental extraction (4-8 weeks vs 10 weeks, continuous delivery vs all-or-nothing).
+
+This document is preserved as reference and for historical context.
+:::
+
+**Issue**: [#1799 - Architecture Modernization](https://github.com/IsmaelMartinez/teams-for-linux/issues/1799) (Closed)
 **Created**: 2025-10-30
-**Status**: Research Phase
+**Status**: ~~Research Phase~~ **ARCHIVED**
 
 ## Executive Summary