# andreagriffiths11/teamxray architecture

> Architecture diagram of the GitHub repository andreagriffiths11/teamxray, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andreagriffiths11/teamxray
- Repository: https://github.com/andreagriffiths11/teamxray

## Overview

##### Project type and purpose
- This is a VS Code extension (“Team X-Ray”) written in TypeScript that augments GitHub Copilot with team expertise insights.
- It lives in the VS Code Extension Host, provides commands (right-click file, command-palette), spins up a Webview UI, performs Git analysis, and calls GitHub’s Model Context Protocol (MCP) or falls back to local Git.

##### File structure
- Top-level:
- package.json, tsconfig.json, webpack.config.js → build & package config
- src/extension.ts → VS Code activation & command registration
- src/core/… → service classes (copilot-mcp-service, expertise-analyzer, tree-provider, webview, token-manager)
- src/types → domain types (Expert)
- Build: webpack bundles into the .vsix
- Config: .github/workflows → CI/CD pipeline

##### README insights
- Calls out:
- Real Git Analysis (commit history parsing)
- AI Analysis via GitHub Models API (MCP)
- Offline fallback to local Git
- Modern Webview UI for results

##### Main components & relationships
a. VS Code Extension Host
– extension.ts registers commands & lifecycle hooks
b. Command & Language Integration
– Command in context menu / command-palette triggers core services
c. Core Services Layer
– TokenManager loads GITHUB_TOKEN
– GitAnalysis (in expertise-analyzer) parses commit history via child_process or Git lib
– CopilotMCPService wraps calls to GitHub’s Models API over the MCP protocol
– Fallback logic detects MCP availability and switches to local analysis
d. UI Layer (Webview)
– ExpertiseWebview builds/updates the HTML + JS UI
– TreeProvider exposes an explorer view of expertise hierarchy
e. External Systems
– Local Git binary & repo on disk
– GitHub MCP server (GPT-4o) via Model Context Protocol

##### Architectural patterns & design principles
- Modular service classes (single responsibility per file in src/core)
- Asynchronous event-driven flow (VS Code commands → Promises → Webview updates)
- Dependency injection of TokenManager into CopilotMCPService & Analyzer
- Fallback strategy pattern for online vs offline

##### Technologies & frameworks
- TypeScript + Node.js 20+
- VS Code Extension API
- Git CLI or Node Git library
- GitHub Model Context Protocol (MCP) client
- Webview API for UI
- Webpack for bundling extension

– VS Code Host (left side)
– Core Services (center)
– External Systems (right side)
1. User triggers command → extension.ts
2. extension.ts calls TokenManager → GitAnalysis → CopilotMCPService
3. CopilotMCPService ↔ MCP Server (GPT-4o)
4. If MCP fails → GitAnalysis offline path
5. Results passed to ExpertiseWebview & TreeProvider
6. Webview UI renders insights back to user
– Green for external dependencies (Git, MCP Server)
– Yellow for UI components (Webview, TreeProvider)
d. Labels & annotations:

##### Essential elements
- Component boundaries (VS Code Extension Host vs external systems)
- Clear labels on modules, protocols, and data payloads

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VS Code Extension Host Layer
    subgraph "VS Code Extension Host" 
        direction TB
        EXT["extension.ts\n(Activation & Command Registration)"]:::extensionHost
    end

    %% Core Services Layer
    subgraph "Core Services" 
        direction TB
        TM["TokenManager\n(loads GITHUB_TOKEN)"]:::services
        GA["Git Analysis Service\n(commit history parsing)"]:::services
        CPS["Copilot MCP Service\n(calls GitHub Models API)"]:::services
    end

    %% UI Layer
    subgraph "UI Components" 
        direction TB
        EW["Expertise Webview UI"]:::ui
        TP["Expertise Tree Provider"]:::ui
    end

    %% Domain Types
    DT["Expert Domain Types"]:::types

    %% External Systems
    subgraph "External Systems"
        direction TB
        MG["GitHub MCP Server\n(Model Context Protocol)"]:::external
        LG["Local Git Repo\n(Git CLI/Node Git)"]:::external
    end

    %% Config & CI/CD
    subgraph "Configuration & CI/CD"
        direction TB
        CFG1["webpack.config.js"]:::config
        CFG2["tsconfig.json"]:::config
        CFG3["package.json"]:::config
        CI1[".github/workflows/ci-cd.yml"]:::config
        CI2[".github/workflows/marketplace-prep.yml"]:::config
        CI3[".github/workflows/pr-check.yml"]:::config
    end

    %% Data Flows
    EXT -->|"trigger command"| TM
    TM -->|"provides token"| GA
    GA -->|"commit history"| CPS
    CPS -->|"model prompt"| MG
    MG -->|"expertise JSON"| CPS
    CPS -->|"analysis result"| EW
    CPS -->|"analysis result"| TP

    %% Fallback Path
    GA -.->|"fallback"| LG
    LG -->|"commit history"| GA

    GA -->|"analysis result"| EW
    GA -->|"analysis result"| TP

    %% Domain Types dependency
    DT --> GA
    DT --> CPS
    DT --> EW
    DT --> TP

    %% Configuration dependencies
    CFG1 --> EXT
    CFG2 --> EXT
    CFG3 --> EXT

    %% CI/CD dependency
    CI1 --> CFG3
    CI2 --> CFG3
    CI3 --> CFG3

    %% Click Events
    click EXT "https://github.com/andreagriffiths11/teamxray/blob/main/src/extension.ts"
    click TM "https://github.com/andreagriffiths11/teamxray/blob/main/src/core/token-manager.ts"
    click GA "https://github.com/andreagriffiths11/teamxray/blob/main/src/core/expertise-analyzer.ts"
    click CPS "https://github.com/andreagriffiths11/teamxray/blob/main/src/core/copilot-mcp-service.ts"
    click EW "https://github.com/andreagriffiths11/teamxray/blob/main/src/core/expertise-webview.ts"
    click TP "https://github.com/andreagriffiths11/teamxray/blob/main/src/core/expertise-tree-provider.ts"
    click DT "https://github.com/andreagriffiths11/teamxray/blob/main/src/types/expert.ts"
    click CFG1 "https://github.com/andreagriffiths11/teamxray/blob/main/webpack.config.js"
    click CFG2 "https://github.com/andreagriffiths11/teamxray/blob/main/tsconfig.json"
    click CFG3 "https://github.com/andreagriffiths11/teamxray/blob/main/package.json"
    click CI1 "https://github.com/andreagriffiths11/teamxray/blob/main/.github/workflows/ci-cd.yml"
    click CI2 "https://github.com/andreagriffiths11/teamxray/blob/main/.github/workflows/marketplace-prep.yml"
    click CI3 "https://github.com/andreagriffiths11/teamxray/blob/main/.github/workflows/pr-check.yml"

    %% Styles
    classDef extensionHost fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef services fill:#CCE5FF,stroke:#004085,color:#004085;
    classDef ui fill:#FFF5CC,stroke:#856404,color:#856404;
    classDef external fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef config fill:#E0E0E0,stroke:#6c757d,color:#343a40,font-style:italic;
    classDef types fill:#FFF0F5,stroke:#D63384,color:#D63384;
```
