# imjas-mine/github-analyzer-backend architecture

> Architecture diagram of the GitHub repository imjas-mine/github-analyzer-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imjas-mine/github-analyzer-backend
- Repository: https://github.com/imjas-mine/github-analyzer-backend

## Overview

##### What this project is (type + purpose)
This is a **backend-only FastAPI service** (“GitHub Analyzer API”) that:
- exposes HTTP API endpoints (likely REST via `/api/v1`)
- calls **GitHub’s GraphQL API** using stored `.graphql` query documents
- performs **repository/user analysis** (framework/tech detection, contribution analytics, directory tree inspection, file retrieval)
- uses **OpenAI** to generate AI-powered outputs (e.g., project descriptions / summaries)
- powers a separate website (mentioned in README) but **the frontend is not in this repo**

##### Entrypoint / Application wiring
- `main.py` → FastAPI app creation, router mounting, middleware (if any)
- `app/__init__.py` → package marker

##### API layer (transport)
- `app/api/v1/endpoints.py` → HTTP endpoints; this is your **controller/handler layer**
- `app/api/v1/__init__.py` etc. → versioned API organization

##### Core configuration
- `app/core/config.py` → env vars (e.g., `GITHUB_TOKEN`, OpenAI keys), settings, constants
This should be shown as **Configuration/Secrets** feeding the services.

##### Domain models / schemas
- `app/models/schemas.py` → Pydantic request/response models

##### Service layer (business logic + integrations)
- `app/services/github_service.py` → GitHub GraphQL client wrapper (httpx)
- `app/services/openai_service.py` → OpenAI client wrapper
- `app/services/repo_analyzer_service.py` → orchestration/analysis logic combining GitHub data + AI, plus tech detection heuristics

##### GraphQL query assets
- `app/graphql/queries/*.graphql` → stored query documents

##### Client (Website/Consumer)
- Sends HTTP requests to FastAPI endpoints

##### FastAPI App
- Routes to `app/api/v1/endpoints.py`

##### Repo Analyzer Service (Orchestrator)
- Most “analysis” features likely live here; it coordinates calls below.

##### GitHub Service
- Reads `.graphql` query files
- Uses `httpx` to call **GitHub GraphQL API**
- Auth via `GITHUB_TOKEN` from `config.py` / environment

##### OpenAI Service
- Sends prompts/context to **OpenAI API**
- Returns generated descriptions/summaries/insights

##### Response
- Repo Analyzer aggregates results → endpoint returns response to client

- Client → FastAPI (HTTP/JSON)
- FastAPI → RepoAnalyzerService (internal call)
- RepoAnalyzerService → GitHubService (internal)
- GitHubService → GitHub GraphQL API (HTTPS)
- GitHubService → GraphQL Query Files (file read / template)
- RepoAnalyzerService → OpenAIService (internal)
- OpenAIService → OpenAI API (HTTPS)
- Config/Env → GitHubService/OpenAIService (tokens/keys)

##### Architectural patterns to explicitly represent
From structure, this is a classic layered service:
- **API/Controller layer**: `app/api/v1/endpoints.py`
- **Service layer** (business + orchestration): `repo_analyzer_service.py`
- **Integration clients**: `github_service.py`, `openai_service.py`
- **Contracts**: Pydantic schemas
- **Configuration**: `core/config.py`
- **External systems**: GitHub GraphQL, OpenAI API

- **Versioned API** (`/api/v1`) indicating public contract evolution
- **Orchestrator pattern**: `RepoAnalyzerService` composes multiple downstream calls
- **External API dependency**: GitHub GraphQL is the system of record for repo/user data
- **No database shown in repo**: don’t invent persistence unless you confirm it exists

