Skip to main content
Glama
Ambuj123-lab

Ambuj Systems - Career Workspace

README.md
<div align="center">

<!-- Animated Header Banner -->
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=10,12,14,16,18&height=220&section=header&text=CoverCraft%20Workspace&fontSize=42&fontColor=ffffff&fontAlignY=35&desc=Evidence-Grounded%20Career%20Workspace%20โ€ข%20Claim-Validation%20Engine%20โ€ข%20Real-Time%20Company%20Intelligence&descSize=15&descAlignY=55&animation=fadeIn" width="100%"/>

<br/>

<a href="https://git.io/typing-svg"><img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=20&pause=1000&color=6EE7B7&background=00000000&center=true&vCenter=true&repeat=true&width=750&height=70&lines=Evidence-Grounded+Generation+%E2%80%A2+Claim+Validation;Tavily+8-Page+Crawl+%2B+Jina+AI+Reader+Markdown+Extractor;Third-Party+%26+Payroll+Detection+via+Verbatim+JD+Quotes;Anthropic+MCP+Server+%2B+Next.js+16+Multi-Stage+Docker" alt="Typing SVG" /></a>

<br/>

[![Live Production Demo](https://img.shields.io/badge/LIVE_PRODUCTION-Visit_App-059669?style=for-the-badge&logoColor=white)](https://career-workspace-ambujsystems.vercel.app/)
[![Interactive System Docs](https://img.shields.io/badge/INTERACTIVE_DOCS-System_Architecture-2563EB?style=for-the-badge)](https://career-workspace-ambujsystems.vercel.app/docs)
[![GitHub Release](https://img.shields.io/github/v/release/Ambuj123-lab/career-workspace-ambujsystems?color=10b981&label=Release&style=for-the-badge&logo=github)](https://github.com/Ambuj123-lab/career-workspace-ambujsystems/releases/latest)
[![Uptime SLA 99.998%](https://badge.uptimerobot.com/sla/18a544b11fc4799a468704cc7acccedb.svg?theme=dark)](https://stats.uptimerobot.com/4tYmSQnuBE?utm_source=status_badge&utm_medium=referral)
[![Product Hunt](https://img.shields.io/badge/Product_Hunt-Live_Launch-FF6154?style=for-the-badge&logo=producthunt&logoColor=white)](https://www.producthunt.com/products/covercraft-ai-3)
[![Featured on UptimeRobot](https://img.shields.io/badge/FEATURED_IN-UptimeRobot_Official_Blog-047857?style=for-the-badge&logo=uptimerobot&logoColor=3BD671)](https://uptimerobot.com/blog/community-spotlight-ambuj-kumar-tripathi/)
[![M8ven Verified](https://m8ven.ai/badge/mcp/ambuj123-lab/career-workspace-ambujsystems?variant=verified)](https://m8ven.ai/mcp/ambuj123-lab/career-workspace-ambujsystems)
[![Author Portfolio](https://img.shields.io/badge/PORTFOLIO-Ambuj_Tripathi-8B5CF6?style=for-the-badge)](https://ambuj-ai-portfolio.vercel.app/)

<br/>

[![Next.js 16](https://img.shields.io/badge/Next.js-16.1.6-black?style=flat-square&logo=next.js)](https://nextjs.org/)
[![React 19](https://img.shields.io/badge/React-19.0.0-61DAFB?style=flat-square&logo=react)](https://react.dev/)
[![Google Gemini API](https://img.shields.io/badge/Gemini_API-3.5_Flash_Lite-4285F4?style=flat-square&logo=google)](https://ai.google.dev/)
[![Multi-Provider Fallback](https://img.shields.io/badge/Fallback-OpenRouter_Nemotron_550B-7C3AED?style=flat-square)](https://openrouter.ai/)
[![Tavily AI Search](https://img.shields.io/badge/Tavily_AI-8--Page_Web_Crawl-0ea5e9?style=flat-square)](https://tavily.com/)
[![Jina AI Reader](https://img.shields.io/badge/Jina_AI-Markdown_Extractor-blueviolet?style=flat-square)](https://jina.ai/)
[![MongoDB Atlas](https://img.shields.io/badge/MongoDB-Atlas_Telemetry-47A248?style=flat-square&logo=mongodb)](https://www.mongodb.com/atlas)
[![Langfuse Observability](https://img.shields.io/badge/Langfuse-LLM_Observability-black?style=flat-square&logo=langfuse)](https://langfuse.com/)
[![GitHub MCP Proofer](https://img.shields.io/badge/GitHub_MCP-Commit_Auditor-181717?style=flat-square&logo=github)](https://github.com/)
[![Docker](https://img.shields.io/badge/Docker-Multi--Stage_120MB-2496ED?style=flat-square&logo=docker)](https://docker.com)
[![Vercel Edge](https://img.shields.io/badge/Vercel-Serverless_Edge-000000?style=flat-square&logo=vercel)](https://vercel.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

</div>

---

## ๐ŸŽฏ The Engineering Philosophy

### โŒ The "Toy AI Generator" Fallacy
99% of cover letter tools on the internet are simple prompt wrappers that cause immediate disqualification during technical recruiter screens:
- **Hallucinated Metrics:** They invent fake quantitative claims (*"Increased revenue by 43% using Docker"* when the candidate only listed Docker under skills).
- **Fluff & Sycophancy:** They inject generic, embarrassing praise (*"I have long admired your revolutionary, industry-defining synergy"*).
- **Zero Company Grounding:** They have no real-time awareness of recent engineering pivots, active tech stacks, or corporate subsidiaries.
- **Hidden Third-Party Traps:** They fail to detect when a job posting is a third-party staffing/payroll agency disguised as a direct employer.

### โœ… The CoverCraft Architecture: Verifiable Evidence Graph
**CoverCraft is not a template filler. It is an Evidence-Grounded Career Workspace & Claim-Validation Engine designed for senior engineers and discerning hiring teams.**

```
Candidate Resume (PDF)          Job Description (JD)           Live Web (Tavily + Jina AI)
        โ”‚                               โ”‚                                 โ”‚
        โ–ผ                               โ–ผ                                 โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”           โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”             โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Deterministic    โ”‚           โ”‚ Deterministic    โ”‚             โ”‚ 8-Page Multi-Board โ”‚
โ”‚ Text & Evidence  โ”‚           โ”‚ Fallback Regex   โ”‚             โ”‚ Crawl & Markdown   โ”‚
โ”‚ Extraction Layer โ”‚           โ”‚ & Vendor Auditor โ”‚             โ”‚ Deep Extraction    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜           โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜             โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
          โ”‚                             โ”‚                                 โ”‚
          โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                        โ”‚
                                        โ–ผ
                        โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                        โ”‚   Human-in-the-Loop Gateway     โ”‚
                        โ”‚   (Source Approval & Selection) โ”‚
                        โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                        โ”‚
                                        โ–ผ
                        โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                        โ”‚   Evidence-Grounded Generator   โ”‚
                        โ”‚   โ€ข Strict Verbatim Anchors     โ”‚
                        โ”‚   โ€ข Evidence-Grounded Claim Validation โ”‚
                        โ”‚   โ€ข Citation Footnotes [1], [2] โ”‚
                        โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                        โ”‚
                                        โ–ผ
                        โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                        โ”‚   Interview-Defensible Output   โ”‚
                        โ”‚   (Every claim backed by facts) โ”‚
                        โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## โšก Core Architectural Pillars

### 1. Multi-Source Real-Time Intelligence & Deep Markdown Crawling
- **Tavily 8-Page Authoritative Crawl:** Queries live enterprise footprints targeting `careers`, `linkedin`, `naukri`, and `ambitionbox`.
- **Jina AI Reader (`r.jina.ai`) Deep Scraping:** Strips HTML clutter, popups, and cookie walls, returning clean, high-fidelity markdown with an exponential timeout fallback.
- **Three-Tier Domain Classifier:** Categorizes incoming intelligence into **Company Official**, **Job Portals & Reviews**, and **External Engineering News**.

### 2. Deterministic Fallback Regex & 4-Tier Company Intelligence
When LLM JSON structures are delayed or partially populated, a deterministic regex pipeline extracts ground truth directly from raw JD tokens:
- **๐Ÿ“‹ Job Context Sub-Tab (Default):** Extracts Role, Work Model (Remote / Hybrid / On-Site), Experience Band, and Disclosed Salary Status.
- **โš ๏ธ Third-Party / Staffing Detection:** Flags staffing vendors, C2H (Contract-to-Hire), and payroll intermediaries with **verbatim quotes** directly extracted from the JD.
- **๐Ÿข Company Identity Sub-Tab:** Verifies whether the firm is a Direct Employer, Services Vendor, GCC (Global Capability Center), or Product Company. Missing fields strictly report `"Not verified from available sources"`.
- **โšก Hiring Signals Sub-Tab:** Isolates technology focuses, active initiatives, and recent hiring surges with cited references `[1]`, `[2]`.
- **๐Ÿ”— Sources Coverage Sub-Tab:** Displays full URL citations and scrape statuses.

### 3. Evidence-Grounded Generation, UX & Claim Validation Policy
- **Evidence-Grounded Synthesizer:** System instructions enforce that **every single achievement claim** in the cover letter must map directly to a verified bullet in the candidate's resume.
- **Interactive In-Line Evidence Markers with Clean Submission Export:** On-screen interactive badges (`[Resume Anchor]` & `[Source Citation]`) allow candidates to hover and verify exact source quotes with a live `[Evidence Markers: ON/OFF]` toggle. When candidates click **Copy to Clipboard** or **Download Markdown/PDF**, internal citation tags are **automatically stripped** to deliver 100% clean, submission-ready letters for recruiters.
- **Adversarial Overclaim Red-Teamer (Veracity Audit Gate):** Scans generated text against candidate resume verbs to catch senior inflation (e.g., resume states "assisted team with Kubernetes rollout" vs draft stating "spearheaded enterprise migration"). The engine automatically softens unverified verbs to authentic baseline evidence and records an audit log.
- **Live Step Progress Tracker & Dynamic Elapsed Timer:** An event-driven 4-phase execution tracker (`01. Competency Match` โ†’ `02. MCP Company Research` โ†’ `03. Human Approval` โ†’ `04. Evidence Synthesis`) with a live counting timer (`00:04s`) and active tool indicator so candidates clearly follow live execution without confusion or perceived stalls.
- **Human-in-the-Loop (HITL) Gate:** Users explicitly inspect, evaluate credibility scores, and toggle on/off scraped web sources before any external intelligence enters the LLM generation prompt.

### 4. Native Model Context Protocol (MCP) Integration (7 Production Tools)

> [!TIP]
> **๐Ÿ›ก๏ธ M8ven MCP Trust Index Verified Publisher (Score 89/100 ยท Grade B):**  
> CoverCraft's FastMCP server and its 8 registered tools have been independently audited on the public [M8ven MCP Trust Index](https://m8ven.ai/mcp/ambuj123-lab/career-workspace-ambujsystems) with **Score 89/100 (Grade B - Emerging)**, **0 Security Findings**, and continuous live push monitoring.  
> 
> [![M8ven Score](https://m8ven.ai/badge/mcp/ambuj123-lab/career-workspace-ambujsystems)](https://m8ven.ai/mcp/ambuj123-lab/career-workspace-ambujsystems)
> [![M8ven Verified](https://m8ven.ai/badge/mcp/ambuj123-lab/career-workspace-ambujsystems?variant=verified)](https://m8ven.ai/mcp/ambuj123-lab/career-workspace-ambujsystems)

- Contains a standalone **Anthropic Model Context Protocol (MCP)** server written in Python 3.11 (`mcp-server/`).
- Exposes **8 Registered Tools** via standard Model Context Protocol **stdio transport** and **Streamable HTTP SSE transport**:
  1. `company_research`: Real-time web search via Tavily with traceable source citations.
  2. `evidence_validator`: Claim Ledger validation against source data returning `VERIFIED` / `PARTIAL` / `UNSUPPORTED`.
  3. `jd_analyzer`: Evidence-backed JD matching against resume with actual proof anchors.
  4. `ats_readiness`: Deterministic heuristic audit on keyword coverage, format integrity, and length.
  5. `source_filter`: Algorithmic domain authority tiering, noise suppression, and Outdated News & Stale Tech Filter (<9m company initiatives, <18m engineering stack, [Historical Context] tag).
  6. `cover_letter_generator`: Evidence-grounded synthesis with structured in-line citation markers and zero-overclaim enforcement.
  7. `github_proofer`: Real-time candidate GitHub portfolio & commit history verification engine ($0 free tier PAT, 5,000 req/hr). Inspects public repositories, extracts commit SHAs and messages, and anchors resume technical claims directly into verifiable code evidence with zero overclaiming.
  8. `huggingface_proofer`: Autonomous GenAI model & weights verification engine ($0 free tier HF Token, 30,000 req/hr). Inspects candidate's public Hugging Face models, spaces, datasets, and aggregate download metrics (e.g. 700+ model downloads, qLoRA fine-tuning, GGUF quantization), cross-referencing AI claims against verifiable weights.
- Dual-transport support: run locally with Claude Desktop/Cursor via `stdio_server` or deploy as an independent streaming microservice using `--transport=sse`.

### 5. Live GitHub Code Proof & Commit Auditor (MCP Tool #7)
- **Verifiable Public Code Evidence:** Connects to candidate GitHub profile via official GitHub MCP tool (`mcp-server/tools/github_proofer.py`) and Next.js route `/api/github-verify`.
- **Commit-Level Hashing:** Extracts real-time commit SHAs (e.g. `sha: 7f2a1b9`), commit messages, repository descriptions, and architecture files to ground technical claims in verifiable code history.
- **Zero-Cost Free Tier:** Powered by a GitHub Personal Access Token (PAT) with read-only public scope, unlocking 5,000 req/hr at **$0 cost** with 100% reliable rate limit isolation.
- **Adversarial Overclaim Sentinel:** If a candidate claims a framework without public repository or commit proof, CoverCraft flags the gap and prompts the applicant for clarification rather than hallucinating fictitious enterprise experience.

### 6. Autonomous Hugging Face Weights & Model Auditor (MCP Tool #8)
- **Verifiable Open-Source Weights & Models:** Connects to candidate Hugging Face profile via official MCP tool (`mcp-server/tools/huggingface_proofer.py`) and Next.js route `/api/hf-verify`.
- **Real-World Download & Community Proof:** Audits real community adoption metrics (e.g. 726+ model downloads, 39 community likes/stars), cross-referencing GenAI claims (fine-tuning, LoRA, QLoRA, GGUF quantization, Legal AI) against verifiable downloadable weights.
- **Interactive AI Demo Grounding (Gradio Spaces):** Inspects candidate's live interactive Gradio spaces (e.g. `ambuj-ai-chatbot`, `legal-india-chatbot`), mathematically verifying live model deployment and edge inference capabilities.
- **Zero-Cost Free Tier API:** Powered by Hugging Face user access tokens ($0 free tier) delivering 30,000 req/hr with 5-minute stale-while-revalidate caching and high-availability fallback.
- **Anti-Overclaim Sentinel:** Distinguishes candidates who merely prompt commercial APIs from true AI engineers who fine-tune, quantize, and ship real weights with community traction.

### 7. Candidate Privacy-First Architecture & Dual Auto-Extraction Engine
- **PII Hardening & Phone Number Removal:** Mobile phone numbers have been completely removed from the UI and backend schemas to preserve applicant privacy.
- **Dual Intelligent Auto-Extraction:**
  - **Resume Ingestion Auto-Fill (`/api/parse-resume`):** Auto-extracts candidate Name, Email, LinkedIn URL, and GitHub Profile URL from uploaded PDF resumes via regex + LLM extraction, pre-filling the generator form.
  - **Job Description Auto-Detection (`InputForm.jsx`):** Automatically detects target Role and Company Name as soon as a user pastes a Job Description, eliminating redundant manual typing.

### 8. Production Observability: Langfuse LLM Tracing & MongoDB Atlas
- **Langfuse LLM Observability & Tracing:** Full-trace telemetry capturing end-to-end generation latency, prompt/completion token consumption, Gemini model parameters, and span-level child traces across all 8 MCP tool operations.
- **Resilient Non-Blocking Execution:** Observability spans execute in protected async try/catch blocks; if network limits occur, generation continues seamlessly with zero user latency impact.
- **MongoDB Atlas Telemetry:** Logs anonymized generation latency, token volume, tone selections, and error distributions.

### 5. Production Observability & Multi-Stage Containerization
- **MongoDB Atlas Telemetry:** Logs anonymized generation latency, token volume, tone selections, and error distributions.
- **Production Docker Architecture:** Next.js 16 standalone build reduces Docker image size from **1.2 GB to ~120 MB**, running under an unprivileged `nextjs:nodejs` user for zero root vulnerabilities.

---

## ๐Ÿ› ๏ธ Complete Tech Stack

| Layer | Technologies / Services | Purpose |
|---|---|---|
| **Frontend Framework** | **Next.js 16.1.6 (App Router)** + **React 19** | Server Components, Streaming SSR, High-Performance Hydration |
| **Styling & Motion** | **Vanilla Tailwind CSS v4** + HSL Design Tokens | Modern dark mode, frosted glass surfaces, tactile spring micro-interactions |
| **Language Model** | **3-Tier Multi-Provider Cascade**: Primary `gemini-3.5-flash-lite`, Tier 2 `gemini-3.1-flash-lite-preview`, Tier 3 `nvidia/nemotron-3-ultra-550b-a55b:free` (OpenRouter) | Circuit breaker, exponential backoff, zero-downtime resilience |
| **Web Crawling** | **Tavily AI Search API** (8-Page Crawl) | Real-time portal & news search with domain filtering |
| **Page Extractor** | **Jina AI Reader (`r.jina.ai`)** | Deep page markdown conversion with Bearer token authentication |
| **Agent Protocols** | **Anthropic Model Context Protocol (MCP)** | Python 3.11 stdio server for external LLM agent invocation (8 Tools) |
| **Code Verification** | **GitHub REST API & MCP Proofer** | Real-time public commit SHA and repository grounding ($0 Free Tier) |
| **Model & Weights Verification** | **Hugging Face Hub API & MCP Proofer** | Real-time open-source weights, GGUF/LoRA quants, community downloads ($0 Free Tier) |
| **LLM Observability** | **Langfuse Node SDK** | Full-trace latency, token consumption, and multi-agent child spans |
| **Authentication** | **NextAuth.js v4** (Google OAuth 2.0 Provider) | Secure session management & OAuth callback flow |
| **Database & Telemetry**| **MongoDB Atlas** (Mongoose Driver) | Persistent telemetry schema, audit trails, usage tracking |
| **Deployment** | **Vercel Serverless Edge** + **Docker Standalone** | 0-second cold starts, global CDN caching, container portability |

---

## ๐Ÿ“ End-to-End System Sequence

```mermaid
sequenceDiagram
    autonumber
    actor Candidate as User / Recruiter
    participant Web as Next.js 16 Frontend
    participant API as Route Handlers (/api/*)
    participant Tavily as Tavily Search Engine
    participant Jina as Jina AI Reader
    participant GitHub as GitHub MCP Proofer
    participant Langfuse as Langfuse Observability
    participant LLM as Google Gemini 2.5 Flash Lite
    participant DB as MongoDB Atlas

    Candidate->>Web: Upload Resume (PDF) & Paste Job Description
    Web->>API: POST /api/parse-resume & /api/analyze
    API->>API: Auto-Extract Candidate Name, Email, LinkedIn & GitHub Handle
    API->>API: Auto-Detect Target Role & Company from JD
    API->>GitHub: GET /api/github-verify (MCP Tool #7 Commit Auditor)
    GitHub-->>API: Verified Public Repositories, Commit SHAs & Timestamps
    API->>LLM: Schema-Enforced Extraction (Skills & Match Matrix)
    LLM-->>API: Structured Match Matrix & Vendor Indicators
    API->>Langfuse: Log Trace & Child Spans (Latency, Tokens, Model)
    API-->>Web: Render Evidence Match, GitHub Code Proof, Hugging Face Proof & 4-Tier Job Context Tabs

    Candidate->>Web: Trigger Real-Time Research
    Web->>API: POST /api/research { company, role }
    API->>Tavily: Crawl 8 Authoritative URLs (Careers, News, Reviews)
    Tavily-->>API: Raw Search Results
    API->>Jina: Deep Scrape Top URLs to Clean Markdown
    Jina-->>API: High-Fidelity Content
    API-->>Web: Display HITL Source Cards (User Approves Sources)

    Candidate->>Web: Select Tone & Click "Generate Cover Letter"
    Web->>API: POST /api/generate { approvedSources, evidenceMap }
    API->>LLM: Evidence-Grounded Generation Prompt (Claim Validation)
    LLM-->>API: Streamed Verified Cover Letter + Citations
    API->>DB: Log Telemetry & Audit Record
    API-->>Web: Render Final Letter with Copy, Download & Interview Defense
```

---

## ๐Ÿ“‚ Project Directory Structure

```text
career-workspace-ambujsystems/
โ”œโ”€โ”€ web/                             # Next.js 16 Fullstack Application
โ”‚   โ”œโ”€โ”€ public/                      # Static assets & SVG icons
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ app/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ api/
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ analyze/         # Resume parsing & JD matching handler
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ auth/            # NextAuth Google OAuth endpoints
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ generate/        # Evidence-grounded generation pipeline
โ”‚   โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ research/        # Tavily 8-page crawl + Jina Reader pipeline
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ docs/                # Interactive Architectural Documentation
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ generate/            # Main interactive workspace interface
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ globals.css          # Design system tokens, tactile spring curves & glow utilities
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ layout.js            # Root layout with NextAuth Provider
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ page.js              # High-conversion Obsidian Black landing page
โ”‚   โ”‚   โ”œโ”€โ”€ components/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ ResultsPanel.jsx     # 4-tier tabbed intel & vendor verification UI
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ SourceCard.jsx       # Human-in-the-loop approved source cards
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ ...                  # Reusable UI component modules
โ”‚   โ”‚   โ”œโ”€โ”€ lib/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ gemini.js            # Resilient Google Gemini client with retry
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ mongodb.js           # Production connection-cached MongoDB client
โ”‚   โ”‚   โ””โ”€โ”€ prompts/                 # Strict system prompts & JSON schemas
โ”‚   โ”œโ”€โ”€ Dockerfile                   # Multi-stage standalone Next.js container (~120MB)
โ”‚   โ”œโ”€โ”€ next.config.mjs              # Standalone output configuration
โ”‚   โ””โ”€โ”€ package.json                 # Dependencies & build scripts
โ”œโ”€โ”€ mcp-server/                      # Anthropic Model Context Protocol (MCP)
โ”‚   โ”œโ”€โ”€ server.py                    # Stdio protocol handler with analysis tools
โ”‚   โ”œโ”€โ”€ Dockerfile                   # Python 3.11-slim container definition
โ”‚   โ””โ”€โ”€ requirements.txt             # MCP protocol SDK & utilities
โ”œโ”€โ”€ docker-compose.yml               # Multi-service local orchestrator
โ””โ”€โ”€ README.md                        # Production Engineering Specification
```

---

## ๐Ÿš€ Getting Started Locally

### Prerequisites
- **Node.js**: `v20.x` or `v22.x`
- **Docker & Docker Compose** (Optional, for containerized run)
- **API Keys**: Google Gemini API, Tavily Search API, Jina AI API, MongoDB Atlas URI

### 1. Clone the Repository
```bash
git clone https://github.com/Ambuj123-lab/career-workspace-ambujsystems.git
cd career-workspace-ambujsystems/web
```

### 2. Configure Environment Variables
Create `.env.local` inside the `web/` folder (or copy `.env.example` from repository root):
```env
# --- Core AI & Grounding Search (Required) ---
GEMINI_API_KEY=your_gemini_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here

# --- Authentication & Security (NextAuth.js) ---
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_random_32_character_secret_here

# --- Candidate Proofing & Verification (Optional) ---
GITHUB_TOKEN=your_github_token_here
HF_TOKEN=your_huggingface_token_here
JINA_API_KEY=your_jina_api_key_here

# --- LLM Provider Fallback & Telemetry (Optional) ---
OPENROUTER_API_KEY=your_openrouter_api_key_here
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/?appName=CoverCraft
MONGODB_DB_NAME=covercraft_db
```

#### Credential Audit & Transparency (M8ven Verified)
| Credential / Variable | Scope | Requirement | Purpose & Audit Description |
| :--- | :--- | :--- | :--- |
| `GEMINI_API_KEY` | Server / LLM | **Required** | Primary synthesis engine (Google AI Studio Gemini 2.5 / Flash) |
| `TAVILY_API_KEY` | Server / Web Search | **Required** | Live web grounding & target company intelligence crawler |
| `GOOGLE_CLIENT_SECRET` | NextAuth OAuth | Required for Auth | Google OAuth 2.0 client secret for candidate sign-in |
| `GOOGLE_CLIENT_ID` | NextAuth OAuth | Required for Auth | Google OAuth 2.0 client ID |
| `NEXTAUTH_SECRET` | Web Security | Required for Auth | Cryptographic signing secret for JWT session cookies |
| `GITHUB_TOKEN` | MCP / API | Optional | Higher rate limits for candidate public GitHub repository audits |
| `HF_TOKEN` | MCP / API | Optional | Candidate Hugging Face ML models, spaces, and dataset proofing |
| `JINA_API_KEY` | Web Crawler | Optional | Markdown parser fallback for target company landing pages |
| `OPENROUTER_API_KEY` | LLM Fallback | Optional | Multi-model provider fallback if primary Gemini API quota is throttled |
| `MONGODB_URI` | Telemetry / DB | Optional | Telemetry, generation audit logs, and user feedback persistence |

### 3. Install Dependencies & Launch
```bash
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) in your browser.

---

## ๐Ÿณ Docker Production Deployment

Build and run the multi-stage standalone container locally:

```bash
# Build multi-stage image (~120MB footprint)
docker build -t covercraft-web:latest ./web

# Run standalone container
docker run -p 3000:3000 --env-file ./web/.env.local covercraft-web:latest
```

Or deploy both the Next.js app and the Python MCP server via Docker Compose:
```bash
docker compose up -d --build
```

---

## ๐ŸŒ Production Deployments & Links

| Asset | Link | Status |
|---|---|:---:|
| **๐Ÿš€ Production App** | [career-workspace-ambujsystems.vercel.app](https://career-workspace-ambujsystems.vercel.app/) | ![Live](https://img.shields.io/badge/Status-Live-059669?style=flat-square) |
| **๐Ÿ“– Interactive Architecture Docs** | [career-workspace-ambujsystems.vercel.app/docs](https://career-workspace-ambujsystems.vercel.app/docs) | ![Ready](https://img.shields.io/badge/Status-Active-2563EB?style=flat-square) |
| **๐Ÿ’ป GitHub Repository** | [Ambuj123-lab/career-workspace-ambujsystems](https://github.com/Ambuj123-lab/career-workspace-ambujsystems) | ![GitHub](https://img.shields.io/badge/Status-Public-181717?style=flat-square&logo=github) |
| **๐Ÿ‘ค Engineering Portfolio** | [ambuj-ai-portfolio.vercel.app](https://ambuj-ai-portfolio.vercel.app/) | ![Portfolio](https://img.shields.io/badge/Status-Live-8B5CF6?style=flat-square) |
| **๐Ÿ“ฐ Official UptimeRobot Feature** | [Community Spotlight Article](https://uptimerobot.com/blog/community-spotlight-ambuj-kumar-tripathi/) | ![Featured](https://img.shields.io/badge/Status-Published-047857?style=flat-square) |

---

## ๐Ÿ‘จโ€๐Ÿ’ป Architect & Author

<div align="center">

### **Ambuj Kumar Tripathi**
**Generative AI Engineer & Production Systems Specialist**  
*Building production-grade agentic architectures, deterministic extraction pipelines, and high-reliability LLM systems.*

[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0A66C2?style=for-the-badge&logo=linkedin)](https://www.linkedin.com/in/ambuj-kumar-tripathi/)
[![GitHub](https://img.shields.io/badge/GitHub-Follow-181717?style=for-the-badge&logo=github)](https://github.com/Ambuj123-lab)
[![Portfolio](https://img.shields.io/badge/Portfolio-Visit-34A853?style=for-the-badge&logo=google-chrome&logoColor=white)](https://ambuj-ai-portfolio.vercel.app/)
[![Email](https://img.shields.io/badge/Email-Contact-EA4335?style=for-the-badge&logo=gmail&logoColor=white)](mailto:tripathiambuj761@gmail.com)

</div>

### Other Flagship Engineering Projects by Ambuj:
- ๐Ÿ›๏ธ **[Agentic Financial Parser](https://github.com/Ambuj123-lab/agentic-rag-financial-parser)** โ€” 11-node LangGraph StateGraph financial pipeline with WhatsApp bot & hybrid RAG.
- ๐Ÿ›ก๏ธ **[Citizen Safety Awareness AI](https://citizen-safety-ai-assistant.vercel.app/)** โ€” Real-time PII-masked linear RAG assistant for Indian legal & citizen protection.
- โš–๏ธ **[Constitution of India AI Expert](https://github.com/Ambuj123-lab)** โ€” Resilient Qdrant + Jina AI parent-child chunking legal RAG system.

---

## ๐Ÿ“œ License

This project is open-source and licensed under the **[MIT License](LICENSE)**.

<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=10,12,14,16,18&height=100&section=footer" width="100%"/>

<sub>Architected with โค๏ธ by Ambuj Kumar Tripathi โ€ข Powered by Google Gemini 3.5 & 3-Tier Multi-Provider Cascade (OpenRouter Nemotron 550B) โ€ข Langfuse Telemetry โ€ข Tavily AI โ€ข Jina AI โ€ข Next.js 16</sub>

</div>

Maintenance

ActivityMaintained
ResponsivenessNo issues