Skip to content

Commit df8f957

Browse files
sudheerxdevsudheerxdev
committed
update project
1 parent b677ac0 commit df8f957

22 files changed

Lines changed: 3691 additions & 2674 deletions

‎.env.example‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Required in Vercel for higher GitHub rate limits and pinned GraphQL queries
2+
GITHUB_TOKEN=
3+
4+
# Optional API-level rate limiter using Vercel KV / Upstash REST
5+
KV_REST_API_URL=
6+
KV_REST_API_TOKEN=
7+
8+
# Optional tuning
9+
RATE_LIMIT_MAX_REQUESTS=30
10+
RATE_LIMIT_WINDOW_MS=60000
11+
ANALYSIS_CACHE_TTL_MS=300000
12+
GITHUB_CACHE_TTL_MS=120000
13+
GITHUB_REQUEST_TIMEOUT_MS=10000

‎Images/mascot-detective.svg‎

Lines changed: 47 additions & 0 deletions
Loading

‎README.md‎

Lines changed: 93 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,117 @@
1-
# DevDetective - GitHub Portfolio Analyzer & Enhancer
1+
# DevDetective - Vercel Production Build
22

3-
DevDetective is a production-oriented static web app that evaluates a GitHub profile like a recruiter.
4-
It fetches GitHub data, computes weighted category scores, highlights strengths and red flags,
5-
and generates actionable portfolio improvement suggestions.
3+
DevDetective is a GitHub Portfolio Analyzer & Enhancer optimized for Vercel serverless deployment.
4+
It provides recruiter-style scoring, risk detection, roadmap generation, and downloadable reports using real GitHub data.
65

7-
## Features
6+
## Highlights
87

9-
- Accepts a GitHub username or profile URL
10-
- Supports optional GitHub PAT for higher rate limits and GraphQL pinned repositories
11-
- Fetches public repositories, stars, forks, watchers, README presence, language signals, and recency
12-
- Estimates activity consistency using `pushed_at` timestamps
13-
- Fetches authored PR and issue counts via GitHub Search API
14-
- Computes a weighted `GitHub Portfolio Score (0-100)`
15-
- Computes `Hireability Score` and `Portfolio Readiness Level`
16-
- Returns 7 sub-scores: Documentation Quality, Code Activity / Consistency, Project Popularity, Repository Completeness, Language Diversity, Recent Activity, Impact Signals
17-
- Shows transparent scoring inputs and formula context in UI and report output
18-
- Generates recruiter-style insights: Strengths, Red Flags, Actionable Suggestions (minimum 5)
19-
- Adds AI Recruiter Simulation verdict and feedback signals
20-
- Detects hidden portfolio risks (concentration, conversion, collaboration, momentum)
21-
- Recommends a career path with confidence score and next-skill targets
22-
- Generates a personalized multi-week improvement roadmap
23-
- Includes language, repository-importance, subscore radar, and activity-bucket charts
24-
- Includes pinned repository panel and ranked repository table
25-
- Supports light/dark mode persistence
26-
- Exports a downloadable recruiter-ready Markdown report
27-
- Supports offline shell caching through service worker
8+
- Accepts GitHub username, `@username`, or profile URL
9+
- Uses real GitHub REST/GraphQL data through serverless API
10+
- Objective portfolio score (`0-100`) + weighted category subscores
11+
- Recruiter insights: strengths, red flags, hidden risks
12+
- Hireability score + readiness level
13+
- Top repository ranking and visual analytics dashboard
14+
- Personalized improvement roadmap and career-path recommendation
15+
- Downloadable markdown recruiter report
16+
- Dark/light mode and responsive SaaS-style UI
2817

29-
## Optional GitHub Token Setup
18+
## Vercel-Native Architecture
3019

31-
Token is optional, but recommended for better API limits and pinned repositories.
20+
- Static frontend served via Vercel CDN
21+
- Serverless API route: `api/analyze.js`
22+
- Stateless request flow
23+
- Optional distributed rate limiting using Vercel KV / Upstash REST
24+
- API response caching + in-function cache + CDN caching headers
25+
- Request de-duplication for concurrent same-user analysis calls
3226

33-
1. Go to GitHub Settings > Developer settings > Personal access tokens.
34-
2. Create a token with minimal read access for public data.
35-
3. Paste it into the app's token input.
27+
## Project Structure
3628

