DevLens AI is a production-style developer intelligence platform. It combines source-aware static analysis, transparent repository health scoring, AI-assisted reviews, documentation generation, repository RAG, and GitHub workflows in a modular monolith designed to be split into services later.
The CI badge denotes the included GitHub Actions workflow; it intentionally makes no claim about a remote run before this repository is published.
- Email/password authentication with Argon2id hashing, short-lived JWTs, rotating HttpOnly refresh sessions, RBAC, audit trails, and protected APIs.
- GitHub OAuth repository discovery/import, branch sync, resilient GitHub API error mapping, and explicit confirmation before posting a PR comment.
- Asynchronous analysis jobs with FastAPI, Celery, Redis, PostgreSQL, pgvector, status transitions, idempotent demo data, and no long-running HTTP request.
- Source filtering, language detection for Python/JavaScript/TypeScript/Java/C++/C#/Go, Python AST parsing, generic symbol/import extraction, secret scanning, and concrete security/quality findings.
- Provider abstraction (
LLMProvider) for OpenAI-compatible chat/embedding APIs and a deterministic offline demo provider. Potential secrets are redacted before AI context is prepared. Ask your codebaseRAG with pgvector cosine search in PostgreSQL, source citations, and an explicit insufficient-context response.- Responsive Next.js dashboard with dark/light mode, React Query caching, Recharts-ready score cards, React Flow architecture graphs, and Monaco source inspection.
- Docker Compose, health/readiness checks, structured JSON logs, Alembic migration, CI/security workflows, tests, and operational documentation.
Add real screenshots after running the application locally. The repository deliberately does not use mock screenshots or fake performance claims.
flowchart TD
Browser[Next.js dashboard] --> API[FastAPI modular monolith]
API --> Auth[Auth and GitHub modules]
API --> Repo[Repository and PR modules]
API --> Queue[Redis / Celery queue]
API --> DB[(PostgreSQL + pgvector)]
Queue --> Worker[Analysis worker]
Worker --> GitHub[GitHub REST API]
Worker --> LLM[LLMProvider]
Worker --> DB
The API owns durable state; Redis is used only for queueing, rate limiting, OAuth state, and temporary cacheable state. The worker downloads source archives but never executes repository code. If a future version offers opt-in execution (for example, test runs), it must run in the deliberately constrained sandbox image described in security documentation.
| Area | Technologies |
|---|---|
| Web | Next.js, React, TypeScript strict mode, Tailwind, shadcn-style components, TanStack Query, React Flow, Monaco, Recharts |
| API | FastAPI, Pydantic, SQLAlchemy 2, Alembic, PostgreSQL, pgvector |
| Jobs | Celery and Redis |
| AI | Provider abstraction, OpenAI-compatible REST adapter, embeddings, pgvector RAG, offline deterministic demo provider |
| Quality | Ruff, Bandit-ready analysis, pytest, Vitest, GitHub Actions, Docker |
Prerequisites: Docker Desktop with Compose v2. For local non-container development, use Python 3.12+, Node 22+, PostgreSQL 16 with pgvector, and Redis 7+.
cp .env.example .env
docker compose up --buildOpen http://localhost:3000 and select Try demo workspace. The local demo user is demo@devlens.ai with password DemoPassword!123. It is seed data only; never retain or use this password in any deployed environment.
Services:
- Web dashboard:
http://localhost:3000 - API/OpenAPI:
http://localhost:8000/docs - Health:
http://localhost:8000/health - Readiness (checks PostgreSQL + Redis):
http://localhost:8000/ready
Copy .env.example. Required for a secure non-demo deployment:
| Variable | Purpose |
|---|---|
DATABASE_URL |
PostgreSQL SQLAlchemy URL; PostgreSQL must have pgvector available. |
REDIS_URL |
Celery, rate limiting, OAuth-state Redis URL. |
JWT_SECRET |
Long, unique JWT signing secret. |
TOKEN_ENCRYPTION_KEY |
Fernet key to encrypt GitHub OAuth tokens at rest; required in production. |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
GitHub OAuth application credentials. |
LLM_API_KEY |
OpenAI-compatible provider key. Omit it to use the labelled deterministic demo provider. |
NEXT_PUBLIC_API_URL |
Browser-visible API origin. |
DEMO_MODE=false, a production APP_ENV, allowed CORS_ORIGINS, TLS termination, and managed secrets are expected for a deployment.
# API
cd apps/api
python -m venv .venv
. .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[dev,analysis]"
alembic upgrade head
python -m app.scripts.seed
uvicorn app.main:app --reload
# worker (second terminal)
cd apps/api
celery -A app.workers.celery_app:celery_app worker --loglevel=INFO
# web (third terminal)
cd apps/web
npm install
npm run devCommon Make targets: make up, make down, make migrate, make seed, make test, and make lint.
cd apps/api && pytest && ruff check app tests && ruff format --check app tests
cd apps/web && npm test && npm run typecheck && npm run lint
docker compose -f docker-compose.yml configThe tests target authentication token rotation, static analysis behavior, deterministic demo embeddings, and UI score rendering. CI expands these checks with image builds and security scans. Critical logic deserves further integration tests as GitHub credentials and hosted environments are added.
FastAPI serves current OpenAPI UI at /docs; a concise endpoint guide is in docs/api.md. All application endpoints use this envelope:
{ "success": true, "data": {}, "message": "optional" }Errors never include stack traces:
{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests.", "details": {} } }flowchart LR
Source[Filtered source files] --> Parse[Parse / symbols / static findings]
Parse --> Chunk[Bounded code chunks]
Chunk --> Redact[Redact likely secrets before LLM]
Chunk --> Embed[Embeddings]
Embed --> Vector[(pgvector)]
Question --> QueryEmbed[Question embedding]
QueryEmbed --> Vector
Vector --> Context[Top relevant chunks]
Redact --> Review[AI review]
Context --> Answer[Answer + file/line citations]
Only filtered, size-bounded source code is considered. .env, .git, dependency directories, build artefacts, binary/invalid text, and oversized files are excluded. AI results are labelled as potential findings with confidence scores, while static/security sources remain distinct.
apps/
api/ FastAPI API, SQLAlchemy models, Alembic, services, worker tasks, tests
web/ Next.js developer dashboard
workers/analysis-worker/ isolated worker image definition
packages/ cross-runtime contract/config boundaries
infrastructure/ sandbox image and deployment guidance
docs/ architecture, database, security, RAG, operations docs
.github/workflows/ CI, security, and Docker checks
Passwords are never stored in plaintext; refresh tokens are SHA-256 stored and rotated; GitHub tokens are encrypted when TOKEN_ENCRYPTION_KEY is configured; secrets are not logged; protected endpoints are rate limited; and API responses contain safe error messages. See docs/security.md for controls and limitations.
DevLens is a developer-assistance tool—not a complete security audit or a replacement for production security review.
- Add Semgrep, lockfile/SBOM dependency scanners, and language-specific analyzers in worker images.
- Add GitHub webhook signature validation and incremental analysis on push/PR events.
- Add organization/workspace tenancy, SSO, fine-grained GitHub App permissions, and an external secrets manager integration.
- Scale worker queues by workload class; run pgvector HNSW tuning experiments; add metrics/traces/alerting.
- Add Playwright E2E tests, screenshot regression coverage, and production deployment manifests for AWS/Azure.
Read CONTRIBUTING.md and docs/contributing.md before opening a change. DevLens AI is available under the MIT License.