docs: add architecture decision records (ADRs) for key technical choices

- Added the following ADRs to `docs/adrs/` directory:
  - ADR-001: MCP Integration Architecture
  - ADR-002: Real-time Communication Architecture
  - ADR-003: Background Task Architecture
  - ADR-004: LLM Provider Abstraction
  - ADR-005: Technology Stack Selection
- Each ADR details the context, decision drivers, considered options, final decisions, and implementation plans.
- Documentation aligns technical choices with architecture principles and system requirements for Syndarix.

docs/adrs/ADR-001-mcp-integration-architecture.md

@@ -0,0 +1,134 @@
+# ADR-001: MCP Integration Architecture
+
+**Status:** Accepted
+**Date:** 2025-12-29
+**Deciders:** Architecture Team
+**Related Spikes:** SPIKE-001
+
+---
+
+## Context
+
+Syndarix requires integration with multiple external services (LLM providers, Git, issue trackers, file systems, CI/CD). The Model Context Protocol (MCP) was identified as the standard for tool integration in AI applications. We need to decide on:
+
+1. The MCP framework to use
+2. Server deployment pattern (singleton vs per-project)
+3. Scoping mechanism for multi-project/multi-agent access
+
+## Decision Drivers
+
+- **Simplicity:** Minimize operational complexity
+- **Resource Efficiency:** Avoid spawning redundant processes
+- **Consistency:** Unified interface across all integrations
+- **Scalability:** Support 10+ concurrent projects
+- **Maintainability:** Easy to add new MCP servers
+
+## Considered Options
+
+### Option 1: Per-Project MCP Servers
+Spawn dedicated MCP server instances for each project.
+
+**Pros:**
+- Complete isolation between projects
+- Simple access control (project owns server)
+
+**Cons:**
+- Resource heavy (7 servers × N projects)
+- Complex orchestration
+- Difficult to share cross-project resources
+
+### Option 2: Unified Singleton MCP Servers (Selected)
+Single instance of each MCP server type, with explicit project/agent scoping.
+
+**Pros:**
+- Resource efficient (7 total servers)
+- Simpler deployment
+- Enables cross-project learning (if desired)
+- Consistent management
+
+**Cons:**
+- Requires explicit scoping in all tools
+- Shared state requires careful design
+
+### Option 3: Hybrid (MCP Proxy)
+Single proxy that routes to per-project backends.
+
+**Pros:**
+- Balance of isolation and efficiency
+
+**Cons:**
+- Added complexity
+- Routing overhead
+
+## Decision
+
+**Adopt Option 2: Unified Singleton MCP Servers with explicit scoping.**
+
+All MCP servers are deployed as singletons. Every tool accepts `project_id` and `agent_id` parameters for:
+- Access control validation
+- Audit logging
+- Context filtering
+
+## Implementation
+
+### MCP Server Registry
+
+| Server | Port | Purpose |
+|--------|------|---------|
+| LLM Gateway | 9001 | Route LLM requests with failover |
+| Git MCP | 9002 | Git operations across providers |
+| Knowledge Base MCP | 9003 | RAG and document search |
+| Issues MCP | 9004 | Issue tracking operations |
+| File System MCP | 9005 | Workspace file operations |
+| Code Analysis MCP | 9006 | Static analysis, linting |
+| CI/CD MCP | 9007 | Pipeline operations |
+
+### Framework Selection
+
+Use **FastMCP 2.0** for all MCP server implementations:
+- Decorator-based tool registration
+- Built-in async support
+- Compatible with SSE transport
+- Type-safe with Pydantic
+
+### Tool Signature Pattern
+
+```python
+@mcp.tool()
+def tool_name(
+    project_id: str,   # Required: project scope
+    agent_id: str,     # Required: calling agent
+    # ... tool-specific params
+) -> Result:
+    validate_access(agent_id, project_id)
+    log_tool_usage(agent_id, project_id, "tool_name")
+    # ... implementation
+```
+
+## Consequences
+
+### Positive
+- Single deployment per MCP type simplifies operations
+- Consistent interface across all tools
+- Easy to add monitoring/logging centrally
+- Cross-project analytics possible
+
+### Negative
+- All tools must include scoping parameters
+- Shared state requires careful design
+- Single point of failure per MCP type (mitigated by multiple instances)
+
+### Neutral
+- Requires MCP client manager in FastAPI backend
+- Authentication handled internally (service tokens for v1)
+
+## Compliance
+
+This decision aligns with:
+- FR-802: MCP-first architecture requirement
+- NFR-201: Horizontal scalability requirement
+- NFR-602: Centralized logging requirement
+
+---
+
+*This ADR supersedes any previous decisions regarding MCP architecture.*