# namgyu-youn/topicgen architecture

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

- Interactive diagram: https://gitdiagram.com/namgyu-youn/topicgen
- Repository: https://github.com/namgyu-youn/topicgen

## Overview

##### Main Components

a) User Interface Layer:
- Gradio Web Interface
- Input handling (GitHub URL)
- Category selection interface
- Results display

b) Core Processing Layer:
- GitHub Repository Analyzer
- Content Fetcher
- Zero-shot Classification System (DeBERTa-v3)
- Topic Generator

c) Infrastructure Layer:
- Docker Container
- Python Runtime Environment
- Error Handling System
- Logging System

##### Component Relationships and Data Flow

- User input → Gradio Interface → GitHub Analyzer
- GitHub Analyzer → Fetcher (for repository content)
- Fetcher → Content Processing → Zero-shot Classification
- Classification Results → Topic Generation → User Interface

##### Specific Implementation Details

Key technical elements:
- Python 3.12 Slim Docker container
- Gradio framework for UI
- Transformer models (DeBERTa-v3)
- Asynchronous operations (aiohttp)
- Poetry dependency management

##### Layering and Grouping

Create clear boundaries between:
- Frontend (Gradio interface)
- Backend services (analyzer, fetcher)
- ML components (zero-shot classification)
- Infrastructure (Docker, Python runtime)

##### Additional Elements

Supporting components:
- Error handling system (from error_handler.py)
- Logging system (from utils/logger.py)
- Debug utilities (from utils/debug.py)
- Analysis scripts (from scripts/)

##### Notes for Implementation

- Clear separation between the web interface and processing logic
- ML pipeline for topic generation
- Error handling and logging flows
- Docker container boundaries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef ui fill:#3498db,stroke:#2980b9,color:white
    classDef processing fill:#2ecc71,stroke:#27ae60,color:white
    classDef ml fill:#e74c3c,stroke:#c0392b,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef external fill:#34495e,stroke:#2c3e50,color:white

    %% User Interface Layer
    subgraph UI[User Interface Layer]
        GradioUI[Gradio Web Interface]
        URLInput[URL Input Handler]
        CategorySelect[Category Selection]
    end

    %% Core Processing Layer
    subgraph Processing[Core Processing Layer]
        GitAnalyzer[GitHub Repository Analyzer]
        ContentFetch[Content Fetcher]
        AnalysisEng[Analysis Engine]
        TopicGen[Topic Generator]
    end

    %% Machine Learning Layer
    subgraph ML[Machine Learning Layer]
        DeBERTa[DeBERTa-v3 Model]
        ZeroShot[Zero-shot Classification]
    end

    %% Infrastructure Layer
    subgraph Infra[Infrastructure Layer]
        Docker[Docker Container]
        ErrorHandler[Error Handling System]
        Logger[Logging System]
        CICD[CI/CD Pipeline]
    end

    %% External Services
    GitHub[(GitHub API)]:::external

    %% Relationships
    GradioUI --> URLInput
    URLInput --> CategorySelect
    CategorySelect --> GitAnalyzer
    GitAnalyzer --> GitHub
    GitHub --> ContentFetch
    ContentFetch --> AnalysisEng
    AnalysisEng --> DeBERTa
    DeBERTa --> ZeroShot
    ZeroShot --> TopicGen
    TopicGen --> GradioUI

    ErrorHandler -.-> Processing
    ErrorHandler -.-> ML
    Logger -.-> Processing
    Logger -.-> ML
    Docker -.-> UI
    Docker -.-> Processing
    Docker -.-> ML
    CICD -.-> Docker

    %% Click events
    click GradioUI "https://github.com/Namgyu-Youn/topicgen/blob/main/app.py"
    click GitAnalyzer "https://github.com/Namgyu-Youn/topicgen/blob/main/scripts/github_analyzer.py"
    click ContentFetch "https://github.com/Namgyu-Youn/topicgen/blob/main/scripts/fetcher.py"
    click AnalysisEng "https://github.com/Namgyu-Youn/topicgen/blob/main/scripts/analyzer.py"
    click TopicGen "https://github.com/Namgyu-Youn/topicgen/blob/main/scripts/topic_list.py"
    click ErrorHandler "https://github.com/Namgyu-Youn/topicgen/blob/main/scripts/error_handler.py"
    click Logger "https://github.com/Namgyu-Youn/topicgen/blob/main/utils/logger.py"
    click Docker "https://github.com/Namgyu-Youn/topicgen/tree/main/Dockerfile"
    click CICD "https://github.com/Namgyu-Youn/topicgen/blob/main/.github/workflows/ci-cd.yml"
    click DeBERTa "https://github.com/Namgyu-Youn/topicgen/tree/main/src/topicgen"

    %% Legend
    subgraph Legend
        UI_Legend[User Interface]:::ui
        Processing_Legend[Processing]:::processing
        ML_Legend[Machine Learning]:::ml
        Infra_Legend[Infrastructure]:::infra
        External_Legend[External Services]:::external
    end

    %% Style applications
    class GradioUI,URLInput,CategorySelect ui
    class GitAnalyzer,ContentFetch,AnalysisEng,TopicGen processing
    class DeBERTa,ZeroShot ml
    class Docker,ErrorHandler,Logger,CICD infra
```
