How imjas-mine/github-analyzer-backend works
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.