# gabrielchua/repo-explainer architecture

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

- Interactive diagram: https://gitdiagram.com/gabrielchua/repo-explainer
- Repository: https://github.com/gabrielchua/repo-explainer

## Overview

##### Project type and purpose
- This is a single-service web application built with Streamlit (Python) that provides AI-powered analysis of GitHub repositories.
- It features a simple UI, business-logic helpers in utils.py, and integration with two external services: the GitHub REST API and Google’s Generative AI (Gemini-1.5).

##### File structure
- app.py – the Streamlit entry point defining UI components and orchestrating calls
- utils.py – helper functions for:
– Fetching repository contents via GitHub API
– Summarizing code with Google Gen AI
– Formatting results for display
- requirements.txt – lists dependencies (streamlit, google-ai-sdk, PyGitHub or requests, etc.)
- .streamlit/secrets.example.toml – template for storing API keys (GH_API_KEY, GOOGLE_API_KEY)
- README.md – project description and usage instructions
- No database or internal persistence; all state is transient per session.

##### README for architecture cues
- User interacts via Streamlit UI in the browser
- Application invokes:
– GitHub API (public or authenticated) to retrieve repo tree, README, source files
– Google Generative AI API (Gemini-1.5-pro) to generate explanations and interactive chat responses

##### Main components and interactions
a. Client (Web Browser)
- HTTP(S) connection to Streamlit server
b. Streamlit Server (app.py)
- UI layer: input field for GitHub URL, “Analyze” button, chat interface
- Controller logic: orchestrates calls to utils
c. Business Logic Module (utils.py)
- GitHub Client: fetch repository structure, files
- Google AI Client: send prompts, receive AI-generated summaries
d. External Services
- GitHub REST API (optionally authenticated)
- Google Generative AI API (Gemini-1.5-pro)
e. Configuration/Secrets Store
- .streamlit/secrets.toml or environment variables for API keys

##### Relationships and data flows
1. User → Streamlit UI: enters GitHub URL
2. Streamlit UI (app.py) → GitHub API: fetches repository metadata and code
3. Streamlit UI → Google Gen AI API: sends extracted code/README for summarization
4. Google Gen AI API → Streamlit UI: returns summary, allows follow-up Q&A
5. Streamlit UI → User: displays summary and answers

##### Architectural patterns and design principles
- Separation of concerns:
– UI and routing in app.py
– Business logic in utils.py
- Statelessness: each user session is in-memory; no database
- External integration: clear client modules abstracting REST calls
- Config management: secrets stored outside source code, loaded at runtime

##### Relevant technologies and libraries
- Streamlit (web server & UI)
- Python 3.x
- requests or PyGitHub (GitHub API client)
- google-ai-sdk (or REST calls to Google Gen AI)
- TOML / os.environ for secrets

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main flow
    Browser["User Browser"]:::user
    Streamlit["Streamlit UI & Controller"]:::inApp
    Utils["Business Logic Module\n(utils.py)"]:::inApp
    GitHubAPI["GitHub REST API"]:::external
    GoogleAI["Google Gen AI API\n(Gemini-1.5-pro)"]:::external

    %% Flow arrows
    Browser -->|"HTTP(S) request"| Streamlit
    Streamlit -->|"calls utils.github_client"| Utils
    Utils -->|"GET /repos"| GitHubAPI
    GitHubAPI -->|"repo data"| Utils
    Utils -->|"returns repo data"| Streamlit
    Streamlit -->|"calls utils.ai_client"| Utils
    Utils -->|"POST /generateSummary"| GoogleAI
    GoogleAI -->|"AI summary"| Utils
    Utils -->|"returns summary"| Streamlit
    Streamlit -->|"renders response"| Browser

    %% Auxiliary files
    subgraph "Project Files"
        Secrets[".streamlit/secrets.example.toml"]:::config
        Requirements["requirements.txt"]:::doc
        Readme["README.md"]:::doc
    end

    %% File associations
    Secrets -.-> Streamlit
    Secrets -.-> Utils
    Requirements -.-> Streamlit
    Readme -.-> Browser

    %% Click events
    click Streamlit "https://github.com/gabrielchua/repo-explainer/blob/main/app.py"
    click Utils "https://github.com/gabrielchua/repo-explainer/blob/main/utils.py"
    click Secrets "https://github.com/gabrielchua/repo-explainer/blob/main/.streamlit/secrets.example.toml"
    click Requirements "https://github.com/gabrielchua/repo-explainer/blob/main/requirements.txt"
    click Readme "https://github.com/gabrielchua/repo-explainer/blob/main/README.md"

    %% Styles
    classDef inApp fill:#d0e1f9,stroke:#333,stroke-width:1px
    classDef external fill:#c7f0d6,stroke:#333,stroke-width:1px
    classDef config fill:#f9e0b0,stroke:#333,stroke-width:1px
    classDef doc fill:#e1d0f9,stroke:#333,stroke-width:1px
    classDef user fill:#ffffff,stroke:#333,stroke-width:1px
```
