🔥 DevAudit — AI Code Roaster & Health Inspector

"Your code has the structural integrity of a Jenga tower in an earthquake." — DevAudit, probably, about your repo

DevAudit points your GitHub repo at Google Gemini and gets back three things:

What you get	What it means
🎤 Brutal Roast	Technically specific, painfully accurate, darkly funny AI feedback
💯 Health Score	A 0–100 score across architecture, security, and maintainability
🗺️ 12-Month Roadmap	Three actionable phases to actually fix your mess

No fluff. No "great job!". Just the honest technical opinion your code deserves.

---

Screenshots

Landing Page

Login

Dashboard

---

Why DevAudit?

Most code review tools tell you what to fix. DevAudit tells you how bad it is first — because sometimes you need a reality check before a checklist. The roast isn't mean for the sake of it; every line is grounded in real code signals (file structure, commit history, language mix, README quality, etc.).

---

Features

• Zero install friction — one backend, one frontend, one proxy. Done.
• Deep repo analysis — pulls metadata, README, file tree, language breakdown, and last 10 commits before asking the AI anything
• Structured AI output — Gemini returns typed JSON (score, roast, roadmap), not free-form prose
• Persistent history — every audit is saved to SQLite so you can track improvement over time
• Password-protected dashboard — simple but effective; your audits stay yours
• Neumorphic UI — because your code may be ugly, but the dashboard doesn't have to be

---

Tech Stack

Layer	Technology
Frontend	React 18 + Vite, React Router v6, CSS Modules
Backend	FastAPI, SQLAlchemy, SQLite, Uvicorn
AI	Google Gemini API
GitHub Data	GitHub REST API
Proxy	Python http.server (single-port unified serving)

---

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• A Google Gemini API key
• A GitHub personal access token (read:repo scope)

1. Clone & configure

git clone https://github.com/your-username/dev-audit.git
cd dev-audit
cp .env.example backend/.env

Edit backend/.env and fill in your keys.

2. Start the backend

cd backend
pip install -r requirements.txt
python main.py
# Listening on http://localhost:8001

3. Start the frontend

cd frontend
npm install
npm run dev
# Vite dev server on http://localhost:5173

4. (Optional) Unified proxy

Want everything on a single port?

# From project root
python proxy_server.py
# Everything served on http://localhost:9999

---

Environment Variables

Copy .env.example to backend/.env and set:

Variable	Description
GEMINI_API_KEY	Your Google Gemini API key
GEMINI_MODEL	Model ID (default: gemini-2.0-flash)
GITHUB_TOKEN	GitHub PAT for fetching repo data
LOCAL_PASSWORD	Dashboard login password

---

Project Structure

dev-audit/
├── backend/
│   ├── main.py          # FastAPI app — all endpoints, AI logic, DB models
│   └── .env             # Your secrets (git-ignored)
├── frontend/
│   └── src/
│       ├── api/         # API client
│       ├── components/  # AuditCard, AuditForm, Sidebar, StatsCard
│       └── pages/       # Landing, Login, Dashboard
├── proxy_server.py      # Optional unified proxy (port 9999)
├── .env.example         # Template — copy to backend/.env
└── README.md

---

How It Works

User submits GitHub handle + repo URL
        │
        ▼
FastAPI backend fetches from GitHub API:
  • Repo metadata (stars, forks, language, topics)
  • README content (first 3000 chars)
  • Top-level file/folder tree
  • Language percentage breakdown
  • Last 10 commit messages
        │
        ▼
All context → Gemini prompt
        │
        ▼
Gemini returns structured JSON:
  { score: 0-100, roast: "...", roadmap: [{phase, description}, ...] }
        │
        ▼
Saved to SQLite → returned to dashboard

---

API Reference

All endpoints require X-Password: <your LOCAL_PASSWORD> header (except login).

Method	Endpoint	Description
POST	/api/login	Validate password
GET	/api/audit	List all audits
POST	/api/audit	Create a new audit

POST /api/audit body:

{
  "github_handle": "torvalds",
  "repo_url": "https://github.com/torvalds/linux"
}

---

Contributing

PRs welcome. If you're adding a new AI feature, keep the output schema structured (typed JSON) so the frontend can reliably render it.

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-thing
3. Commit your changes: git commit -m 'feat: add my thing'
4. Push and open a PR

---

Roadmap

• Public shareable audit links
• Multi-repo comparison view
• Webhook trigger on push (auto-audit on deploy)
• GitHub OAuth (replace password auth)
• Export audit as PDF

---

License

MIT — do whatever you want, just don't blame us when the AI roasts your production codebase at 3am.

---

Built by Dhiraj Hazarika & Frank.