37-
Token handling:
29+
```text
30+
.
31+
├── api/
32+
│ ├── analyze.js
33+
│ └── _lib/
34+
│ ├── analysis.js
35+
│ ├── github.js
36+
│ ├── rate-limit.js
37+
│ └── utils.js
38+
├── src/
39+
│ ├── main.js
40+
│ ├── config/constants.js
41+
│ ├── report/markdown.js
42+
│ ├── ui/charts.js
43+
│ ├── ui/elements.js
44+
│ ├── ui/render.js
45+
│ └── utils/core.js
46+
├── index.html
47+
├── style.css
48+
├── sw.js
49+
├── manifest.json
50+
├── vercel.json
51+
└── .env.example
52+
```
3853

39-
- Stored in browser localStorage key: `devdetective_token`
40-
- No backend storage is used in this project
54+
## Environment Variables
4155

42-
## Run Locally
56+
Set in Vercel Project Settings -> Environment Variables.
4357

44-
This project is plain HTML/CSS/JS. Serve the repository root with any static server.
58+
### Required (recommended strongly)
4559

46-
### Option 1: Python
60+
- `GITHUB_TOKEN`: GitHub token for higher rate limits and GraphQL pinned repos
4761

48-
```bash
49-
python3 -m http.server 5500
50-
```
62+
### Optional (for distributed rate limiting)
5163

52-
Open:
64+
- `KV_REST_API_URL`
65+
- `KV_REST_API_TOKEN`
5366

54-
```text
55-
http://localhost:5500
56-
```
67+
### Optional tuning
68+
69+
- `RATE_LIMIT_MAX_REQUESTS` (default `30`)
70+
- `RATE_LIMIT_WINDOW_MS` (default `60000`)
71+
- `ANALYSIS_CACHE_TTL_MS` (default `300000`)
72+
- `GITHUB_CACHE_TTL_MS` (default `120000`)
73+
- `GITHUB_REQUEST_TIMEOUT_MS` (default `10000`)
74+
75+
## Deploy on Vercel
5776

58-
### Option 2: VS Code Live Server or any static server
77+
1. Import this repository in Vercel.
78+
2. Add environment variables above.
79+
3. Deploy.
5980

60-
Serve the repository root and open `index.html`.
81+
Vercel settings:
6182

62-
## Rate Limits and Reliability
83+
- Build Command: **(none required)**
84+
- Output Directory: **(none required)**
85+
- Framework Preset: **Other**
6386

64-
- Handles GitHub API errors with clear user-facing messages
65-
- Shows rate-limit reset time when available
66-
- Aborts in-flight requests when a new analysis starts
67-
- Retries once on transient network failures
68-
- Caches completed analyses for 10 minutes in `devdetective_cache_{username}`
87+
`vercel.json` already includes function config and production headers.
6988

70-
## Scoring Model Summary
89+
## Local Run
7190

72-
Overall score combines these weighted categories:
91+
### Static frontend check
92+
93+
```bash
94+
python3 -m http.server 5500
95+
```
96+
97+
Open `http://localhost:5500`.
98+
99+
### Full Vercel-like local run (if Vercel CLI installed)
100+
101+
```bash
102+
vercel dev
103+
```
73104

74-
- Documentation Quality (18%)
75-
- Code Activity / Consistency (17%)
76-
- Project Popularity (15%)
77-
- Repository Completeness (14%)
78-
- Language Diversity (10%)
79-
- Recent Activity (14%)
80-
- Impact Signals (12%)
105+
## Reliability & Security
81106

82-
Each sub-score is normalized to `0-100`, then combined by weight.
107+
- Input sanitization for usernames/URLs
108+
- API abuse protection with rate limiting
109+
- 429 responses when limits are exceeded
110+
- Graceful handling for invalid input, not found, network failures, and GitHub upstream failures
111+
- No sensitive token exposed to browser
112+
- Security headers configured via `vercel.json`
83113

84-
## Known Limitations
114+
## Notes
85115

86-
- Commit frequency is approximated using repository `pushed_at` (not full commit history traversal)
87-
- README and language deep checks are limited to top repositories for API efficiency
88-
- Pinned repo retrieval via GraphQL requires token; fallback ranking is used otherwise
89-
- Output quality depends on public GitHub metadata completeness
116+
- Commit consistency is approximated via `pushed_at` metadata.
117+
- Deep README/language checks are limited to top repos for performance and GitHub quota efficiency.

0 commit comments

Comments
 (0)