##### Labels
- “API Endpoints (app/api/v1/endpoints.py)”
- “Repo Analyzer (app/services/repo_analyzer_service.py)”
- “GitHub Client (app/services/github_service.py)”
- “GraphQL Queries (app/graphql/queries/*.graphql)”
- “OpenAI Client (app/services/openai_service.py)”
- “Config (app/core/config.py)”
- “Schemas (app/models/schemas.py)”

- “HTTP JSON request”
- “GraphQL query + variables”
- “Repo tree / file content”
- “Prompt + context”
- “Generated summary/insights”

##### Practical “don’t overthink it” decomposition checklist (maximize components)
- Split “Services” into the 3 actual service files.
- Split “GitHub integration” into “GitHubService” and “GraphQL Query Catalog”.
- Split “App” into “Routing”, “Schemas”, “Config”.
- **each external API** as its own node.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View A: Context (C4 L1)
  %% =========================
  subgraph "A) Context (C4 Level 1)"
    direction TB

    Client["Web Client / API Consumer\n(gitanalyzer.me frontend - external)"]:::external

    API["GitHub Analyzer API\n(FastAPI Backend Service)"]:::system

    GitHubCloud["GitHub GraphQL API\n(api.github.com/graphql)"]:::external
    OpenAICloud["OpenAI API"]:::external

    Client -->|"HTTP/JSON requests"| API
    API -->|"HTTPS GraphQL queries"| GitHubCloud
    API -->|"HTTPS prompts/completions"| OpenAICloud
    API -->|"HTTP/JSON responses"| Client
  end

  %% =========================
  %% View B: Container/Service (C4 L2)
  %% =========================
  subgraph "B) Container / Service Diagram (C4 Level 2)"
    direction TB

    subgraph "FastAPI Application Runtime"
      direction TB

      Entry["App Entrypoint\n(FastAPI app creation + router mounting)"]:::runtime
      AppPkg["Application Package Root\n(app)"]:::runtime

      subgraph "API Layer (/api/v1)"
        direction TB
        Endpoints["API Endpoints / Controllers\n(app/api/v1/endpoints.py)"]:::api
        ApiPkg["API Version Package\n(app/api/v1)"]:::api
      end

      Schemas["Pydantic Schemas / Contracts\n(app/models/schemas.py)"]:::contracts
      Config["Config / Secrets\n(env-driven settings)\n(app/core/config.py)"]:::config

      subgraph "Service Layer"
        direction TB
        RepoAnalyzer["Repo Analyzer Service (Orchestrator)\n(app/services/repo_analyzer_service.py)"]:::orchestrator

        subgraph "Integration Clients"
          direction TB
          GitHubSvc["GitHub Service (GraphQL client wrapper)\n(app/services/github_service.py)"]:::integration
          OpenAISvc["OpenAI Service (client wrapper)\n(app/services/openai_service.py)"]:::integration
        end

        subgraph "GraphQL Query Catalog"
          direction TB
          QueryDir["Stored GraphQL Queries\n(app/graphql/queries/)"]:::artifact
          QRepo["get_repository_details.graphql"]:::artifact
          QTree["get_directory_tree.graphql"]:::artifact
          QFile["get_file_content.graphql"]:::artifact
          QUser["get_user_profile.graphql"]:::artifact
          QUserRepos["get_user_repositories.graphql"]:::artifact
          QContribs["get_user_contributions.graphql"]:::artifact
          QCalendar["get_contribution_calendar.graphql"]:::artifact
          QStats["get_contribution_stats.graphql"]:::artifact

          QueryDir -->|"contains"| QRepo
          QueryDir -->|"contains"| QTree
          QueryDir -->|"contains"| QFile
          QueryDir -->|"contains"| QUser
          QueryDir -->|"contains"| QUserRepos
          QueryDir -->|"contains"| QContribs
          QueryDir -->|"contains"| QCalendar
          QueryDir -->|"contains"| QStats
        end
      end
    end

    %% Internal request path
    Entry -->|"mounts"| Endpoints
    AppPkg -->|"packages"| Endpoints

    Endpoints -->|"validate/serialize\n(Pydantic models)"| Schemas
    Endpoints -->|"calls service methods"| RepoAnalyzer

    %% Orchestration
    RepoAnalyzer -->|"fetch repo/user data"| GitHubSvc
    RepoAnalyzer -->|"prompt + context"| OpenAISvc

    %% GitHub integration
    GitHubSvc -->|"reads query documents"| QueryDir
    GitHubSvc -->|"GraphQL query + variables\n(async HTTPS via httpx)"| GitHubCloud

    %% OpenAI integration
    OpenAISvc -->|"generated summary/insights\n(async HTTPS)"| OpenAICloud

    %% Configuration
    Config -->|"GITHUB_TOKEN"| GitHubSvc
    Config -->|"OPENAI_API_KEY"| OpenAISvc
    Config -->|"constants/settings"| RepoAnalyzer
  end

  %% =========================
  %% View C: Dynamic (Sequence)
  %% =========================
  subgraph "C) Dynamic View (Representative Sequence)"
    direction TB

    subgraph "Flow: Analyze Repository (framework detection + AI summary)"
      direction TB
      S1["Client calls\nPOST /api/v1/analyze-repo"]:::external
      S2["API Endpoints\nparse request + validate schema"]:::api
      S3["Repo Analyzer\norchestrate analysis"]:::orchestrator
      S4["GitHub Service\nexecute GraphQL queries"]:::integration
      S5["GraphQL Query Catalog\n(select documents)"]:::artifact
      S6["GitHub GraphQL API\n(repo tree, files, metadata)"]:::external
      S7["OpenAI Service\nbuild prompt + call model"]:::integration
      S8["OpenAI API\n(summary/insights)"]:::external
      S9["API Endpoints\nreturn aggregated response"]:::api

      S1 -->|"HTTP JSON request"| S2
      S2 -->|"validated input"| S3
      S3 -->|"needs repo metadata/tree/files"| S4
      S4 -->|"load .graphql"| S5
      S4 -->|"GraphQL query + variables"| S6
      S6 -->|"repo details + tree + file content"| S4
      S3 -->|"analysis context + extracted signals"| S7
      S7 -->|"prompt + context"| S8
      S8 -->|"generated text/insights"| S7
      S3 -->|"aggregated results"| S9
      S9 -->|"HTTP JSON response"| S1
    end

    subgraph "Flow: Fetch User Contributions (for visualization)"
      direction TB
      U1["Client calls\nGET /api/v1/user/{login}/contributions"]:::external
      U2["API Endpoints\nvalidate + dispatch"]:::api
      U3["Repo Analyzer\naggregate contribution data"]:::orchestrator
      U4["GitHub Service\nquery contributions/calendar/stats"]:::integration
      U5["GitHub GraphQL API\n(contribution calendar/stats)"]:::external
      U6["API Endpoints\nreturn structured data\n(for 3D visualization frontend)"]:::api

      U1 -->|"HTTP JSON request"| U2
      U2 -->|"validated params"| U3
      U3 -->|"fetch contributions"| U4
      U4 -->|"GraphQL queries"| U5
      U5 -->|"contrib calendar + stats"| U4
      U3 -->|"normalized dataset"| U6
      U6 -->|"HTTP JSON response"| U1
    end
  end

  %% =========================
  %% Click events (from mapping)
  %% =========================
  click Entry "https://github.com/imjas-mine/github-analyzer-backend/blob/main/main.py"
  click AppPkg "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/__init__.py"
  click Endpoints "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/api/v1/endpoints.py"
  click ApiPkg "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/api/v1/__init__.py"
  click Config "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/core/config.py"
  click Schemas "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/models/schemas.py"
  click RepoAnalyzer "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/services/repo_analyzer_service.py"
  click GitHubSvc "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/services/github_service.py"
  click OpenAISvc "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/services/openai_service.py"
  click QueryDir "https://github.com/imjas-mine/github-analyzer-backend/tree/main/app/graphql/queries/"
  click QRepo "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_repository_details.graphql"
  click QTree "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_directory_tree.graphql"
  click QFile "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_file_content.graphql"
  click QUser "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_user_profile.graphql"
  click QUserRepos "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_user_repositories.graphql"
  click QContribs "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_user_contributions.graphql"
  click QCalendar "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_contribution_calendar.graphql"
  click QStats "https://github.com/imjas-mine/github-analyzer-backend/blob/main/app/graphql/queries/get_contribution_stats.graphql"

  %% =========================
  %% Styles
  %% =========================
  classDef system fill:#1f3a5f,stroke:#0b1f33,color:#ffffff,stroke-width:2px
  classDef external fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1.5px
  classDef runtime fill:#0b7285,stroke:#064e3b,color:#ecfeff,stroke-width:1.5px
  classDef api fill:#2563eb,stroke:#1e3a8a,color:#eff6ff,stroke-width:1.5px
  classDef contracts fill:#7c3aed,stroke:#4c1d95,color:#f5f3ff,stroke-width:1.5px
  classDef config fill:#a16207,stroke:#78350f,color:#fffbeb,stroke-width:1.5px
  classDef orchestrator fill:#16a34a,stroke:#14532d,color:#f0fdf4,stroke-width:1.5px
  classDef integration fill:#0891b2,stroke:#164e63,color:#ecfeff,stroke-width:1.5px
  classDef artifact fill:#be123c,stroke:#881337,color:#fff1f2,stroke-width:1.5px
```
