LazyBearWorks/memory-bank/systemPatterns.md

# System Patterns — Архитектура и паттерны

## 🏗️ Система архитектуры

```
┌─────────────────────────────────────────────────────────┐
│              HTTP Transport Layer                        │
│         ModelContextProtocol 1.2.0 HTTP                 │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│              Application Layer (TUI + MCP)               │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐│
│  │   RazorConsole │  │   McpWeb      │  │  ToolRegistry││
│  │     App.razor  │  │    Hosted     │  │      Service ││
│  └───────────────┘  └───────────────┘  └──────────────┘│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│              Services Layer (IToolModule)                │
│  ┌──────────┐ ┌───────────────┐ ┌────────────────────┐ ┌─────┐│
│  │JiraTools │ │ConfluenceTools│ │KubernetesTools     │ │Qdrant││
│  └──────────┘ └───────────────┘ └────────────────────┘ └─────┘│
│  └────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│              External API Layer                          │
│  ┌──────────┐ ┌───────────────┐ ┌────────────────────┐ ┌────┐│
│  │ Jira API │ │Confluence API │ │ K8s API            │ │Qdr│  │
│  └──────────┘ └───────────────┘ └────────────────────┘ └───┘  │
└─────────────────────────────────────────────────────────┘
```

## Ключевые архитектурные компоненты

### 1. HTTP Transport Layer

**File**: `LazyBear.MCP/Program.cs`

```csharp
var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        // MCP-провайдеры
        services.AddSingleton<K8sClientProvider>();
        services.AddSingleton<JiraClientProvider>();
        services.AddSingleton<ConfluenceClientProvider>();
        
        // Модули инструментов
        services.AddSingleton<IToolModule, JiraToolModule>();
        services.AddSingleton<IToolModule, KubernetesToolModule>();
        services.AddSingleton<IToolModule, ConfluenceToolModule>();
        
        // HTTP MCP endpoint в фоне
        services.AddHostedService<McpWebHostedService>();
    })
    .Build();
```

**Ответственность**: Регистрация HTTP MCP transport и инструментов

### 2. TUI Layer (RazorConsole)

**File**: `LazyBear.MCP/Program.cs` (RazorConsole конфиг)

```csharp
.host.UseRazorConsole<App>(hostBuilder =>
{
    hostBuilder.ConfigureServices(services =>
    {
        services.AddSingleton<TUI.Components.GlobalKeyboardService>();
        services.AddSingleton<LocalizationService>();
        // ... TUI сервисы
    });
});
```

**Ответственность**: Консольный интерфейс мониторинга K8s

### 3. Tool Registry Pattern

**File**: `LazyBear.MCP/Services/ToolRegistryService.cs` (предположительно)

```csharp
public class ToolRegistryService
{
    public void RegisterModule(IToolModule module)
    {
        // Регистрация модуля инструментов
        // Модуль появляется в TUI и MCP tools
    }
}
```

**Ответственность**: Централизованная регистрация инструментов

**Register в Program.cs**:
```csharp
var registry = host.Services.GetRequiredService<ToolRegistryService>();
foreach (var module in host.Services.GetServices<IToolModule>())
{
    registry.RegisterModule(module);
}
```

### 4. Client Provider Pattern

**Files**:
- `LazyBear.MCP/Services/Kubernetes/K8sClientProvider.cs`
- `LazyBear.MCP/Services/Jira/JiraClientProvider.cs`
- `LazyBear.MCP/Services/Confluence/ConfluenceClientProvider.cs`

```csharp
public class K8sClientProvider
{
    private readonly IConfiguration _config;
    
    public KubernetesClientFactory GetClientFactory()
    {
        // Fallback: explicit kubeconfig → default → in-cluster
        var kubeconfigPath = _config["Kubernetes:KubeconfigPath"]
            ?? Environment.GetEnvironmentVariable("KUBECONFIG")
            ?? string.Empty;
        
        return new KubernetesClientFactory(kubeconfigPath);
    }
}
```

**Ответственность**: Создание клиентов внешних API с fallback стратегией

## Паттерны взаимодействия

### Pattern 1: Initialize Flow

```
Клиент MCP
    ↓ [RPC: initialize]
MCP Transport
    ↓
Application (ToolRegistry)
    ↓
Tool Module (Jira/K8s/Confluence)
    ↓
External API (Jira API / K8s API)
    ↓
Ответ через MCP transport
```

### Pattern 2: Tools Flow

```
Клиент MCP
    ↓ [RPC: tool/name]
ToolRegistry.FindTool()
    ↓
ToolModule.Execute()
    ↓
External API
    ↓
Результат → MCP response
```

### Pattern 3: Health Check Flow

```
HTTP /health
    ↓
McpWebHostedService
    ↓
Лiveness probe статус
    ↓
JSON response
```

## DI Container Setup

```csharp
services.AddSingleton<...>(...)
    ↓
HostedService (McpWeb)
    ↓
RazorConsole (TUI)
    ↓
RunAsync()
```

**Примечание**: TUI запускается первым и владеет консолью, HTTP host работает параллельно в фоне.

## Критические пути реализации

### Путь 1: Создание Jira задачи

```
jiraTools/createIssue(params)
    ↓
JiraToolModule.Execute()
    ↓
JiraClientProvider.GetClient()
    ↓
Jira API REST
    ↓
Ответ с issue key
```

### Путь 2: Создание K8s Deployment

```
k8sDeploymentTools/createDeployment(params)
    ↓
KubernetesToolModule.Execute()
    ↓
K8sClientProvider.GetClientFactory().CreateClient()
    ↓
K8s API V1/Deployments
    ↓
Ответ с deployment name
```

### Путь 3: Мониторинг через TUI

```
RazorConsole Render()
    ↓
GetDeployments() → GetPods() → GetEvents()
    ↓
App.razor (RazorConsole)
    ↓
Console.Output
```

## Компонентные контракты

### IToolModule

```csharp
public interface IToolModule
{
    string Name { get; }
    Task<object> ExecuteAsync(IToolContext context, string toolName, object? arguments);
}
```

**Ответственность**: Определение одного модуля инструментов (Jira/Confluence/K8s)

### IToolContext

Контекст выполнения инструмента:
- MCP connection info
- Tool registry
- DI services
- Logging provider

### K8sClientFactory

```csharp
public class KubernetesClientFactory
{
    public KubernetesClient CreateClient(string? kubeconfigPath);
}
```

**Fallback порядок**:
1. Explicit kubeconfig path
2. Environment variable KUBECONFIG
3. In-cluster config (если внутри кластера)

## Logging Architecture

```
InMemoryLoggerProvider
    ↓
InMemoryLogSink
    ↓
Console.WriteLine
```

**Конфиг**:
```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "ModelContextProtocol": "Debug"
    }
  }
}
```

---

### Qdrant Client Provider Pattern

**File**: `LazyBear.MCP/Services/Qdrant/QdrantClientProvider.cs`

```csharp
public class QdrantClientProvider
{
    private readonly IConfiguration _config;
    
    public QdrantClient GetClient()
    {
        // Конфиг из appsettings.json
        var url = _config["Qdrant:Url"];
        var apiKey = _config["Qdrant:ApiKey"] ?? string.Empty;
        
        return new QdrantClient(url, apiKey);
    }
}
```

**Fallback порядок**:
1. Explicit URL из конфига
2. Environment variable QDRANT_URL
3. Localhost default

**Ответственность**: Создание клиентов Qdrant с поддержкой API ключа (опционально)

---

*Файл описывает систему архитектуры, ключевые компоненты и потоки данных. Обновлять при введении новых архитектурных решений.*