CoverCraft AI by Ambuj Kumar Tripathi

---

🎯 エンジニアリングの理念

❌ 「おもちゃのAIジェネレーター」という誤謬

インターネット上のカバーレターツールの99％は単純なプロンプトラッパーであり、技術系採用担当者との面接で即座に不採用となる原因になります。

• 根拠のない数値の捏造： 定量的な実績をでっち上げます（候補者がスキル欄にDockerを記載しただけなのに、「Dockerを使って売上を43％増加」など）。
• 中身のないお世辞： ありきたりで気恥ずかしい賛辞を差し込みます（「業界を変革する画期的なシナジーに長年感銘を受けてきました」など）。
• 企業情報の根拠が皆無： 最近のエンジニアリング方針の転換、現在の技術スタック、企業傘下の子会社をリアルタイムに把握できません。
• 見えない第三者の落とし穴： 求人情報が、直接雇用企業を装った第三者の人材紹介会社や給与計算代行会社によるものだと見抜けません。

✅ CoverCraftのアーキテクチャ：検証可能なエビデンスグラフ

CoverCraftはテンプレートの穴埋めツールではありません。シニアエンジニアや採用に慎重なチーム向けに設計された、エビデンスに基づくキャリアワークスペース兼主張検証エンジンです。

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

---

⚡ アーキテクチャの中核となる柱

1. 複数のソースによるリアルタイムインテリジェンスと、深層Markdownクロール

• Tavilyによる8ページの信頼性の高いクロール： careers、linkedin、naukri、ambitionboxを対象に、企業の最新情報を検索します。
• Jina AI Reader（r.jina.ai）による詳細なスクレイピング： HTMLの余計な要素、ポップアップ、Cookieの壁を取り除き、タイムアウト時の指数関数的なフォールバックを備えた、高精度でクリーンなMarkdownを返します。
• 3層ドメイン分類器： 取得したインテリジェンスを、企業公式情報、求人ポータルとレビュー、社外のエンジニアリング関連ニュースに分類します。

2. 決定論的フォールバック正規表現と4階層の企業インテリジェンス

LLMのJSON構造の生成が遅れたり、一部しか入力されていなかったりする場合、決定論的な正規表現パイプラインが、求人票の生トークンから直接、確かな情報を抽出します。

• 📋 職務コンテキストのサブタブ（デフォルト）： 職種、勤務形態（リモート／ハイブリッド／出社）、経験年数の範囲、給与の開示状況を抽出します。
• ⚠️ 第三者企業／人材派遣の検出： 人材派遣会社、C2H（契約から正社員への採用）、給与支払いの仲介業者を検出し、求人票から直接抽出した原文の引用とともに表示します。
• 🏢 企業情報のサブタブ： その企業が直接雇用企業、サービスベンダー、GCC（グローバル・ケイパビリティ・センター）、プロダクト企業のいずれに該当するかを確認します。不足している項目には「利用可能な情報源から確認できません」と厳密に表示します。
• ⚡ 採用シグナルのサブタブ： 技術分野の重点、進行中の取り組み、最近の採用急増を、参照番号 [1]、[2] とともに抽出します。
• 🔗 情報源カバレッジのサブタブ： URLの引用とスクレイピング状況をすべて表示します。

3. 根拠に基づく生成、UX、主張検証ポリシー

• 根拠に基づく統合機能： システム指示により、カバーレターに含まれるすべての実績に関する主張が、候補者の履歴書にある確認済みの箇条書きに直接対応するよう徹底します。
• インラインの対話型根拠マーカーとクリーンな提出用エクスポート： 画面上の対話型バッジ（[履歴書の根拠] と [情報源の引用]）を使うと、候補者はカーソルを合わせて正確な情報源の引用を確認できます。また、[根拠マーカー：オン／オフ] をリアルタイムで切り替えられます。候補者が クリップボードにコピー または Markdown／PDFをダウンロード をクリックすると、内部の引用タグが自動的に削除され、採用担当者に提出できる完全にクリーンなレターが作成されます。
• 敵対的な誇張表現のレッドチーム検証（正確性監査ゲート）： 生成されたテキストと候補者の履歴書に記載された動詞を照合し、役職や貢献度の誇張を検出します（例：履歴書には「Kubernetesのロールアウトでチームを支援」とあるのに、草案では「企業全体の移行を主導」と記載）。エンジンは、未確認の動詞を確認済みの根拠に沿った表現へ自動的に修正し、監査ログに記録します。
• ライブ進捗トラッカーと動的な経過時間タイマー： イベント駆動型の4段階実行トラッカー（01. 能力の照合 → 02. MCP企業調査 → 03. 人による承認 → 04. 根拠の統合）と、リアルタイムでカウントするタイマー（00:04s）、実行中のツールインジケーターを備えています。候補者は実行状況を明確に把握できるため、混乱や処理の停止に対する懸念が生じません。
• ヒューマン・イン・ザ・ループ（HITL）ゲート： 外部の情報がLLM生成プロンプトに取り込まれる前に、ユーザーがスクレイピングしたウェブ情報源を明示的に確認し、信頼性スコアを評価したうえで、有効／無効を切り替えられます。

4. ネイティブ Model Context Protocol（MCP）統合（本番環境向けツール 8 個）

ヒント

🛡️ 3 つのレジストリで検証済みの FastMCP サーバー（Glama · Smithery · M8ven）：
CoverCraft の FastMCP サーバーと登録済みの 8 個のツールは、主要なレジストリで独立した監査と検証を受けており、Glama Grade A - A、M8ven Trust Score 89/100（Grade B）、**Smithery Verified（8 Tools）**を獲得しています。継続的なライブ監視を実施しており、セキュリティ上の脆弱性は 0 件です。

• Python 3.11 で記述された、スタンドアロンの Anthropic Model Context Protocol（MCP） サーバー（mcp-server/）が含まれています。
• 標準の Model Context Protocol stdio トランスポートおよび Streamable HTTP SSE トランスポートを通じて、登録済みの 8 個のツールを提供します。
  1. company_research：Tavily を使用したリアルタイムのウェブ検索。追跡可能な出典引用付きです。
  2. evidence_validator：ソースデータに照らして Claim Ledger を検証し、VERIFIED／PARTIAL／UNSUPPORTED を返します。
  3. jd_analyzer：実際の証拠となる箇所に基づき、履歴書と求人票（JD）の適合性を分析します。
  4. ats_readiness：キーワードの網羅率、書式の完全性、文書の長さを対象に、決定論的なヒューリスティック監査を行います。
  5. source_filter：ドメインの信頼度をアルゴリズムで分類し、ノイズを抑制するとともに、古いニュースと技術を除外します（企業の取り組みは 9 か月未満、エンジニアリングスタックは 18 か月未満を対象とし、[Historical Context] タグを付けます）。
  6. cover_letter_generator：証拠に基づく文章を生成します。構造化されたインライン引用マーカーを付与し、過剰な主張を一切行いません。
  7. github_proofer：候補者の GitHub ポートフォリオとコミット履歴をリアルタイムで検証するエンジンです（無料の PAT 利用枠は $0、5,000 req/hr）。公開リポジトリを調査し、コミット SHA とメッセージを抽出して、履歴書の技術的な主張を検証可能なコードの証拠に直接結び付け、過剰な主張を防ぎます。
  8. huggingface_proofer：GenAI モデルと重みを自律的に検証するエンジンです（無料の HF Token 利用枠は $0、30,000 req/hr）。候補者の公開 Hugging Face モデル、スペース、データセット、およびダウンロード数の合計指標（例：700 件以上のモデルダウンロード、qLoRA ファインチューニング、GGUF 量子化）を調査し、AI に関する主張を検証可能な重みと照合します。
• デュアルトランスポートに対応しています。stdio_server を使用して Claude Desktop／Cursor でローカル実行するか、--transport=sse を使用して独立したストリーミングマイクロサービスとしてデプロイできます。

5. ライブ GitHub コード証明とコミット監査ツール（MCP ツール #7）

• 検証可能な公開コードの証拠： 公式 GitHub MCP ツール（mcp-server/tools/github_proofer.py）と Next.js ルート /api/github-verify を介して、候補者の GitHub プロフィールに接続します。
• コミット単位のハッシュ検証： リアルタイムのコミット SHA（例：sha: 7f2a1b9）、コミットメッセージ、リポジトリの説明、アーキテクチャファイルを抽出し、検証可能なコード履歴に基づいて技術的な主張を確認します。
• 無料枠は完全無料： 読み取り専用の公開スコープを持つ GitHub Personal Access Token（PAT）を利用し、$0 のコストで 1 時間あたり 5,000 件のリクエストを実現し、レート制限を完全に分離して安定性を確保します。
• 誇張を見抜く敵対的センチネル： 候補者が公開リポジトリやコミットによる証拠なしにフレームワークの使用を主張した場合、CoverCraft は架空のエンタープライズ経験を捏造するのではなく、その不足を指摘し、応募者に説明を求めます。

6. Hugging Face の重みとモデルを自律監査するツール（MCP ツール #8）

• 検証可能なオープンソースの重みとモデル： 公式 MCP ツール（mcp-server/tools/huggingface_proofer.py）と Next.js ルート /api/hf-verify を介して、候補者の Hugging Face プロフィールに接続します。
• 実際のダウンロード数とコミュニティによる証拠： 実際のコミュニティ採用指標（例：726 件以上のモデルダウンロード、39 件のコミュニティの「いいね」／スター）を監査し、検証可能なダウンロード可能な重みと照らし合わせて、GenAI に関する主張（ファインチューニング、LoRA、QLoRA、GGUF 量子化、Legal AI）を確認します。
• インタラクティブな AI デモの検証（Gradio Spaces）： 候補者の稼働中のインタラクティブな Gradio スペース（例：ambuj-ai-chatbot、legal-india-chatbot）を調査し、モデルの稼働環境へのデプロイとエッジ推論機能を数学的に検証します。
• API の無料枠は完全無料： Hugging Face のユーザーアクセストークン（無料枠は $0）を利用し、5 分間の stale-while-revalidate キャッシュと高可用性のフォールバックを備え、1 時間あたり 30,000 件のリクエストを提供します。
• 誇張防止センチネル： 商用 API にプロンプトを送るだけの候補者と、実際に重みをファインチューニング、量子化して公開し、コミュニティで支持を得ている真の AI エンジニアを見分けます。

7. 候補者のプライバシーを優先するアーキテクチャと二重自動抽出エンジン

• 個人識別情報の保護と電話番号の削除： 応募者のプライバシーを守るため、携帯電話番号を UI とバックエンドのスキーマから完全に削除しました。
• 二重のインテリジェント自動抽出：
  • 履歴書の取り込みと自動入力（/api/parse-resume）： アップロードされた PDF 履歴書から正規表現と LLM による抽出で候補者の氏名、メールアドレス、LinkedIn URL、GitHub プロフィール URL を自動抽出し、ジェネレーターフォームに事前入力します。
  • 求人票の自動検出（InputForm.jsx）： ユーザーが求人票を貼り付けるとすぐに、対象の職種と企業名を自動検出し、重複する手入力をなくします。

8. 本番環境の可観測性：Langfuse による LLM トレースと MongoDB Atlas

• Langfuse による LLM の可観測性とトレース： エンドツーエンドの生成レイテンシ、プロンプト／完了トークンの消費量、Gemini のモデルパラメーター、8 つすべての MCP ツール操作におけるスパン単位の子トレースを記録する、完全なトレーステレメトリーを提供します。
• 耐障害性を備えたノンブロッキング実行： 可観測性スパンは保護された非同期の try/catch ブロック内で実行されます。ネットワーク制限が発生した場合も、ユーザーへの遅延をゼロに保ち、生成をシームレスに継続します。
• MongoDB Atlas テレメトリー： 匿名化された生成レイテンシ、トークン量、トーンの選択、エラーの分布を記録します。

5. 本番環境の可観測性と多段階コンテナ化

• MongoDB Atlas テレメトリー： 匿名化された生成レイテンシ、トークン量、トーンの選択、エラーの分布を記録します。
• 本番環境向け Docker アーキテクチャ： Next.js 16 のスタンドアロンビルドにより Docker イメージのサイズを1.2 GB から約 120 MB に削減し、権限のない nextjs:nodejs ユーザーで実行することで、root 権限に起因する脆弱性をなくします。

---

🛠️ 技術スタック全体

レイヤー	テクノロジー／サービス	目的
フロントエンドフレームワーク	Next.js 16.1.6 (App Router) + React 19	サーバーコンポーネント、ストリーミング SSR、高パフォーマンスなハイドレーション
スタイリングとモーション	Vanilla Tailwind CSS v4 + HSL デザイントークン	モダンなダークモード、すりガラスのようなサーフェス、触感のあるスプリング式マイクロインタラクション
言語モデル	3層マルチプロバイダーカスケード：プライマリ gemini-3.5-flash-lite、第2層 gemini-3.1-flash-lite-preview、第3層 nvidia/nemotron-3-ultra-550b-a55b:free (OpenRouter)	サーキットブレーカー、指数バックオフ、ダウンタイムゼロの耐障害性
ウェブクロール	Tavily AI Search API（8ページクロール）	ドメインフィルタリングによるリアルタイムのポータルおよびニュース検索
ページ抽出	Jina AI Reader (r.jina.ai)	ベアラートークン認証を使用した、ページ全体の Markdown 変換
エージェントプロトコル	Anthropic Model Context Protocol (MCP)	外部 LLM エージェントの呼び出しに対応する Python 3.11 の stdio サーバー（8 ツール）
コード検証	GitHub REST API & MCP Proofer	公開コミット SHA とリポジトリのリアルタイム検証（無料枠 $0）
モデルと重みの検証	Hugging Face Hub API & MCP Proofer	オープンソースの重み、GGUF／LoRA 量子化モデル、コミュニティのダウンロード数をリアルタイムで検証（無料枠 $0）
LLM オブザーバビリティ	Langfuse Node SDK	レイテンシー、トークン消費量、マルチエージェントの子スパンを含む完全なトレース
認証	NextAuth.js v4（Google OAuth 2.0 Provider）	安全なセッション管理と OAuth コールバックフロー
データベースとテレメトリ	MongoDB Atlas（Mongoose Driver）	永続化テレメトリスキーマ、監査証跡、使用状況の追跡
デプロイ	Vercel Serverless Edge + Docker Standalone	コールドスタート 0 秒、グローバル CDN キャッシュ、コンテナーの可搬性

---

📐 エンドツーエンドのシステムシーケンス

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

---

📂 プロジェクトディレクトリ構成

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

---

🚀 ローカルでの開始方法

前提条件

• Node.js：v20.x または v22.x
• Docker & Docker Compose（任意、コンテナーで実行する場合）
• API キー：Google Gemini API、Tavily Search API、Jina AI API、MongoDB Atlas URI

1. リポジトリをクローンする

git clone https://github.com/Ambuj123-lab/career-workspace-ambujsystems.git
cd career-workspace-ambujsystems/web

2. 環境変数を設定する

web/ フォルダー内に .env.local を作成します（またはリポジトリのルートにある .env.example をコピーします）：

# --- 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

認証情報の監査と透明性（M8ven による検証済み）

認証情報／変数	スコープ	要件	目的と監査の説明
GEMINI_API_KEY	サーバー／LLM	必須	主要な統合エンジン（Google AI Studio Gemini 2.5 / Flash）
TAVILY_API_KEY	サーバー／ウェブ検索	必須	ライブウェブ情報による検証と、対象企業の情報を収集するクローラー
GOOGLE_CLIENT_SECRET	NextAuth OAuth	認証に必須	候補者のサインインに使用する Google OAuth 2.0 クライアントシークレット
GOOGLE_CLIENT_ID	NextAuth OAuth	認証に必須	Google OAuth 2.0 クライアント ID
NEXTAUTH_SECRET	ウェブセキュリティ	認証に必須	JWT セッション Cookie の暗号署名シークレット
GITHUB_TOKEN	MCP／API	任意	候補者の公開 GitHub リポジトリを監査する際のレート制限を緩和
HF_TOKEN	MCP／API	任意	候補者の Hugging Face ML モデル、スペース、データセットの検証
JINA_API_KEY	ウェブクローラー	任意	対象企業のランディングページ用 Markdown パーサーのフォールバック
OPENROUTER_API_KEY	LLM フォールバック	任意	プライマリ Gemini API の割り当てが制限された場合のマルチモデルプロバイダーへのフォールバック
MONGODB_URI	テレメトリ／DB	任意	テレメトリ、生成の監査ログ、ユーザーフィードバックの永続化

3. 依存関係をインストールして起動する

npm install
npm run dev

ブラウザーで http://localhost:3000 を開きます。

---

🐳 Docker による本番環境へのデプロイ

マルチステージのスタンドアロンコンテナーをローカルでビルドして実行します：

# 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

または、Docker Compose を使用して Next.js アプリと Python MCP サーバーの両方をデプロイします：

docker compose up -d --build

---

🌐 本番環境へのデプロイとリンク

資産	リンク	ステータス
🚀 本番アプリ	career-workspace-ambujsystems.vercel.app
📖 インタラクティブなアーキテクチャドキュメント	career-workspace-ambujsystems.vercel.app/docs
💻 GitHub リポジトリ	Ambuj123-lab/career-workspace-ambujsystems
👤 エンジニアリングポートフォリオ	ambuj-ai-portfolio.vercel.app
📰 UptimeRobot 公式特集記事	コミュニティスポットライト記事

---

👨‍💻 アーキテクト兼作者

Ambuj によるその他の主要なエンジニアリングプロジェクト：

• 🏛️ エージェント型金融パーサー — WhatsApp ボットとハイブリッド RAG を備えた、11 ノードの LangGraph StateGraph 金融パイプラインです。
• 🛡️ 市民安全啓発 AI — インドの法律と市民保護のための、PII をリアルタイムでマスキングする線形 RAG アシスタントです。
• ⚖️ インド憲法 AI エキスパート — Qdrant と Jina AI の親子チャンク分割を活用した、堅牢な法務 RAG システムです。

---

📜 ライセンス

このプロジェクトはオープンソースで、**MIT ライセンス**のもとでライセンスされています。