GitHub-Profile-AnAIyzer

Real-time GitHub developer analytics dashboard that turns any public username into a clear profile and repository insights view.

Description

GitHub-Profile-AnAIyzer is a lightweight full-stack web app that fetches public data from the GitHub REST API and presents it in a modern, interactive dashboard. The backend (FastAPI) handles profile retrieval, repository aggregation, language distribution, pull request counting, and domain-specific error mapping. The frontend (Vanilla JavaScript + Tailwind + Chart.js) renders profile cards, language charts, technology topics, and sortable repository lists with fast client-side interactions. The project is intentionally stateless and simple to run locally.

Table of Contents

• Description
• AI-Driven Development
• Features
• Tech Stack
• Getting Started
• API Endpoints
• Architecture & Directory Structure
• Testing
• Version History

AI-Driven Development

This project was built with AI-driven development.

• Built using GitHub Copilot with custom, task-specific agents and skills.
• No manual code writing was used in the main implementation workflow.

Custom Agents and Skills Used

Custom Sub-Agents

• GitHub-Profile-AnAIyzer Backend (.github/agents/backend.agent.md): Specialized in FastAPI routes, GitHub API client logic, backend aggregation services, and backend testing workflow.
• GitHub-Profile-AnAIyzer Frontend (.github/agents/frontend.agent.md): Specialized in Vanilla JS UI architecture, DOM rendering, Chart.js behavior, interactive filtering/sorting, and visual validation.

Custom Skills

• python-fastapi (.github/skills/python-fastapi.md): Defined backend design rules (thin routers, typed models, clear error handling, stateless architecture).
• python-testing-patterns (.github/skills/python-testing-patterns.md): Enforced pytest conventions and strict mocking of GitHub HTTP requests for deterministic tests.
• vanilla-frontend-patterns-and-design (.github/skills/vanilla-frontend-patterns-and-design.md): Guided frontend structure, Chart.js lifecycle management, and UI/UX quality principles.

Repository-Wide Agent Instructions

• AGENTS.md (AGENTS.md): This file sets the main project rules for all agents and contributors.
• How it works with sub-agents and skills: AGENTS.md gives the base rules. Sub-agents and skills add more specific backend or frontend guidance.
• Testing rule: Follow the mock-only GitHub API testing policy described in the Testing section.

Features

• Search any public GitHub username.
• View profile summary: avatar, login, name, bio, followers, and repository count.
• Aggregate analytics: total stars, total forks, and total pull requests.
• Interactive language distribution doughnut chart with click-to-filter behavior.
• Topic cloud generated from repository topics, including topic-based filtering.
• Repository explorer with:
  • sorting by stars, last updated date, or name
  • ascending/descending order
  • show more/show less pagination controls
  • topic badges and relative last-updated labels
• Resilient error handling for empty usernames, missing users, rate limits, and upstream API failures.

Tech Stack

• Backend: Python, FastAPI, Pydantic, HTTPX, python-dotenv
• Frontend: HTML5, Tailwind CSS, Vanilla JavaScript (ES modules), Chart.js
• Testing: pytest, pytest-asyncio, pytest-mock, FastAPI TestClient

Getting Started

Prerequisites & Dependencies

• Python 3.11 or newer
• pip
• Optional: GitHub personal access token for higher API limits (GITHUB_TOKEN)

Installation & Setup

1. Clone the repository:

git clone <repo-url>
cd GitHub-Profile-AnAIyzer

2. Create and activate a virtual environment:

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux/macOS (bash/zsh):

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:

python -c "from shutil import copyfile; copyfile('.env.example', '.env')"

5. Update .env (optional but recommended):

GITHUB_TOKEN=your_github_token_here

Executing Program

Start the FastAPI app from the project root:

python -m uvicorn backend.app:app --app-dir src --host 127.0.0.1 --port 8000

Open the app in your browser:

http://127.0.0.1:8000

API Endpoints

Method	Endpoint	Description
GET	/api/profile/{username}	Returns public profile information and top topic frequencies for the user.
GET	/api/analytics/{username}	Returns aggregated repository analytics (stars, forks, PR count, language counts, repositories).
GET	/api/languages/{username}	Returns language usage counts across the user’s public repositories.

Common error behavior:

• 400: Invalid input (for example, empty username)
• 404: GitHub user not found
• 429: GitHub API rate limit exceeded
• 502: Upstream GitHub request failure (profile/analytics endpoints)

Architecture & Directory Structure

The project follows a clean modular split between backend API logic and frontend presentation logic.

GitHub-Profile-AnAIyzer/
├── src/
│   ├── backend/
│   │   ├── app.py                  # FastAPI app bootstrap and router registration
│   │   ├── clients/github.py       # GitHub API client + response models + error mapping
│   │   ├── routers/                # HTTP endpoints: profile, analytics, languages
│   │   └── services/               # Business logic and data aggregation
│   └── frontend/
│       ├── index.html              # Main UI shell
│       ├── app.js                  # App entry point
│       ├── AppController.js        # Event orchestration and app flow
│       ├── UIManager.js            # DOM rendering + chart updates
│       ├── StateManager.js         # UI state, filtering, and sorting
│       └── ApiService.js           # Frontend API calls and error translation
├── tests/backend/                  # Backend route/client unit tests with mocks
├── .github/agents/                 # Project-specific AI sub-agents
├── .github/skills/                 # Project-specific AI skill instructions
├── requirements.txt
└── README.md

Testing

Run the full test suite:

pytest -q

Or run backend-focused tests:

python -m pytest tests/backend

Testing policy:

• Backend tests mock HTTP calls to GitHub.
• No test should call api.github.com directly.

Version History

• 1.0.0
• Initial Release (Fully AI-Generated)