# kunal-bhadra/git-insight architecture

> Architecture diagram of the GitHub repository kunal-bhadra/git-insight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kunal-bhadra/git-insight
- Repository: https://github.com/kunal-bhadra/git-insight

## Overview

##### Project type and purpose
- GitInsight is a full-stack, monolithic web application built with Spring Boot (Java) on the backend and Thymeleaf/Bootstrap/HTMX for the frontend.
- Its goal is to fetch a user’s recent GitHub activity, produce a “Quick Summary” of event counts, and generate a deeper, AI-powered “Smart Summary” via calls to a large language model (Gemini).

##### File structure
- Top-level:
- pom.xml — Maven build and dependency management
- src/main/java/dev/kunalb/gitinsight
– git package: GitHttpClient, GitInsight, GitSummaryGenerator, domain classes (RepoActivity, GitUser)
– llm package: LlmHttpClient, LlmInsight, LlmParser, persona definitions, PromptStore
– web package: ServerController (Spring MVC entry point)
- src/main/resources
– application.properties — config for API keys and ports
– templates (Thymeleaf): homepage.html, summary.html, layout.html
– public/img/site.webmanifest — static assets
- Test directory contains basic AppTest.

##### README
- Confirms tech stack: Spring Boot, Maven, Thymeleaf, HTMX, Bootstrap, Gemini API.
- Describes two main features: Quick Summary (event aggregation) and Smart Summary (LLM-driven feedback via personas).
- Shows external dependencies: GitHub API and Gemini API.

##### Main components
a. Frontend (Client Browser)
- Thymeleaf templates rendered by Spring
- Bootstrap/HTMX for styling and minimal JS interactions
b. Backend (Spring Boot Application)
- Controller layer: ServerController
- Service layer:
– GitInsight & GitHttpClient → GitHub REST API
– GitSummaryGenerator & GitSummaryCleaner → build quick summaries
– LlmInsight & LlmHttpClient → Gemini REST API
– LlmParser & PromptStore → process AI responses
- Domain/in-memory store: models (GitUser, RepoActivity) aggregated at runtime
- Configuration: application.properties, environment variables for API keys
c. External services
- GitHub REST API (for user events)
- Gemini (LLM) API (for smart analysis)

##### Relationships and data flows
1. Browser → HTTP GET “/” or “/summary” on ServerController
2. ServerController invokes GitInsight:
- GitHttpClient calls GitHub API → raw events
- GitSummaryGenerator cleans/aggregates data → Quick Summary
3. For Smart Summary:
- LlmInsight builds prompt via PromptStore → LlmHttpClient calls Gemini API
- LlmParser processes LLM response → Smart Summary
4. Consolidated model is passed back to Thymeleaf template → rendered HTML
5. Browser displays summary; HTMX may drive partial updates

##### Architectural patterns and design principles
- MVC (Model–View–Controller)
- Layered architecture: Controller → Service → HTTP Clients → External APIs
- Single-module monolith (no separate microservices)
- In-memory data aggregation for simplicity (no persistent database)

