DevLens AI

An AI-powered developer workspace that analyzes GitHub repositories — built to read a codebase the way a senior engineer would on day one.

🚧 Project Status

• ✅ Milestone 1 – Project Setup
• ✅ Milestone 2 – Authentication & Dashboard
• ✅ Milestone 3 – GitHub Repository Analysis
• 🚧 Milestone 4 – Gemini AI Repository Insights (In Progress)

Note: The AI-powered repository insights feature is under active development. Core repository analysis and GitHub integration are fully functional.

Milestone 1 — Project scaffolding

• Clean, separated frontend/ and backend/ project structure
• Frontend: landing page (Navbar, Hero, Feature Cards, CTA, Footer) in a GitHub-inspired dark theme, fully responsive
• Backend: Flask app using the application-factory pattern, Blueprints, environment-based config, and a single /api/health route

Milestone 2 — Authentication & dashboard shell

• Backend: JWT authentication (register, login, logout, protected /api/auth/me), password hashing (Werkzeug/PBKDF2), MySQL via SQLAlchemy + Flask-Migrate, a users table only
• Frontend: Login and Register pages matching the existing design language, an AuthContext + ProtectedRoute for session handling, and a Dashboard (Sidebar, top navigation, Welcome card, and placeholder cards for Analyze Repository, Recent Activity, and Saved Repositories)

What's explicitly not included yet (later milestones):

• AI/Gemini-powered repository insights
• Intelligent codebase summarization and recommendations

Project structure

devlens-ai/
├── backend/
│   ├── app/
│   │   ├── __init__.py          # App factory (create_app)
│   │   ├── extensions.py        # Shared db / jwt / migrate instances
│   │   ├── config/
│   │   │   ├── __init__.py
│   │   │   └── config.py        # Environment-based config (incl. MySQL, JWT)
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   └── user.py          # User model (users table only)
│   │   ├── routes/
│   │   │   ├── __init__.py
│   │   │   ├── health_routes.py # /api/health blueprint
│   │   │   └── auth_routes.py   # /api/auth/* blueprint
│   │   └── utils/
│   │       ├── __init__.py
│   │       ├── validators.py        # Email/password validation
│   │       └── token_blocklist.py   # In-memory JWT blocklist (logout)
│   ├── .env.example
│   ├── .gitignore
│   ├── requirements.txt
│   └── run.py                   # Dev server entry point
│
└── frontend/
    ├── public/
    │   └── favicon.svg
    ├── src/
    │   ├── api/
    │   │   ├── apiClient.js         # Shared axios instance + auth header
    │   │   ├── authService.js       # register/login/logout/me calls
    │   │   └── healthService.js     # Calls /api/health
    │   ├── components/
    │   │   ├── Navbar.jsx           # Landing page
    │   │   ├── Hero.jsx             # Landing page
    │   │   ├── FeatureCards.jsx     # Landing page
    │   │   ├── CTASection.jsx       # Landing page
    │   │   ├── Footer.jsx           # Landing page
    │   │   ├── auth/
    │   │   │   ├── AuthCard.jsx     # Shared shell for Login/Register
    │   │   │   ├── FormField.jsx
    │   │   │   └── FormError.jsx
    │   │   └── dashboard/
    │   │       ├── Sidebar.jsx
    │   │       ├── TopNav.jsx
    │   │       ├── WelcomeCard.jsx
    │   │       ├── AnalyzeRepositoryCard.jsx   # Placeholder
    │   │       ├── RecentActivityCard.jsx      # Placeholder
    │   │       └── SavedRepositoriesCard.jsx   # Placeholder
    │   ├── context/
    │   │   └── AuthContext.jsx      # Auth state, login/register/logout
    │   ├── routes/
    │   │   └── ProtectedRoute.jsx   # Redirects to /login if unauthenticated
    │   ├── pages/
    │   │   ├── LandingPage.jsx
    │   │   ├── Login.jsx
    │   │   ├── Register.jsx
    │   │   └── Dashboard.jsx
    │   ├── styles/
    │   │   └── index.css
    │   ├── App.jsx                  # Routes
    │   └── main.jsx                 # Entry point (BrowserRouter + AuthProvider)
    ├── .env.example
    ├── .eslintrc.cjs
    ├── .gitignore
    ├── index.html
    ├── package.json
    ├── postcss.config.js
    ├── tailwind.config.js
    └── vite.config.js

Getting started

Backend

cd backend
python -m venv venv
source venv/bin/activate        # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # then edit MySQL credentials / secrets

Create the MySQL database (matching MYSQL_DB in your .env):

CREATE DATABASE devlens_ai CHARACTER SET utf8mb4;

Run migrations to create the users table:

export FLASK_APP=run.py         # On Windows: set FLASK_APP=run.py
flask db init
flask db migrate -m "Create users table"
flask db upgrade

Start the server:

python run.py

The API will be available at http://localhost:5000. Verify it's running:

curl http://localhost:5000/api/health

Auth endpoints

Method	Path	Auth required	Description
POST	/api/auth/register	No	Create a user, returns a JWT
POST	/api/auth/login	No	Exchange email + password for a JWT
POST	/api/auth/logout	Yes (Bearer)	Blocklists the current token
GET	/api/auth/me	Yes (Bearer)	Returns the logged-in user

Frontend

cd frontend
npm install
cp .env.example .env
npm run dev

The app will be available at http://localhost:5173. Visit /register to create an account, or /login if you already have one — both redirect to /dashboard on success.

Notes

• CORS on the backend is restricted to the origins listed in CORS_ORIGINS (set via .env), defaulting to the Vite dev server.
• The frontend reads the API base URL from VITE_API_BASE_URL, so the two services can be pointed at each other (or at staging/production URLs) without touching source code.
• Passwords are hashed with Werkzeug's PBKDF2-based hasher; plain-text passwords are never stored or logged.
• JWTs are stateless by design. Logout works by recording the token's jti in an in-memory blocklist, checked on every protected request. This is sufficient for a single dev/demo process — swap it for Redis (with a TTL matching JWT_ACCESS_TOKEN_EXPIRES_SECONDS) before running multiple workers or instances in production.
• The dashboard's "Analyze Repository", "Recent Activity", and "Saved Repositories" cards are intentionally static placeholders — wiring them up to real data is later milestones' work.