# aanishnithin07/gitdna architecture

> Architecture diagram of the GitHub repository aanishnithin07/gitdna, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aanishnithin07/gitdna
- Repository: https://github.com/aanishnithin07/gitdna

## Overview

#### Purpose and Entry Points
GitDNA is a GitHub behavioral-intelligence product: it fetches public GitHub telemetry, derives developer activity signals, and uses LLMs to produce profile narratives, traits, comparisons, and visual artifacts. The React client starts at `src/main.jsx` and composes the experience in `src/App.jsx`. The Python API is exposed through `backend/main.py`; `api/index.py` likely provides the Vercel-facing API entry.

#### Frontend Application Shell
`src/App.jsx` owns the scan/comparison workflow, profile state, and composition of the feature views. `src/utils/backendApi.js` is the frontend boundary for calling the backend rather than embedding API logic across UI components. Styling and application-level visual behavior live in `src/App.css` and `src/index.css`.

#### Analysis and AI Pipeline
`backend/main.py` is the FastAPI HTTP boundary: it accepts requested GitHub identities/features and returns analysis results. `backend/analyzer.py` is the deterministic analysis stage that transforms GitHub REST/Event data into behavioral metrics such as activity, timing, language, and commit-derived signals. `backend/ai_engine.py` is the generative interpretation layer, converting computed telemetry into archetypes, roast/battle narratives, time-machine stories, and related AI content.

#### GitHub and LLM Service Boundaries
The backend integrates GitHub REST and Events APIs as the source of public profile, repository, commit, and event data. LLM generation depends on Groq/Llama 3.1 and Google Gemini Flash, with credentials/configuration expected via `backend/.env.example` and `.env.example`. The key boundary is: external GitHub data is normalized and scored before being passed to AI generation, keeping visual clients insulated from provider-specific calls.

#### Feature Presentation Modules
Specialized React components render distinct projections of the common profile-analysis result: repository/trait analysis in `src/components/RepoAnalysis.jsx`, activity geography in `src/components/GitMap.jsx`, longitudinal narratives in `src/components/TimeMachine.jsx`, and workload risk in `src/components/BurnoutDetail.jsx`. Comparison and collectible outputs are isolated in `src/components/DeveloperMatcher.jsx` and `src/components/TradingCard.jsx`; editorial/linguistic presentations are in `src/components/GitNewspaper.jsx` and `src/components/LanguagePrediction.jsx`.

#### Primary Control Flow
A user supplies one or two GitHub usernames in the client. `src/App.jsx` invokes the backend through `src/utils/backendApi.js`; FastAPI coordinates GitHub retrieval, metric analysis, and optional AI enrichment. The resulting structured profile is retained client-side and fanned out to visualization components, avoiding separate external fetches per card. Share/deep-link behavior is primarily a frontend concern, while authoritative data acquisition and model calls remain server-side.

#### Runtime and Deployment
The frontend is a Vite/React static application, configured by `vite.config.js` and deployed through `vercel.json`. The backend is a Python/FastAPI service with dependencies in `backend/requirements.txt`, runtime declaration in `backend/runtime.txt`, and Railway deployment metadata in `backend/railway.json` and `backend/Procfile`. This creates a split deployment: Vercel serves the interactive client, while Railway hosts long-running API and AI-provider integration.

Main entry points: [`backend/main.py`](https://github.com/aanishnithin07/gitdna/blob/main/backend/main.py) (FastAPI API), [`src/App.jsx`](https://github.com/aanishnithin07/gitdna/blob/main/src/App.jsx) (Scan & comparison shell), [`src/utils/backendApi.js`](https://github.com/aanishnithin07/gitdna/blob/main/src/utils/backendApi.js) (Backend API client), [`src/main.jsx`](https://github.com/aanishnithin07/gitdna/blob/main/src/main.jsx) (React entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Vite React Client"]
  node_react_entry["React entry<br/>client bootstrap<br/>[main.jsx]"]
  node_app["Scan &amp; comparison shell<br/>React workflow<br/>[App.jsx]"]
  node_api_client["Backend API client<br/>frontend boundary<br/>[backendApi.js]"]
  node_profile_views["Profile analysis views<br/>React views<br/>[RepoAnalysis.jsx]"]
  node_comparison_outputs["Comparison &amp; card views<br/>React views"]
  node_editorial_views["Editorial views<br/>React views<br/>[GitNewspaper.jsx]"]
end

subgraph group_backend["FastAPI Analysis Service"]
  node_fastapi{{"FastAPI API<br/>HTTP boundary<br/>[main.py]"}}
  node_analyzer["Telemetry analyzer<br/>deterministic analysis<br/>[analyzer.py]"]
  node_ai_engine["AI interpretation<br/>LLM enrichment<br/>[ai_engine.py]"]
  node_vercel_api["Vercel API entry<br/>serverless entry<br/>[index.py]"]
end

subgraph group_external["External Providers"]
  node_github[("GitHub REST &amp; Events<br/>public telemetry source")]
  node_llm_providers{{"Groq/Llama &amp; Gemini<br/>LLM providers"}}
end

subgraph group_deploy["Deployment"]
  node_vite["Vite build config<br/>client build<br/>[vite.config.js]"]
  node_vercel["Vercel<br/>static hosting<br/>[vercel.json]"]
  node_railway["Railway<br/>API hosting<br/>[railway.json]"]
  node_python_runtime["Python API runtime<br/>service runtime<br/>[requirements.txt]"]
end

node_react_entry -->|"mounts"| node_app
node_app -->|"requests scans"| node_api_client
node_app -->|"fans out profile"| node_profile_views
node_app -->|"renders comparison"| node_comparison_outputs
node_app -->|"renders narratives"| node_editorial_views
node_api_client -->|"HTTP analysis request"| node_fastapi
node_vercel_api -.->|"API entry"| node_fastapi
node_fastapi -->|"retrieves telemetry"| node_github
node_fastapi -->|"coordinates metrics"| node_analyzer
node_analyzer -->|"normalized scored telemetry"| node_ai_engine
node_ai_engine -->|"generates content"| node_llm_providers
node_fastapi -->|"structured profile result"| node_api_client
node_vite -.->|"builds client"| node_react_entry
node_vercel -.->|"deploys static app"| node_vite
node_railway -.->|"runs"| node_python_runtime
node_python_runtime -.->|"hosts"| node_fastapi

click node_react_entry "https://github.com/aanishnithin07/gitdna/blob/main/src/main.jsx"
click node_app "https://github.com/aanishnithin07/gitdna/blob/main/src/App.jsx"
click node_api_client "https://github.com/aanishnithin07/gitdna/blob/main/src/utils/backendApi.js"
click node_profile_views "https://github.com/aanishnithin07/gitdna/blob/main/src/components/RepoAnalysis.jsx"
click node_comparison_outputs "https://github.com/aanishnithin07/gitdna/blob/main/src/components/DeveloperMatcher.jsx"
click node_editorial_views "https://github.com/aanishnithin07/gitdna/blob/main/src/components/GitNewspaper.jsx"
click node_fastapi "https://github.com/aanishnithin07/gitdna/blob/main/backend/main.py"
click node_analyzer "https://github.com/aanishnithin07/gitdna/blob/main/backend/analyzer.py"
click node_ai_engine "https://github.com/aanishnithin07/gitdna/blob/main/backend/ai_engine.py"
click node_vercel_api "https://github.com/aanishnithin07/gitdna/blob/main/api/index.py"
click node_vite "https://github.com/aanishnithin07/gitdna/blob/main/vite.config.js"
click node_vercel "https://github.com/aanishnithin07/gitdna/blob/main/vercel.json"
click node_railway "https://github.com/aanishnithin07/gitdna/blob/main/backend/railway.json"
click node_python_runtime "https://github.com/aanishnithin07/gitdna/blob/main/backend/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react_entry,node_app,node_api_client,node_profile_views,node_comparison_outputs,node_editorial_views toneBlue
class node_fastapi,node_analyzer,node_ai_engine,node_vercel_api toneAmber
class node_github,node_llm_providers toneMint
class node_vite,node_vercel,node_railway,node_python_runtime toneRose
```

## Components

### Vite React Client

- [React entry](https://github.com/aanishnithin07/gitdna/blob/main/src/main.jsx): client bootstrap · `src/main.jsx`
- [Scan & comparison shell](https://github.com/aanishnithin07/gitdna/blob/main/src/App.jsx): React workflow · Owns profile state and feature composition. · `src/App.jsx`
- [Backend API client](https://github.com/aanishnithin07/gitdna/blob/main/src/utils/backendApi.js): frontend boundary · `src/utils/backendApi.js`
- [Profile analysis views](https://github.com/aanishnithin07/gitdna/blob/main/src/components/RepoAnalysis.jsx): React views · Repo, map, timeline, and burnout projections. · `src/components/RepoAnalysis.jsx`
- [Comparison & card views](https://github.com/aanishnithin07/gitdna/blob/main/src/components/DeveloperMatcher.jsx): React views · Matchup and collectible profile outputs. · `src/components/DeveloperMatcher.jsx`
- [Editorial views](https://github.com/aanishnithin07/gitdna/blob/main/src/components/GitNewspaper.jsx): React views · Newspaper and language presentations. · `src/components/GitNewspaper.jsx`

### FastAPI Analysis Service

- [FastAPI API](https://github.com/aanishnithin07/gitdna/blob/main/backend/main.py): HTTP boundary · Accepts identities and requested analysis features. · `backend/main.py`
- [Telemetry analyzer](https://github.com/aanishnithin07/gitdna/blob/main/backend/analyzer.py): deterministic analysis · Derives behavioral metrics from GitHub data. · `backend/analyzer.py`
- [AI interpretation](https://github.com/aanishnithin07/gitdna/blob/main/backend/ai_engine.py): LLM enrichment · Creates archetypes, narratives, and AI content. · `backend/ai_engine.py`
- [Vercel API entry](https://github.com/aanishnithin07/gitdna/blob/main/api/index.py): serverless entry · `api/index.py`

### External Providers

- **GitHub REST & Events**: public telemetry source · Profiles, repositories, commits, and events.
- **Groq/Llama & Gemini**: LLM providers

### Deployment

- [Vite build config](https://github.com/aanishnithin07/gitdna/blob/main/vite.config.js): client build · `vite.config.js`
- [Vercel](https://github.com/aanishnithin07/gitdna/blob/main/vercel.json): static hosting · Serves the interactive client. · `vercel.json`
- [Railway](https://github.com/aanishnithin07/gitdna/blob/main/backend/railway.json): API hosting · Hosts the long-running Python API. · `backend/railway.json`
- [Python API runtime](https://github.com/aanishnithin07/gitdna/blob/main/backend/requirements.txt): service runtime · `backend/requirements.txt`

## Connections

- React entry → Scan & comparison shell: mounts
- Scan & comparison shell → Backend API client: requests scans
- Scan & comparison shell → Profile analysis views: fans out profile
- Scan & comparison shell → Comparison & card views: renders comparison
- Scan & comparison shell → Editorial views: renders narratives
- Backend API client → FastAPI API: HTTP analysis request
- Vercel API entry → FastAPI API: API entry
- FastAPI API → GitHub REST & Events: retrieves telemetry
- FastAPI API → Telemetry analyzer: coordinates metrics
- Telemetry analyzer → AI interpretation: normalized scored telemetry
- AI interpretation → Groq/Llama & Gemini: generates content
- FastAPI API → Backend API client: structured profile result
- Vite build config → React entry: builds client
- Vercel → Vite build config: deploys static app
- Railway → Python API runtime: runs
- Python API runtime → FastAPI API: hosts