How hamzaqadeer01/resume-matcher works
Project Type and Purpose
• Full-stack web application to analyze and optimize resumes against job descriptions
• Frontend built with Next.js (React), styled with Tailwind CSS
• Backend built with FastAPI (Python), uses local AI model serving (Ollama) and SQLite
File Structure
• Top-level “apps/frontend” → Next.js application
• Top-level “apps/backend” → FastAPI application
– “app/api/router/v1” → REST endpoints (/job, /resume, /health)
– “app/agent” → Core AI Agent abstraction, providers (Ollama, OpenAI), strategies
– “app/services” → Business logic (job_service, resume_service, score_improvement_service)
– “app/models” & “app/schemas” → ORM models (SQLite via SQLAlchemy), Pydantic schemas, JSON schemas
– “app/core” → Configuration, database initialization, exception handling
• Configuration and deployment scripts: Makefile, setup scripts, .env.sample
Extract Key Insights from README
• Frontend communicates with backend over HTTP REST (Next.js API calls)
• Backend routes calls into an AI agent which generates prompts and queries local models via Ollama
• Persistence in SQLite for job postings, user resumes, match scores
• Local-first design: AI runs on user’s machine (no cloud hosting by default)
Main Components and Their Relationships
• User’s Browser (Web UI)
– Next.js pages & components
– File upload widget, keyword optimizer, resume previewer
– Sends HTTP requests to Backend (/api/v1)
• Backend API (FastAPI)
– API Layer: Routers → Controller methods
– Service Layer: Business logic for resume analysis, job matching, score improvement
– Agent Layer: Builds prompts, selects provider, executes model calls
– Providers: Ollama (local AI), optional OpenAI fallback
– Data Layer: SQLAlchemy models, SQLite database
• Data Store
– SQLite database file
– Tables: users, resumes, jobs, associations, scores
• AI Model Server
– Ollama local service (model hosting)
– Exposed via HTTP/gRPC to the Agent providers
• External Services (optional)
– OpenAI API as fallback provider
– Discord/LinkedIn/Twitter integration for community links (non-critical)
Architectural Patterns and Design Principles
• Layered Architecture (API → Services → Agent → Providers → Database)
• Separation of Concerns:
– UI vs. API vs. Business Logic vs. AI orchestration vs. Persistence
• Hexagonal/Ports-and-Adapters:
– Agent strategies and providers are swappable adapters around a common interface
• Domain-Driven Organization:
– Models and schemas grouped by domain (job, resume, user)