An AI-powered career guidance platform that takes you from "I don't know what fits me" to "I got the offer" — in one connected system.
Margito is a full-stack, AI-powered career guidance platform that combines six core features into a single, connected pipeline:
| Feature | What it does |
|---|---|
| Skill Profile | 8-step onboarding wizard collects your education, skills, experience, projects, and career goals into an analysis-grade profile |
| Career Recommendations | Hybrid AI engine ranks career roles by fit score — blending skill coverage, semantic similarity, and interest alignment |
| Learning Roadmap | Sequenced 4-stage timeline (Foundations → Core Skills → Projects → Interview Prep) with curated free resources and progress tracking |
| Resume Analyzer | ATS-style scoring with sub-scores (keyword match, formatting, completeness, action verbs, quantified impact) + improvement suggestions |
| Job Matching | Semantic job matching using pgvector cosine search across 100+ seeded job postings with real-time similarity scoring |
| AI Mock Interview | Real-time voice conversation with an AI interviewer that asks dynamic follow-ups, challenges your answers, and generates an in-depth performance report |
Why it's different: LinkedIn, Naukri, Internshala, and JobScan each solve one slice. Margito is the first end-to-end single-session pipeline: profile → skill gap → recommendation → roadmap → resume fix → job match → live AI mock interview with actionable feedback.
Every AI feature works with or without an API key:
- With Groq API key: LLM-enhanced explanations, dynamic interview conversations, in-depth reports
- Without API key: Rule-based fallbacks produce functional output for every feature — the app never breaks
A conversational AI interviewer that works entirely on free tiers:
- Browser Web Speech API for speech-to-text (free, no key)
- Groq streaming LLM generates dynamic follow-up questions in real-time
- Edge-TTS streaming plays audio responses as they're generated
- Real barge-in — interrupt the AI mid-sentence, it adapts and continues
- The interviewer challenges wrong answers, pushes for specifics, references your resume, and decides when to end
Not just name + skills. The onboarding wizard collects:
- Education (institution, graduation year, field of study)
- Career stage (student / fresher / working professional / career switcher / returning)
- Work preferences (remote/hybrid/on-site, full-time/part-time/contract)
- Projects with links, certifications, languages, portfolio links
- Resume upload with live ATS score preview and one-click auto-fill
- bcrypt passwords (12 rounds), JWT auth (HS256, 7-day expiry)
- httpOnly cookies — the browser never touches the token
- Every endpoint except health/auth requires a valid Bearer token
- Server-side validation on all inputs, sanitized error messages
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router) · TypeScript · Tailwind CSS v4 · framer-motion · lucide-react |
| Backend | FastAPI (Python 3.11+) · SQLAlchemy 2 (async) · asyncpg · Pydantic v2 |
| Database | PostgreSQL 17 + pgvector (hosted on Neon free tier) |
| AI — LLM | Groq (qwen/qwen3.6-27b) with rule-based fallbacks |
| AI — Embeddings | Scikit-learn HashingVectorizer (384-dim, zero cold start) |
| AI — STT | Browser Web Speech API (primary) · Groq Whisper (fallback) |
| AI — TTS | Edge-TTS (free, neural voices, streaming MP3 chunks) |
| Auth | bcrypt + python-jose JWT (HS256) + httpOnly cookies |
Zero-cost architecture: The entire platform runs on free tiers. The only optional cost is a Groq API key (free tier available), and the app works fully without it.
┌─────────────────────────────────────────────────────────┐
│ Browser (Next.js 16) │
│ ┌──────────┐ ┌──────────┐ ┌───────────────────────┐ │
│ │ Onboard │ │Dashboard │ │ Voice Interview │ │
│ │ Wizard │ │ Page │ │ (Web Speech STT + │ │
│ │ │ │ │ │ WS duplex + MP3) │ │
│ └──────────┘ └──────────┘ └───────────────────────┘ │
│ │ │ │ │
│ ┌────┴──────────────┴──────────────┴────┐ │
│ │ /api/* proxy (injects JWT cookie) │ │
│ └────────────────┬──────────────────────┘ │
└─────────────────────┼───────────────────────────────────┘
│ HTTP (same-origin) + WebSocket
▼
┌─────────────────────────────────────────────────────────┐
│ FastAPI Backend (:8000) │
│ │
│ ┌─────────┐ ┌────────────┐ ┌────────────────────────┐ │
│ │ Auth │ │ Profile │ │ Recommendation │ │
│ │ Service │ │ Analyzer │ │ Engine (hybrid) │ │
│ └─────────┘ └────────────┘ └────────────────────────┘ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Roadmap │ │ Resume │ │ Job Matcher │ │
│ │ Generator │ │ Scorer │ │ (pgvector) │ │
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Interview Agent (LLM + rule fallback) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │
│ │ │ LLM │ │ TTS │ │ STT (Whisper) │ │ │
│ │ │ (Groq) │ │(edge-tts)│ │ (fallback) │ │ │
│ │ └──────────┘ └──────────┘ └────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
└──────────────────────┼───────────────────────────────────┘
│ asyncpg + pgvector
▼
┌─────────────────────────────────────────────────────────┐
│ PostgreSQL 17 + pgvector (Neon) │
│ users · profiles · job_postings (vector) │
│ roadmap_progress · interview_sessions │
│ HNSW index for semantic search │
└─────────────────────────────────────────────────────────┘
Every feature works without external services, in this order:
- LLM available (Groq key set) → best output (natural-language reasoning, interview reports)
- LLM unavailable → rule-based output from local JSON + embeddings
- DB unavailable → job matching falls back to the on-disk seed file; everything else keeps working (only persistence/identity fails)
Career Guidance/
├── master_spec.md # Single source of truth (read first)
├── AGENTS.md # AI agent conventions + commands
├── PROGRESS.md # Running log of completed/in-progress tasks
├── DECISIONS.md # Engineering decisions log
├── .env.example # All env var names (no secrets)
│
├── docs/
│ ├── ARCHITECTURE.md # System design, data flow, security model
│ ├── API.md # Full REST API reference
│ ├── DATABASE.md # Postgres + pgvector schema & seeding
│ └── DEVELOPMENT.md # Setup, run, test, build, troubleshooting
│
├── backend/ # FastAPI service
│ ├── app/
│ │ ├── main.py # App entry, CORS, router registration
│ │ ├── config.py # pydantic-settings (env-driven)
│ │ ├── db.py # Async SQLAlchemy engine/session
│ │ ├── db_models.py # ORM tables (users, profiles, jobs, etc.)
│ │ ├── deps.py # get_current_user (JWT) dependency
│ │ ├── models/ # Pydantic request/response schemas
│ │ ├── routers/ # auth, profile, recommendations, roadmap,
│ │ │ # resume, jobs, interview, dashboard, health
│ │ ├── services/ # Business logic (see docs/ARCHITECTURE.md)
│ │ └── data/ # Curated JSON (skills, roles, learning resources) - no job corpus
│ ├── scripts/ # seed_db.py, create_indexes.py
│ └── tests/ # pytest suite (30+ tests)
│
└── frontend/ # Next.js 16 app
├── app/ # Routes (all feature pages + API proxy)
├── components/ # ui/, layout/, features/, onboarding/, motion/
└── lib/ # api-client.ts, auth.tsx, types.ts, use-voice-agent.ts
- Node.js 18+ and npm
- Python 3.11+
- PostgreSQL 17 with pgvector extension (Neon free tier recommended)
- Git
git clone <repository-url>
cd Career-Guidance
# Frontend
cd frontend
npm install
# Backend
cd ../backend
python -m venv .venv
# Windows
.\.venv\Scripts\Activate
# Linux / macOS
source .venv/bin/activate
pip install -r requirements.txtCopy the example and fill in your values:
# From the repo root
copy .env.example backend\.env # Windows
cp .env.example backend/.env # Linux / macOSRequired:
DATABASE_URL=postgresql://<user>:<password>@<host>/neondb?sslmode=require
SECRET_KEY=<long-random-string>Optional (everything works without it):
GROQ_API_KEY=gsk_... # Enables LLM-enhanced featurescd backend
python -m scripts.seed_db # Creates tables + profile-column migrations (seeds NO jobs)
python -m scripts.create_indexes # Builds HNSW index for semantic search# Terminal 1 — Backend
cd backend
python -m uvicorn app.main:app --reload --port 8000
# Terminal 2 — Frontend
cd frontend
npm run dev| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| Swagger Docs | http://localhost:8000/docs |
| Health Check | http://localhost:8000/health |
cd backend
python -m pytest tests -q- Tests run against a dedicated
margito_testdatabase (auto-created) - LLM calls are disabled in tests — all rule-based fallback paths are exercised
- 30+ tests cover: auth, profile, recommendations, roadmap, resume (text + upload), job matching, interview (Q&A + report + voice WS), authorization, and health
A guided flow that collects everything the AI engines need:
About you → Education → Skills (with proficiency 1-5) → Interests & work → Goals → Your story (resume upload with live ATS preview) → Extras (projects, certifications, languages) → Review
- Resume upload supports PDF, DOCX, TXT, and Markdown
- Parsed data auto-fills wizard fields with one click
- Skip any step — the app works with partial profiles
The hybrid recommendation engine scores 56 career roles using:
- Skill coverage (40%): matched required + nice-to-have skills vs your profile
- Semantic similarity (35%): cosine distance between your profile embedding and role embeddings
- Interest alignment (25%): keyword overlap between your interests and role descriptions
Explanations are LLM-enhanced when a Groq key is set, otherwise rule-based.
For your pinned target role, a 4-stage timeline:
- Foundations — core skills most roles share
- Core Skills — role-specific technical requirements
- Projects — portfolio-building with practical application
- Interview Prep — behavioral + technical practice
Each milestone includes curated free resources (Coursera, freeCodeCamp, LeetCode, etc.), estimated hours, and a completion checkbox. Progress persists per role.
ATS-style scoring across 5 dimensions:
- Keyword Match — role-relevant terms in your resume
- Formatting — section structure, parseability
- Section Completeness — experience, education, skills, projects, summary
- Action Verbs — 40+ strong verbs (led, built, designed, optimized...)
- Quantified Impact — numbers, percentages, metrics in achievements
Without a job description, weights redistribute to focus on formatting, completeness, and action verbs.
Semantic matching using pgvector cosine search:
- Your profile is embedded into 384-dim vector space
- 100+ seeded job postings are pre-embedded with the same model
- Cosine similarity gives a match score (0-100)
- Keyword overlap provides a fallback when embeddings are unavailable
A conversational AI agent, not a fixed Q&A loop:
Text mode: Type your answers, get dynamic follow-up questions Voice mode: Full-duplex real-time conversation:
- You speak → browser transcribes (Web Speech API)
- AI generates streaming response (Groq LLM)
- Response plays as audio (Edge-TTS, streaming MP3)
- You can interrupt mid-sentence (real barge-in)
- AI adapts based on your answers, challenges wrong answers, probes for specifics
Report includes:
- Overall score + verdict (Hire / Leaning Hire / Leaning No Hire / No Hire)
- 5 competency scores (Communication, Technical Depth, Structure, Problem Solving, Experience)
- Per-question breakdown with correctness tracking (correct / partially correct / incorrect)
- Interview insights (what went well, what to improve, surprising moments)
- Resume alignment assessment
- Action plan with specific suggestions
| Method | Path | Description |
|---|---|---|
GET |
/health |
Health check |
GET |
/content/roles |
All career roles |
GET |
/content/skills |
All skills with categories |
GET |
/content/resources |
Learning resources |
GET |
/content/stats |
Platform statistics |
POST |
/auth/register |
Create account |
POST |
/auth/login |
Log in |
| Method | Path | Description |
|---|---|---|
GET |
/auth/me |
Current user info |
GET/PUT |
/profiles/me |
Get/update profile |
POST |
/profiles/ |
Create profile |
GET |
/recommendations/me |
Career recommendations |
GET |
/roadmap/me |
Learning roadmap |
PUT |
/roadmap/me/progress |
Update roadmap progress |
POST |
/resume/analyze |
Analyze resume text |
GET |
/resume/me |
Get saved analysis |
POST |
/resume/upload |
Upload resume file |
GET |
/jobs/auto-fetch |
Auto-fetch real jobs |
POST |
/interview/sessions |
Create interview session |
POST |
/interview/sessions/{id}/answer |
Submit answer |
POST |
/interview/sessions/{id}/complete |
Generate report |
GET |
/interview/sessions |
List all sessions |
GET |
/interview/sessions/{id} |
Get session detail |
GET |
/dashboard/me |
Dashboard metrics |
| Path | Description |
|---|---|
WS /interview/sessions/{id}/ws |
Real-time voice interview |
Full API reference: docs/API.md
| Table | Purpose |
|---|---|
users |
Account credentials (bcrypt + JWT) |
profiles |
Full analysis-grade profile (30+ fields) |
job_postings |
provisioned (vector(384) + HNSW index) but holds no rows - live job data comes from external APIs |
roadmap_progress |
Per-user, per-role stage completion |
interview_sessions |
Session transcripts, reports, scores |
Full schema details: docs/DATABASE.md
Key engineering choices (full log in DECISIONS.md):
- PostgreSQL + pgvector over MongoDB — single relational store with native vector search
- Custom JWT auth over NextAuth — full control, fewer dependencies
- Local embeddings over paid API — free, no network dependency after one-time download
- Groq as LLM provider with rule-based fallbacks — works with zero API keys
- Browser Web Speech API for voice — free, no vendor lock-in
- Edge-TTS for speech synthesis — free neural voices, streaming MP3
- No external UI library — hand-rolled components with Tailwind v4 design tokens
| Document | What it covers |
|---|---|
master_spec.md |
Single source of truth — spec, status, stack, schema, API, algorithms |
AGENTS.md |
Conventions + commands for AI agents working in this repo |
docs/ARCHITECTURE.md |
System design, data flow, security model |
docs/API.md |
Full REST API reference (all endpoints, request/response shapes) |
docs/DATABASE.md |
PostgreSQL + pgvector schema & seeding |
docs/DEVELOPMENT.md |
Setup, run, test, build, troubleshooting |
DECISIONS.md |
Engineering decisions log |
PROGRESS.md |
Completed tasks, in-progress work, next steps |
DEPLOY.md |
Free deployment guide (Vercel + Render + keep-alive) |
| Metric | Value |
|---|---|
| Career Roles | 56 |
| Skills in Taxonomy | 267 |
| Skill Aliases | 94 |
| Learning Resources | 75 |
| Seeded Job Postings | 100 |
| Categories | 11 |
| Embedding Dimensions | 384 |
| Backend Tests | 30+ |
Margito runs entirely on free tiers. See the complete step-by-step guide:
DEPLOY.md — Vercel (frontend) + Render (backend) + Neon (database) + GitHub Actions keep-alive to prevent cold starts. Total cost: $0/month.
Quick summary:
- Push code to GitHub
- Deploy backend on Render (set
DATABASE_URL,SECRET_KEY,FRONTEND_URL) - Deploy frontend on Vercel (set
NEXT_PUBLIC_API_URLto your Render URL) - Enable the keep-alive cron job (prevents server sleeping)
- Done — your app is live
This project is for educational and demonstration purposes.
Built with care. Every feature works without external AI keys. The entire platform runs on free tiers.