DevLens

From Code to Confidence.

AI-powered developer assessment platform for aspiring software engineers.

DevLens analyses your GitHub repositories, builds a deterministic evidence graph from your engineering artifacts, and translates it into a Developer Readiness score — with AI-generated explanations grounded entirely in evidence, not guesswork.

Getting Started · Features · Architecture · API Reference · Contributing

What is DevLens?

Most developers struggle to communicate their engineering ability. Portfolios feel hollow, self-assessments are biased, and recruiters cannot easily evaluate raw code quality at scale.

DevLens solves this by turning your public GitHub history into verified, structured evidence.

"Every score is backed by evidence. Every weakness has an explanation. Every recommendation is actionable."

Who is it for?

2nd–4th year Computer Science students preparing for internships and first jobs
Fresh graduates looking to confidently present their skills
Self-taught developers wanting an objective measure of portfolio readiness

Core Features

Feature	Description
GitHub Analysis Pipeline	Fetches repositories, commit history, languages, and file structure via GitHub GraphQL/REST API
Evidence Graph	Deterministic detector system that converts raw engineering artifacts into scored evidence nodes
Developer Readiness Score	Composite 0–100 score across 6 pillars: Quality, Maturity, Practices, Breadth, Professionalism, Growth
Repository Intelligence	Per-repository analysis of framework, CI/CD, testing, TypeScript usage, Docker, and deployment
AI Explanations	OpenRouter-powered, evidence-grounded natural language explanations per assessment section
AI Recommendations	Structured, prioritised action items with estimated score impact
Portfolio Readiness	Role-specific (frontend/backend/fullstack) readiness evaluation
Dual Theme System	Dark mode (obsidian) + Light mode (`#ECE6CD` warm parchment) with Skiper UI animated toggle switches
Skiper UI Motion Suite	Spotlight cards, border beams, interactive hover buttons, and spring-animated counters
Command Palette (`⌘K`)	Fast keyboard-driven command navigation and action shortcuts
Assessment History	Versioned immutable score snapshots across sync runs

Design & Motion System

DevLens features a custom dual-theme design system and interactive micro-animations powered by Skiper UI and Framer Motion:

Warm Parchment Light Theme (#ECE6CD): Custom-tailored cream background with #F6F1DF / #FAF6E8 elevated card surfaces, high-contrast dark charcoal typography (#1C1917 / text-zinc-900), and warm amber borders (border-amber-900/15).
Obsidian Dark Theme: Pure deep black surface architecture (#08080a, #0d0d0d, #111115) with crisp white accents.
Skiper UI Theme Toggles: Multi-variant SVG morphing toggle buttons with spring mechanics and smooth icon transitions.
Interactive Motion Primitives:
- SpotlightCard: Dynamic cursor-tracking radial spotlight glow.
- BorderBeam: Glowing animated border ray along card perimeters.
- InteractiveHoverButton: Expanding arrow hover physics.
- AnimatedNumber: Spring-physics score tweening with delta indicators.
- TimeRangeFilter: Sliding layoutId active pill switcher.

GitHub Analysis Pipeline

GitHub API (GraphQL + REST)
    │
    ▼
Profile & Repository Ingestion
    │  (5-repo concurrency, Zod validation)
    ▼
Repository Intelligence Generation
    │  (framework, CI/CD, TypeScript, Docker, testing detectors)
    ▼
Evidence Graph Construction
    │  (documentation, readme, typescript, metadata, license detectors)
    ▼
Readiness Assessment Engine
    │  (6 weighted pillar scorers)
    ▼
Developer Score Computation (0–100) + Grade (S/A/B/C/D)
    │
    ▼
Recommendation Generation
    │
    ▼
AI Context Builder → OpenRouter → AI Explanations & Recommendations

The pipeline is triggered on demand via POST /api/sync/github. All intermediate results are persisted in MongoDB for instant subsequent access.

AI Capabilities

DevLens uses OpenRouter as its AI gateway, routing requests to configurable LLMs (default: openai/gpt-4o-mini).

Critical design principle: The LLM is not the source of truth. Deterministic engineering evidence is the source of truth. AI explanations are generated from pre-computed evidence — the LLM interprets structured data, it does not assess code directly.

AI Explanation Engine — Generates natural language explanations for each assessment section (overall, quality, maturity, practices, breadth, etc.), grounded in real evidence nodes
AI Recommendation Engine — Produces structured, prioritised recommendations with supporting evidence and estimated score impact
Deterministic Fallback — If the API key is absent or OpenRouter fails, the system synthesises evidence-grounded explanations from the data itself — no degraded experience
Per-run Caching — Explanations are cached in MongoDB against their runId, preventing redundant API calls

Screenshots

Screenshots are located in the /screenshots directory. See docs/RELEASE_ASSETS.md for the full asset checklist and capture instructions.

Architecture

DevLens is an event-informed modular monolith deployed on Vercel serverless infrastructure.

Browser
    │  HTTPS
    ▼
Vercel Edge (Middleware: auth guard, route protection)
    │
    ├── Next.js App Router (Server Components — zero client JS for data rendering)
    │       └── /dashboard, /dashboard/assessment, /dashboard/portfolio
    │
    └── Route Handlers (serverless API)
            ├── /api/auth/[...all]       (Better Auth)
            ├── /api/sync/github         (GitHub ingestion trigger)
            ├── /api/dashboard           (aggregated dashboard data)
            ├── /api/assessment/*        (detail, history, compare)
            ├── /api/evidence/*          (evidence nodes & graph)
            ├── /api/ai/*               (explain, recommend)
            ├── /api/repositories/*      (per-repo intelligence)
            └── /api/portfolio/readiness (role-specific evaluation)
                    │
                    ▼
            Domain Services
            ├── GitHub Service      → GitHub GraphQL/REST API
            ├── Evidence Engine     → Detector pipeline
            ├── Readiness Engine    → 6-pillar scorer
            ├── Assessment Service  → Score computation & persistence
            └── AI Feature          → Context builder → OpenRouter
                    │
                    ▼
            MongoDB Atlas (Mongoose ODM)

Folder Structure

src/
├── app/                    # Next.js 16 App Router
│   ├── api/                # Route Handlers (serverless endpoints)
│   ├── dashboard/          # Protected dashboard pages
│   ├── login/              # Authentication page
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Landing page
├── features/               # Feature-sliced domain modules
│   ├── ai/                 # AI explanation & recommendation engine
│   │   ├── cache/          # MongoDB-backed explanation cache
│   │   ├── context/        # Context builder (assembles evidence for LLM)
│   │   ├── prompts/        # System & user prompt templates
│   │   ├── providers/      # OpenRouter API client
│   │   ├── services/       # explanation.service, recommendation.service
│   │   └── config.ts       # AI config (model, temp, max tokens)
│   ├── assessment/         # Assessment detail & UI components
│   ├── auth/               # Better Auth integration & session helpers
│   ├── dashboard/          # Dashboard data aggregation
│   ├── evidence/           # Evidence graph engine
│   │   ├── detectors/      # Per-signal detectors (readme, typescript, license…)
│   │   ├── engine/         # Detector registry & evidence runner
│   │   ├── graph/          # Evidence node & relationship models
│   │   └── normalizers/    # Raw data → evidence normalisation
│   ├── portfolio/          # Portfolio readiness evaluation
│   ├── profile/            # User profile management
│   ├── readiness/          # 6-pillar readiness scoring engine
│   │   ├── scorers/        # quality, maturity, practices, breadth, professionalism, growth
│   │   └── engine/         # Readiness engine orchestrator
│   ├── repositories/       # Repository intelligence generation
│   └── settings/           # User settings
├── services/               # Backend integration services
│   ├── ai/                 # (reserved for future AI service expansion)
│   ├── assessment/         # dashboard.service, history.service, run-assessment.service
│   ├── github/             # GitHub client, sync-service, profile/repo/readme/language services
│   ├── portfolio/          # Portfolio analysis service
│   ├── resume/             # Resume parser (future)
│   └── storage/            # UploadThing file storage
├── models/                 # Mongoose schema definitions
├── lib/                    # Shared utilities
│   ├── auth/               # Better Auth server instance
│   ├── db/                 # MongoDB connection helper
│   └── validations/        # Zod schemas
├── config/                 # App configuration
├── constants/              # Frozen application constants
├── hooks/                  # Shared React hooks
├── providers/              # React context providers
├── types/                  # Global TypeScript types
└── proxy.ts                # Next.js middleware (route protection)

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript 5 (Strict Mode)
Styling	Tailwind CSS v4
Theming	next-themes (Obsidian Dark + `#ECE6CD` Light)
UI Components	shadcn/ui + Base UI
Motion System	Skiper UI + Framer Motion
Icons	Lucide React
Authentication	Better Auth
Database	MongoDB Atlas + Mongoose
AI Gateway	OpenRouter (via native fetch)
File Upload	UploadThing
Validation	Zod v4
Forms	React Hook Form
Testing	Vitest
Deployment	Vercel

Getting Started

Prerequisites

Node.js >= 18.18.0
npm >= 10.0.0
MongoDB Atlas account (free tier works)
GitHub OAuth App credentials

Installation

1. Clone the repository:

git clone <repository-url>
cd devlens

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env.local

Open .env.local and fill in your credentials. See Environment Variables for details.

4. Run the development server:

npm run dev

Open http://localhost:3000 in your browser.

Environment Variables

Variable	Required	Description
`NEXT_PUBLIC_APP_URL`	Yes	Public app URL (e.g. `http://localhost:3000`)
`MONGODB_URI`	Yes	MongoDB Atlas connection string
`BETTER_AUTH_SECRET`	Yes	32+ char random secret for session signing
`BETTER_AUTH_URL`	Yes	App base URL for OAuth callbacks
`GITHUB_CLIENT_ID`	Yes	GitHub OAuth App client ID
`GITHUB_CLIENT_SECRET`	Yes	GitHub OAuth App client secret
`OPENROUTER_API_KEY`	No*	OpenRouter API key for AI features
`AI_PROVIDER`	No	AI provider name (default: `openrouter`)
`AI_MODEL`	No	Model identifier (default: `openai/gpt-4o-mini`)
`AI_MAX_TOKENS`	No	Max tokens per request (default: `1000`)
`AI_TEMPERATURE`	No	Sampling temperature (default: `0.3`)
`AI_EXPLANATION_CACHE`	No	Set to `false` to disable caching (default: enabled)
`UPLOADTHING_TOKEN`	No	UploadThing token for file uploads
`UPLOADTHING_SECRET`	No	UploadThing secret
`UPLOADTHING_APP_ID`	No	UploadThing app ID

*Without OPENROUTER_API_KEY, the AI features use a deterministic evidence-grounded fallback that still produces useful output.

See .env.example for setup instructions and how to obtain each credential.

Testing

# Run all tests
npm run test

# Run tests with coverage report
npm run test:coverage

Tests are located in the /tests directory and cover:

Evidence detectors (readme, documentation, typescript, license, metadata)
Repository intelligence detectors
Readiness scorers (all 6 pillars)
Readiness engine orchestration
AI explanation and recommendation synthesis
Portfolio readiness evaluation
Evidence graph adapter

Development Scripts

Command	Description
`npm run dev`	Start Next.js development server
`npm run build`	Build production bundle
`npm run start`	Start production server
`npm run lint`	Run ESLint
`npm run lint:fix`	Auto-fix ESLint errors
`npm run format`	Format code with Prettier
`npm run format:check`	Check formatting
`npm run typecheck`	TypeScript type check
`npm run test`	Run Vitest test suite
`npm run test:coverage`	Run tests with V8 coverage
`npm run prepare`	Initialise Husky git hooks

Roadmap

v1.0 (Current)

Phase 2 (Planned)

Engineering Standards

Strict TypeScript — strict: true, no any unless explicitly justified
Service isolation — External APIs (AI, storage, GitHub) wrapped in services
Zod validation — All inputs validated at the boundary before persistence
Feature-based architecture — Domain logic lives in features/, business services in services/
Git hooks — Pre-commit ESLint and Prettier enforcement via Husky

License

MIT — See LICENSE for details.

Contributing

See CONTRIBUTING.md for development setup, branch strategy, and pull request expectations.

Name		Name	Last commit message	Last commit date
.husky		.husky
docs		docs
prompts		prompts
public		public
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
lint-staged.config.mjs		lint-staged.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

DevLens

From Code to Confidence.

What is DevLens?

Who is it for?

Core Features

Design & Motion System

GitHub Analysis Pipeline

AI Capabilities

Screenshots

Architecture

Folder Structure

Tech Stack

Getting Started

Prerequisites

Installation

Environment Variables

Testing

Development Scripts

Roadmap

v1.0 (Current)

Phase 2 (Planned)

Engineering Standards

License

Contributing

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

DevLens

From Code to Confidence.

What is DevLens?

Who is it for?

Core Features

Design & Motion System

GitHub Analysis Pipeline

AI Capabilities

Screenshots

Architecture

Folder Structure

Tech Stack

Getting Started

Prerequisites

Installation

Environment Variables

Testing

Development Scripts

Roadmap

v1.0 (Current)

Phase 2 (Planned)

Engineering Standards

License

Contributing

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages