DevCompass AI

Your AI Learning Companion — an AI-powered platform that generates personalized, structured learning roadmaps for AI/ML technologies.

Type a topic — LangGraph, CrewAI, PyTorch, anything AI-related — and DevCompass AI searches GitHub, YouTube, and arXiv, ranks the best resources, and uses AI to synthesize them into a complete learning path: prerequisites, a staged roadmap, hands-on project ideas, and a skill-gap analysis. A built-in chat assistant lets you ask follow-up questions about your specific roadmap.

Features

🔍 Topic-aware search — validates that a requested topic is AI-related before doing any work
📚 Multi-source resource collection — GitHub repositories, YouTube tutorials, arXiv papers, and official documentation, gathered and ranked independently
🗺️ AI-generated learning roadmap — staged learning path with difficulty, estimated time, and prerequisites
💡 Practical project ideas — Beginner, Intermediate, and Advanced project suggestions with implementation steps
🧭 Skill-gap analysis — identifies what you need to learn first, and how long it'll take
💬 Context-aware chat assistant — ask follow-up questions about your specific roadmap, grounded in the actual generated data
🎨 Modern, responsive UI — built with React, TypeScript, and Tailwind CSS

Architecture

DevCompass AI is a two-part system: an n8n workflow that does all resource collection and AI reasoning, and a React frontend that presents the results and adds an interactive chat layer.

┌─────────────────────┐           ┌──────────────────────────   ┐         ┌────────────────────┐
│   React Frontend    │  POST     │      n8n Workflow           │  calls  │   External APIs    │
│  (Vite + TypeScript)│ ──────►   │  (Topic validation, resource│ ──────► │  GitHub · YouTube ·│
│                     │           │   collection, AI reasoning) │         │  arXiv · Gemini    │
└─────────────────────┘           └──────────────────────────   ┘         └────────────────────┘
         │
         │  calls (separately, for chat only)
         ▼
┌─────────────────────┐
│  Vercel Serverless  │
│ Function (/api/chat)│  → calls Gemini directly, keeps API key server-side
└─────────────────────┘

A key design decision: the AI never searches the web directly. All resource collection (GitHub, YouTube, arXiv) happens through dedicated API pipelines before any LLM call. The AI's job is purely to reason over already-collected, already-ranked data — this keeps results grounded in real, verifiable sources rather than the model's own (potentially outdated or hallucinated) knowledge.

Tech Stack

Backend / Orchestration

n8n — workflow automation and orchestration
Google Gemini API — topic validation, resource ranking strategy, and roadmap synthesis
GitHub REST API, YouTube Data API v3, arXiv API — resource collection
Docker — n8n self-hosted deployment

Frontend

React 18 + TypeScript
Vite — build tooling
Tailwind CSS v4 — styling
React Router — client-side routing
Axios — HTTP client

Chat Feature

Vercel Serverless Functions — server-side proxy to Gemini, keeps the API key out of the browser

n8n Backend Workflow

The backend is implemented entirely in n8n using a modular, multi-stage pipeline. Resource collection and AI reasoning are deliberately separated — the AI only ever reasons over data that's already been gathered and ranked by rule-based logic.

Workflow Stages

1. Topic Validation A webhook receives the user's topic. An LLM call validates whether it's AI-related, and if so, normalizes it — returning is_ai_related, normalized_topic, display_name, aliases, topic_type, search_keywords, and related_technologies. Non-AI topics stop the workflow here.

2. Learning Resource Strategy Planner A second LLM call determines which resource types are actually worth searching for this topic (e.g. { "github": "VERY_HIGH", "youtube": "HIGH", "arxiv": "MEDIUM", "official_docs": "HIGH" }), and produces optimized search keywords and known official documentation.

3. GitHub Repository Pipeline Queries the GitHub API, then a rule-based ranking engine scores repositories by stars, activity, description relevance, and educational usefulness. Only the highest-ranked repos are kept.

4. arXiv Research Pipeline Queries the arXiv API, parses the XML response, and ranks papers by title/abstract relevance, keyword matching, and publication recency.

5. YouTube Learning Pipeline Queries the YouTube Data API and ranks videos by topic relevance, title, description, and channel quality.

6. Resource Integrator & Normalizer Combines GitHub, arXiv, and YouTube results into one standardized schema:

{
  "resource_type": "",
  "title": "",
  "description": "",
  "url": "",
  "priority": "",
  "metadata": {}
}

7. AI Learning Engine The primary reasoning stage. Given the validated topic, the resource strategy, and the normalized resource pool — but explicitly not allowed to search the web — this LLM estimates difficulty and total learning time, identifies prerequisites, organizes resources into a staged learning path, and generates practical learning tips.

8. AI Learning Companion A second LLM extends the roadmap with two outputs generated together: three progressively challenging project ideas (Beginner/Intermediate/Advanced, each with technologies and implementation steps), and a skill-gap analysis covering why each prerequisite matters, key concepts, preparation time, and recommended learning methods.

9. Final Response Builder Combines every stage's output into a single JSON response — topic info, roadmap, resources, projects, and skill-gap analysis — consumed directly by the React frontend.

Workflow Diagram

`` User Topic │ ▼ Topic Validator │ ▼ Learning Resource Strategy Planner │ ┌─────────────────┐ │ │ │ ▼ ▼ ▼ GitHub arXiv YouTube Collector Collector Collector │ │ │ Ranking Ranking Ranking └────────┼──────────┘ ▼ Resource Integrator & Normalizer ▼ AI Learning Engine ▼ AI Learning Companion ▼ Final Response Builder ▼ React Frontend ```

Design Principles (Backend)

Modular architecture — each resource source is an independent pipeline
Rule-based ranking before AI reasoning — cheaper, deterministic, and reduces what the LLM has to infer
Multiple specialized LLM calls instead of one large prompt — each stage has a narrow, well-defined job
Structured JSON communication between every workflow stage
The AI is never allowed to browse the web — it only reasons over resources the pipeline has already collected

Frontend

The React frontend consumes the n8n workflow's JSON output and presents it across a clean, tabbed dashboard.

Pages:

Home — search interface with topic suggestion chips, an explainer section, and the search entry point
Dashboard — a single-page results view with tabs: Overview (staged roadmap timeline), Official, GitHub, YouTube, Research Papers, Projects, and Skill Gap

Key frontend decisions:

All roadmap data is normalized client-side into consistent TypeScript types, since n8n's raw output uses keyed objects (e.g. { Beginner: {...}, Intermediate: {...} }) that are converted into arrays for easier rendering
Resource tabs display the full ranked resource pool gathered by the collectors (not just the AI's top picks), so users can browse every GitHub repo, video, and paper the pipeline found — not just a curated shortlist
Mock data (src/mock/sampleResponse.json) mirrors the real API shape exactly, enabling full UI development and testing independent of the live n8n backend

AI Chat Assistant

A floating chat widget on the Dashboard lets users ask questions about their specific, currently-generated roadmap — grounded in that roadmap's actual content, not a general-purpose assistant.

Why a separate serverless function instead of routing through n8n: a chat reply is a simple, stateless "send message → call LLM → return reply" operation, which fits a lightweight serverless function better than a full workflow execution. It also keeps the Gemini API key out of both the browser and n8n's request path for this specific feature — the key lives only in a Vercel environment variable, read exclusively inside /api/chat.ts, which runs server-side and is never bundled into client-side JavaScript.

Conversation history is capped to the last 8 messages per request, keeping token usage predictable regardless of how long a chat session runs.

Project Structure

`` DevCompass/ ├── frontend/ │ ├── api/ │ │ └── chat.ts # Vercel serverless function (Gemini chat proxy) │ ├── src/ │ │ ├── components/ │ │ │ ├── chat/ # ChatWidget │ │ │ ├── home/ # SearchBar, TopicChips, HowItWorks │ │ │ ├── layout/ # Navbar │ │ │ ├── roadmap/ # SummaryCard, LearningRoadmap, ResourceList, │ │ │ │ # ProjectCards, SkillGapPanel │ │ │ └── ui/ # Tabs, ResourceTypeBadge │ │ ├── mock/ │ │ │ └── sampleResponse.json # Realistic mock data matching the live API shape │ │ ├── pages/ │ │ │ ├── Home.tsx │ │ │ └── Dashboard.tsx │ │ ├── services/ │ │ │ ├── api.ts # n8n webhook call + response normalizer │ │ │ └── chatApi.ts # Chat API service │ │ └── types/ │ │ └── index.ts # Shared TypeScript interfaces │ ├── vercel.json │ └── vite.config.ts ├── docker/ │ └── n8n/ # n8n runtime data (gitignored) ├── workflow/ # Exported n8n workflow JSON └── docker-compose.yml


---

## Getting Started

### Prerequisites
- Node.js 18+
- Docker (for self-hosted n8n)
- A Google Gemini API key
- A YouTube Data API v3 key

### 1. Start the n8n backend
```bash
docker compose up -d

Import the workflow from workflow/ into n8n, add your Gemini and YouTube API credentials, and activate the workflow.

2. Configure the frontend

cd frontend
npm install
cp .env.example .env

Fill in .env:

VITE_N8N_WEBHOOK_URL=http://localhost:5678/webhook/learn-topic
GEMINI_API_KEY=your_key_here

3. Run locally

vercel dev

Note: use vercel dev rather than npm run dev if you want to test the chat feature locally, since it also serves the /api serverless function. Plain npm run dev works fine for everything except chat.

Visit http://localhost:3000.

Environment Variables

Variable	Where	Purpose
`VITE_N8N_WEBHOOK_URL`	`frontend/.env`	URL of the n8n production webhook
`GEMINI_API_KEY`	`frontend/.env` (server-side only, no `VITE_` prefix)	Used by `/api/chat.ts` — never exposed to the browser
`GEMINI_API_KEY`, `YOUTUBE_API_KEY`	`docker/.env` (or root `.env`)	Used by the n8n workflow's LLM and YouTube collector nodes

Design Principles

Separation of collection and reasoning — resource gathering is deterministic and rule-based; only synthesis is left to the AI
Never trust the AI with unverified facts — official documentation links are resolved from real collected data (e.g. a repo's homepage field) rather than recalled from the model's memory
Normalize early, render simply — all backend shape quirks (keyed objects, nested metadata) are converted to clean arrays in one normalization layer, so every component downstream works with predictable types
Secrets never touch the browser — any value used for authenticated API calls lives only in server-side code (n8n or the serverless function), never in a VITE_-prefixed variable

Security Notes

This project deliberately avoids two common mistakes:

n8n's local database (docker/n8n/database.sqlite*) and event logs are gitignored — this file can contain credentials and execution history and should never be committed
Only the Gemini key used for the chat feature lives in a frontend-adjacent .env file, and even then it is not VITE_-prefixed, so Vite never bundles it into client-side JavaScript

Future Enhancements

Saved/bookmarked roadmaps per user
Broader topic support beyond the current AI/ML scope
Streaming chat responses
Usage analytics dashboard
Additional resource sources (Hacker News, Reddit, technical blogs)

Screenshots

📸 Screenshots

Home	How It Works	Dashboard
Learning Roadmap	Official Documentation	GitHub Repositories
YouTube Resources	Research Papers	Project Generator
Skill Gap Analysis	AI Chat Assistant	Chat Response

---

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
docker/n8n		docker/n8n
frontend		frontend
screenshots		screenshots
.gitignore		.gitignore
Readme.md		Readme.md
docker-compose.yml		docker-compose.yml
image.png		image.png
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

DevCompass AI

Table of Contents

Features

Architecture

Tech Stack

n8n Backend Workflow

Workflow Stages

Workflow Diagram

Design Principles (Backend)

Frontend

AI Chat Assistant

Project Structure

2. Configure the frontend

3. Run locally

Environment Variables

Design Principles

Security Notes

Future Enhancements

Screenshots

📸 Screenshots

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

DevCompass AI

Table of Contents

Features

Architecture

Tech Stack

n8n Backend Workflow

Workflow Stages

Workflow Diagram

Design Principles (Backend)

Frontend

AI Chat Assistant

Project Structure

2. Configure the frontend

3. Run locally

Environment Variables

Design Principles

Security Notes

Future Enhancements

Screenshots

📸 Screenshots

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages