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