# lablab-deepai/gitguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/lablab-deepai/gitguard-ai
- Repository: https://github.com/lablab-deepai/gitguard-ai

## Overview

##### Project type and purpose
- GitGuard-AI is a hybrid monorepo containing two major modules:
a. A full-stack “landing_page” (Next.js frontend + Python backend) that hosts a marketing/demo UI and exposes secret-detection APIs.
b. A “trae-plugin” Python package that integrates with the Trae IDE via a Modular Command Platform (MCP) to run secret-detection logic in developers’ editors or CI pipelines.
- Its core purpose is secret detection in codebases, with both a user-facing web demo and a programmatic IDE/CLI plugin.

##### File structure
- Top level:
- landing_page/ (separate frontend and backend subfolders)
- trae-plugin/ (gitguard core, MCP commands, utils, tests)
- docs/ (documentation)
- landing_page/frontend: Next.js app with React components, Tailwind, API routes under app/api.
- landing_page/backend: Python microservice (detector.py, main.py) defined in a pyproject.toml.
- trae-plugin/gitguard: Python package with MCP integration (create_mcp.py, secret_detection_script.py) and detection utils (llm_detect.py, regex_detector.py).
- tests cover plugin use cases.

##### README for additional insights
- Confirms two modules, points to module-level READMEs for details.
- Landing-page frontend uses v0.dev, backend provides detection endpoints.
- Trae-plugin implements IDE commands and secret detection algorithms; extensible via MCP.

a. Main components:
1. Web Frontend (Next.js React app)
2. Web Backend (Python FastAPI/Flask-style microservice)
3. Secret-Detection Core Library (Python utils in trae-plugin/gitguard/utils)
4. Trae IDE Plugin (MCP commands + scripts in trae-plugin/gitguard/mcp)
5. External Services: LLM provider (if configured), Version Control System (Git), Hosting platform (Vercel or similar)
6. Documentation module (docs/)
b. Component interactions:
- End user’s browser ↔ Frontend UI ↔ Next.js API routes ↔ Backend HTTP endpoints ↔ Detector logic ↔ Core utils ↔ Returns JSON results.
- Developer’s IDE ↔ Trae runtime ↔ Trae-plugin MCP command ↔ Secret-detection scripts ↔ Core utils ↔ Optionally invoke LLM API ↔ Show inline warnings.
- CI pipeline can invoke the same plugin or backend API for batch scanning.
c. Architectural patterns & principles:
- Monorepo with clear module boundaries (landing_page vs. plugin).
- Backend-for-frontend pattern: Next.js API routes forward requests to Python microservice.
- Plugin architecture via MCP for extensibility.
- Core detection logic is decoupled from transport layers.
d. Key technologies & frameworks:
- Next.js, React, Tailwind CSS, Vercel/v0.dev (frontend)
- Python (landing_page/backend + trae-plugin), MCP (Modular Command Platform), pytest (tests)
- LLM integration (in llm_detect.py) and regex-based detection

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Landing Page Module
    subgraph "Landing Page Module"
        subgraph "Frontend (Next.js)" 
            direction TB
            UI["Browser UI<br/>(React + Tailwind)"]:::frontend
            API["API Routes<br/>(app/api)"]:::frontend
        end
        subgraph "Backend (Python Microservice)"
            direction TB
            Main["main.py"]:::backend
            Detector["detector.py"]:::backend
        end
    end

    %% Trae Plugin Module
    subgraph "Trae Plugin Module"
        direction TB
        subgraph "MCP Commands & Scripts"
            CreateMCP["create_mcp.py"]:::plugin
            Script["secret_detection_script.py"]:::plugin
            Init["__init__.py"]:::plugin
        end
    end

    %% Shared Core Logic
    subgraph "Secret-Detection Core Library"
        direction TB
        LLM["llm_detect.py"]:::core
        Regex["regex_detector.py"]:::core
    end

    %% Documentation
    subgraph "Documentation"
        RootReadme["README.md"]:::docs
        LPReadme["landing_page/README.md"]:::docs
        TPReadme["trae-plugin/README.md"]:::docs
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMService["LLM Provider"]:::external
        GitService["Version Control (Git)"]:::external
        Hosting["Hosting (Vercel/v0.dev)"]:::external
        CI["CI Pipeline"]:::external
        IDE["Developer IDE"]:::external
        Browser["End User Browser"]:::external
    end

    %% Connections: Landing Page
    Browser -->|"HTTP"| UI
    UI -->|"HTTP/JSON"| API
    API -->|"HTTP/JSON"| Main
    Main -->|"invokes"| Detector
    Detector -->|"calls"| LLM
    Detector -->|"calls"| Regex
    LLM -->|"REST API"| LLMService
    API -->|"deploys to"| Hosting

    %% Connections: Trae Plugin
    IDE -->|"MCP Runtime"| CreateMCP
    CreateMCP -->|"executes"| Script
    Script -->|"calls"| LLM
    Script -->|"calls"| Regex
    CI -->|"invokes"| Script
    GitService -->|"provides code"| Script

    %% Documentation Links
    RootReadme
    LPReadme
    TPReadme

    %% Click Events
    click UI "https://github.com/lablab-deepai/gitguard-ai/tree/main/landing_page/frontend/"
    click API "https://github.com/lablab-deepai/gitguard-ai/tree/main/landing_page/frontend/"
    click Main "https://github.com/lablab-deepai/gitguard-ai/blob/main/landing_page/backend/main.py"
    click Detector "https://github.com/lablab-deepai/gitguard-ai/blob/main/landing_page/backend/detector.py"
    click CreateMCP "https://github.com/lablab-deepai/gitguard-ai/blob/main/trae-plugin/gitguard/mcp/create_mcp.py"
    click Script "https://github.com/lablab-deepai/gitguard-ai/blob/main/trae-plugin/gitguard/mcp/secret_detection_script.py"
    click Init "https://github.com/lablab-deepai/gitguard-ai/blob/main/trae-plugin/gitguard/mcp/__init__.py"
    click LLM "https://github.com/lablab-deepai/gitguard-ai/blob/main/trae-plugin/gitguard/utils/llm_detect.py"
    click Regex "https://github.com/lablab-deepai/gitguard-ai/blob/main/trae-plugin/gitguard/utils/regex_detector.py"
    click RootReadme "https://github.com/lablab-deepai/gitguard-ai/blob/main/README.md"
    click LPReadme "https://github.com/lablab-deepai/gitguard-ai/blob/main/landing_page/README.md"
    click TPReadme "https://github.com/lablab-deepai/gitguard-ai/blob/main/trae-plugin/README.md"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef core fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef plugin fill:#D8BFD8,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef docs fill:#F5F5F5,stroke:#000,stroke-width:1px
```