##### Detail
- Both Quick and Smart Summary flows.
- Critical configuration points (env vars, application.properties).
- If desired, note that persistence is in-memory (no DB node).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        Browser["Browser<br/>(Thymeleaf + HTMX + Bootstrap)"]:::client
        Templates["Thymeleaf Templates"]:::frontend
        StaticAssets["Static Assets"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        SpringApp["SpringApplication"]:::controller
        subgraph "Controller Layer"
            ServerController["ServerController"]:::controller
        end
        subgraph "Service Layer"
            subgraph "Git Service"
                GitInsight["GitInsight Service"]:::service
                GitHttpClient["GitHttpClient"]:::service
                GitSummaryGenerator["GitSummaryGenerator"]:::service
                GitSummaryCleaner["GitSummaryCleaner"]:::service
                GHGenException["GitHubGeneralException"]:::exception
                GHRLException["GitHubRateLimitExceededException"]:::exception
            end
            subgraph "LLM Service"
                LlmInsight["LlmInsight Service"]:::service
                LlmHttpClient["LlmHttpClient"]:::service
                LlmParser["LlmParser"]:::service
                PromptStore["PromptStore"]:::service
                LlmPersona["LlmPersona"]:::service
                PersonaEnum["LlmPersonaEnum"]:::service
                LlmGenException["LlmGeneralException"]:::exception
                SummaryNFException["SummaryNotFoundException"]:::exception
            end
        end
        subgraph "Domain Models"
            GitUser["GitUser"]:::domain
            RepoActivity["RepoActivity"]:::domain
        end
        Config["application.properties"]:::config
        SpringApp --> ServerController
    end

    %% External Services
    subgraph "External Services"
        GitHubAPI["GitHub REST API"]:::external
        GeminiAPI["Gemini (LLM) API"]:::external
    end

    %% Test and Build
    Pom["pom.xml"]:::config
    AppTest["AppTest"]:::config

    %% Connections
    Browser -->|"HTTP GET / or /summary"| ServerController
    ServerController -->|"invoke"| GitInsight
    GitInsight -->|calls| GitHttpClient
    GitHttpClient -->|GET events| GitHubAPI
    GitInsight -->|aggregate| GitSummaryGenerator
    GitSummaryGenerator -->|clean| GitSummaryCleaner
    GitInsight -->|throws| GHGenException
    GitInsight -->|throws| GHRLException
    ServerController -->|"invoke"| LlmInsight
    LlmInsight -->|build prompt| PromptStore
    LlmInsight -->|calls| LlmHttpClient
    LlmHttpClient -->|POST prompt| GeminiAPI
    LlmInsight -->|parse| LlmParser
    LlmInsight -->|throws| LlmGenException
    LlmInsight -->|throws| SummaryNFException
    GitSummaryGenerator --> GitUser
    GitSummaryGenerator --> RepoActivity
    LlmParser --> RepoActivity
    LlmParser --> GitUser
    GitUser -->|model data| ServerController
    RepoActivity -->|model data| ServerController
    ServerController -->|render| Templates
    Templates -->|serve HTML| Browser
    Browser -->|load| StaticAssets

    SpringApp -->|config| Config
    SpringApp -->|build| Pom
    Pom -->|test| AppTest

    %% Click Events
    click Templates "https://github.com/kunal-bhadra/git-insight/tree/main/src/main/resources/templates"
    click StaticAssets "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/resources/public/img/site.webmanifest"
    click SpringApp "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/SpringApplication.java"
    click ServerController "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/web/ServerController.java"
    click GitInsight "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitInsight.java"
    click GitHttpClient "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitHttpClient.java"
    click GitSummaryGenerator "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitSummaryGenerator.java"
    click GitSummaryCleaner "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitSummaryCleaner.java"
    click GHGenException "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitHubGeneralException.java"
    click GHRLException "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitHubRateLimitExceededException.java"
    click GitUser "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/GitUser.java"
    click RepoActivity "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/git/RepoActivity.java"
    click LlmInsight "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/LlmInsight.java"
    click LlmHttpClient "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/LlmHttpClient.java"
    click LlmParser "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/LlmParser.java"
    click PromptStore "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/PromptStore.java"
    click LlmPersona "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/LlmPersona.java"
    click PersonaEnum "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/LlmPersonaEnum.java"
    click LlmGenException "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/LlmGeneralException.java"
    click SummaryNFException "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/java/dev/kunalb/gitinsight/llm/SummaryNotFoundException.java"
    click Config "https://github.com/kunal-bhadra/git-insight/blob/main/src/main/resources/application.properties"
    click Pom "https://github.com/kunal-bhadra/git-insight/blob/main/pom.xml"
    click AppTest "https://github.com/kunal-bhadra/git-insight/blob/main/src/test/java/dev/kunalb/AppTest.java"

    %% Styles
    classDef client fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef controller fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#cfe2ff,stroke:#333,stroke-width:1px
    classDef domain fill:#e2d5ff,stroke:#333,stroke-width:1px
    classDef config fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef external fill:#d4edda,stroke:#333,stroke-width:1px
    classDef exception fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef frontend fill:#e2e3e5,stroke:#333,stroke-width:1px
```
