Skip to content
krishnajaindevPublic

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Margito

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.


What is Margito?

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.


Key Highlights

Real AI, Real Fallbacks

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

Real-Time Voice Interview (Vapi-Style)

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

Analysis-Grade Profile

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

Security First

  • 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

Tech Stack

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.


Architecture

┌─────────────────────────────────────────────────────────┐
│                    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                          │
└─────────────────────────────────────────────────────────┘

The 3-Tier Resilience Model

Every feature works without external services, in this order:

  1. LLM available (Groq key set) → best output (natural-language reasoning, interview reports)
  2. LLM unavailable → rule-based output from local JSON + embeddings
  3. DB unavailable → job matching falls back to the on-disk seed file; everything else keeps working (only persistence/identity fails)

Project Structure

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

Getting Started

Prerequisites

  • Node.js 18+ and npm
  • Python 3.11+
  • PostgreSQL 17 with pgvector extension (Neon free tier recommended)
  • Git

1. Clone & Install

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.txt

2. Environment Variables

Copy the example and fill in your values:

# From the repo root
copy .env.example backend\.env    # Windows
cp .env.example backend/.env      # Linux / macOS

Required:

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 features

3. Seed the Database

cd 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

4. Run

# 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

Running Tests

cd backend
python -m pytest tests -q
  • Tests run against a dedicated margito_test database (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

Feature Deep Dive

1. Onboarding Wizard (8 Steps)

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

2. Career Recommendations

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.

3. Learning Roadmap

For your pinned target role, a 4-stage timeline:

  1. Foundations — core skills most roles share
  2. Core Skills — role-specific technical requirements
  3. Projects — portfolio-building with practical application
  4. 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.

4. Resume Analyzer

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.

5. Job Matching

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

6. AI Mock Interview

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

API Overview

Public Endpoints

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

Protected Endpoints (JWT required)

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

WebSocket

Path Description
WS /interview/sessions/{id}/ws Real-time voice interview

Full API reference: docs/API.md


Database Schema

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


Design Decisions

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

Documentation

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)

Platform Statistics

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+

Deploy for Free

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:

  1. Push code to GitHub
  2. Deploy backend on Render (set DATABASE_URL, SECRET_KEY, FRONTEND_URL)
  3. Deploy frontend on Vercel (set NEXT_PUBLIC_API_URL to your Render URL)
  4. Enable the keep-alive cron job (prevents server sleeping)
  5. Done — your app is live

License

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.

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages