TECHNICAL ARCHITECTURE

How ResumeForge Works

A decoupled async pipeline — the user uploads once and the AI pipeline runs in the background. Zero waiting on loading screens.

Request Flow
End-to-End Pipeline
🌐
Browser
Next.js 15
FastAPI
Python 3.12
🗄️
S3
File Storage
📦
Redis
Job Queue
⚙️
Celery
Workers
🤖
Claude API
Sonnet 4.6
AI Processing Pipeline
📖
Extract
pdfplumber / python-docx
🔗
Embed
pgvector (384-dim)
🎯
Keywords
Claude Haiku
✍️
Rewrite
Claude Sonnet
🛡️
Validate
Constitutional AI
📄
PDF
WeasyPrint ATS
Technology Stack
Frontend
Next.js 15 + TypeScript
shadcn/ui components, Zustand state, TanStack Query for data fetching
Backend
FastAPI (Python 3.12)
Async by default, Pydantic v2 validation, OpenAPI docs auto-generated
AI / LLM
Claude Sonnet 4.6
200K context, lower hallucination rate, ~30% cheaper than GPT-4o
Database
PostgreSQL 16 + pgvector
Single DB for relational + vector. No separate Pinecone instance.
Queue
Celery 5 + Redis
Python-native, battle-tested. 1→10 auto-scaling workers on ECS Fargate.
Auth
Clerk.dev
Magic link + OAuth. Handles GDPR consent flows out of the box.
Storage
AWS S3 + CloudFront
Presigned URL upload. Files served via CDN. AES-256 at rest.
Billing
Stripe
Credit pack webhooks. Idempotent handlers. Automatic invoice PDF.
Key Architecture Decisions
1
LLM Provider
Claude Sonnet 4.6 has significantly lower hallucination rates on factual rewrite tasks and costs ~30% less per token than GPT-4o at equivalent quality.
✓ Claude Sonnet 4.6 GPT-4o
2
Vector DB
pgvector extension on the existing PostgreSQL instance avoids operational overhead of a separate vector database service.
✓ pgvector on Postgres Pinecone
3
Task Queue
Celery 5 with Redis is battle-tested, Python-native, and integrates seamlessly with Django/FastAPI. No vendor lock-in.
✓ Celery + Redis AWS SQS + Lambda
4
AI Orchestration
LangChain LCEL chains provide explicit control over prompt templates and retry logic without opaque abstractions.
✓ LangChain LCEL LlamaIndex
5
PDF Rendering
WeasyPrint produces consistent ATS-safe single-column layouts from CSS. fpdf2 used as local fallback for this demo.
✓ WeasyPrint Puppeteer/Chrome
6
Auth
Clerk.dev handles GDPR consent flows, magic link, and OAuth with zero backend code. Clerk webhooks sync user state.
✓ Clerk.dev Auth0 / custom JWT
Database Schema
-- PostgreSQL 16 + pgvector TABLE users id UUID PRIMARY KEY email TEXT UNIQUE NOT NULL password_hash TEXT NOT NULL credits INT DEFAULT 1 subscription_active BOOL DEFAULT FALSE gdpr_consent_at TIMESTAMPTZ deleted_at TIMESTAMPTZ -- soft delete TABLE resumes id UUID PRIMARY KEY user_id UUID REFERENCES users s3_raw_key TEXT -- AES-256 at rest file_type TEXT -- pdf | docx parsed_json JSONB -- structured sections raw_text TEXT TABLE resume_embeddings resume_id UUID REFERENCES resumes chunk_index INT embedding VECTOR(384) -- all-MiniLM-L6-v2 -- INDEX: ivfflat(embedding vector_cosine_ops) WITH (lists=100) TABLE tailoring_jobs id UUID PRIMARY KEY user_id UUID REFERENCES users resume_id UUID REFERENCES resumes job_description TEXT jd_keywords JSONB status TEXT -- QUEUED|EXTRACTING|ANALYZING|REWRITING|VALIDATING|GENERATING|DONE|FAILED ats_score FLOAT validation_report JSONB TABLE tailored_resumes id UUID PRIMARY KEY job_id UUID REFERENCES tailoring_jobs rewritten_json JSONB pdf_s3_key TEXT template_id TEXT DEFAULT 'classic' TABLE credit_transactions id UUID PRIMARY KEY user_id UUID REFERENCES users amount INT -- positive=add, negative=deduct reason TEXT -- PURCHASE|JOB_DEDUCTION|REFUND|PROMO stripe_payment_id TEXT created_at TIMESTAMPTZ DEFAULT now()
MVP Roadmap — 8 Weeks
Phase 1
Weeks 1–2
Infra & Auth
  • AWS ECS Fargate setup
  • PostgreSQL + pgvector
  • Clerk.dev auth integration
  • S3 bucket + presigned URLs
Phase 2
Weeks 3–4
Parsing & Embedding
  • pdfplumber integration
  • python-docx integration
  • Celery worker setup
  • Vector embedding pipeline
Phase 3
Weeks 5–6
AI Pipeline
  • Claude rewrite chain
  • Hallucination validation
  • ATS scoring algorithm
  • PDF generation (WeasyPrint)
Phase 4
Weeks 7–8
Billing & Launch
  • Stripe credit packs
  • GDPR export/erase
  • Load testing (k6)
  • Production deploy