Skip to content

Commit 4e24ad3

Browse files
ppradyothppradyoth
committed
Build AI resume analyzer fullstack app
0 parents  commit 4e24ad3

64 files changed

Lines changed: 5228 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Backend
2+
ENVIRONMENT=development
3+
LOG_LEVEL=INFO
4+
GEMINI_API_KEY=
5+
GEMINI_MODEL=gemini-2.5-flash
6+
GEMINI_TIMEOUT_SECONDS=30
7+
GEMINI_RETRY_ATTEMPTS=3
8+
GEMINI_RETRY_BASE_DELAY_SECONDS=1
9+
ENABLE_AI_FALLBACK=true
10+
CORS_ORIGINS=http://localhost:5173
11+
MAX_RESUME_CHARS=20000
12+
MAX_UPLOAD_MB=5
13+
14+
# Frontend
15+
VITE_API_BASE_URL=http://localhost:8000

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.env
2+
.venv/
3+
__pycache__/
4+
*.pyc
5+
.pytest_cache/
6+
node_modules/
7+
dist/
8+
.DS_Store
9+
.firebase/
10+
.dist/
11+

‎AGENTS.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
2+
# Agent-Native Documentation & System Overview
3+
4+
This project is engineered for agent-native understanding, maintenance, and extension. All documentation is structured for advanced AI coding agents, LLMs, and future contributors to:
5+
6+
- Fully reconstruct, explain, and evolve the system
7+
- Understand all operational, architectural, and reliability decisions
8+
- Safely extend, debug, and deploy the project
9+
10+
## Documentation Map
11+
12+
- [README.md](README.md): Quickstart, architecture, and setup
13+
- [docs/architecture.md](docs/architecture.md): System and component architecture
14+
- [docs/backend.md](docs/backend.md): Backend orchestration, validation, and reliability
15+
- [docs/frontend.md](docs/frontend.md): Frontend data flow and UX
16+
- [docs/reliability.md](docs/reliability.md): Reliability engineering and failure handling
17+
- [docs/security.md](docs/security.md): Security assumptions and guardrails
18+
- [docs/workflows.md](docs/workflows.md): Operational and deployment workflows
19+
- [docs/api_contracts.md](docs/api_contracts.md): API contracts and schemas
20+
- [docs/deployment.md](docs/deployment.md): Deployment architecture and environment variables
21+
- [docs/troubleshooting.md](docs/troubleshooting.md): Troubleshooting and debugging
22+
- [docs/project_explainer.md](docs/project_explainer.md): High-context system explainer for agents
23+
24+
## Agent Usage Principles
25+
26+
- Always consult `docs/project_explainer.md` for the system mental model and extension points
27+
- Use strict schema validation for all new endpoints and outputs
28+
- Maintain separation of concerns: validation, orchestration, AI, monitoring
29+
- Extend via modular routers/services (backend) and components (frontend)
30+
- All changes must be documented for future agents and contributors
31+
32+
## System Boundaries & Extension
33+
34+
- Backend: FastAPI, modular, strict validation, fallback logic, observability
35+
- Frontend: React, Vite, TailwindCSS, robust error handling
36+
- AI Layer: Gemini API with fallback, strict output schema
37+
- Deployment: Docker, Render, Firebase
38+
39+
For a full system explainer, see [docs/project_explainer.md](docs/project_explainer.md).

‎AI_CONTEXT.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# AI_CONTEXT.md
2+
3+
---
4+
5+
## Project Purpose
6+
Production-grade AI Resume Analyzer & Career Assistant. Demonstrates reliable AI orchestration, validation, monitoring, and deployment for MLOps/AI system design.
7+
8+
## Architecture Summary
9+
- **Frontend**: React (Vite, TailwindCSS)
10+
- **Backend**: FastAPI (Python 3.11)
11+
- **AI Layer**: Gemini API (structured output, fallback to heuristics)
12+
- **Containerization**: Docker, docker-compose
13+
- **Deployment**: Backend (Render), Frontend (Firebase Hosting)
14+
15+
## Component Boundaries
16+
- **Frontend**: UI, form validation, error display, health status, API calls
17+
- **Backend**: API endpoints, validation, AI orchestration, fallback, monitoring, error handling
18+
- **AI Layer**: Gemini API integration, schema enforcement, fallback logic
19+
- **Monitoring**: In-memory metrics, `/metrics` endpoint
20+
21+
## Key Workflows
22+
1. User submits resume (text/file), target role, job description
23+
2. Backend validates input, extracts text if needed
24+
3. AI analysis via Gemini (timeout/retry); fallback to heuristics if needed
25+
4. Structured JSON response returned
26+
5. Metrics and logs recorded for every request
27+
28+
## Deployment Model
29+
- **Backend**: Dockerized, deployed via Render (`render.yaml`), health checks on `/health`
30+
- **Frontend**: Static build, deployed to Firebase Hosting (`firebase.json`)
31+
- **Local**: `docker-compose.yml` for unified dev
32+
- **Secrets**: Managed via environment variables (`.env`)
33+
34+
## API Contracts Summary
35+
- **POST `/analyze`**: multipart/form-data, fields: `resume_text` or `resume_file`, `target_role`, `job_description`. Returns JSON: `{ ats_score, missing_skills, strengths, recommendations }`
36+
- **GET `/health`**: `{ status, environment, gemini_configured }`
37+
- **GET `/metrics`**: `{ total_requests, total_errors, average_latency_ms, requests_by_path }`
38+
39+
## Reliability Assumptions
40+
- Strict schema validation (Pydantic) for all input/output
41+
- Timeout/retry for AI calls
42+
- Fallback to local analysis if Gemini fails
43+
- Centralized error handling, structured logging
44+
- Health/metrics endpoints for observability
45+
46+
## Security Constraints
47+
- Input validation/sanitization for all user data
48+
- Only PDF/TXT files accepted, size-limited
49+
- No persistent user data storage
50+
- Secrets never hardcoded; loaded from env
51+
- CORS restricts frontend origins
52+
- Error responses never leak sensitive info
53+
- Backend container runs as non-root
54+
55+
## Operational Conventions
56+
- All config via environment variables
57+
- All errors/logs include request IDs
58+
- Monitoring via `/metrics` (in-memory, not persistent)
59+
- Health via `/health`
60+
- No database or persistent storage
61+
- All deployments must pass health/metrics checks
62+
63+
## Important Engineering Rules
64+
- Never bypass schema validation
65+
- Always log errors with context
66+
- Fallback logic must be enabled for reliability
67+
- All new endpoints require strict request/response models
68+
- No sensitive data in logs or responses
69+
- All changes must be documented for future agents
70+
71+
## Extension Guidance
72+
- Add endpoints by creating new routers/services (backend)
73+
- Extend AI logic in Gemini/heuristic services
74+
- Add validation/monitoring layers as needed
75+
- Update frontend components for new features
76+
- Always enforce schema validation and structured outputs
77+
- Document all changes in agent-native docs
78+
79+
---
80+
81+
**This file is the canonical, condensed context for AI agents.**

‎README.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# AI Resume Analyzer and Career Assistant
2+
3+
A production-style fullstack workshop project that demonstrates AI orchestration, FastAPI backend patterns, Gemini API integration, structured outputs, Docker, CI/CD, monitoring, and deployment readiness.
4+
5+
## Architecture
6+
7+
```mermaid
8+
flowchart TD
9+
A["React + Vite frontend"] --> B["FastAPI backend API"]
10+
B --> C["Validation layer"]
11+
C --> D["Gemini API service"]
12+
D --> E["Structured Pydantic outputs"]
13+
B --> F["Logging and metrics"]
14+
```
15+
16+
## Features
17+
18+
- Upload a PDF/TXT resume or paste resume text.
19+
- Submit a target role and optional job description.
20+
- Generate an ATS score.
21+
- Identify missing skills and resume strengths.
22+
- Return structured JSON recommendations.
23+
- Use Gemini structured output mode in production.
24+
- Use a local heuristic fallback for development and CI when no API key is set.
25+
- Expose `/health` and `/metrics` endpoints.
26+
27+
## Folder Structure
28+
29+
```text
30+
.
31+
├── backend
32+
│ ├── app
33+
│ │ ├── middleware
34+
│ │ ├── routers
35+
│ │ ├── schemas
36+
│ │ ├── services
37+
│ │ └── utils
38+
│ ├── tests
39+
│ ├── Dockerfile
40+
│ └── requirements.txt
41+
├── frontend
42+
│ ├── src
43+
│ │ ├── components
44+
│ │ └── lib
45+
│ ├── firebase.json
46+
│ └── package.json
47+
├── .github/workflows/ci.yml
48+
├── docker-compose.yml
49+
├── render.yaml
50+
└── .env.example
51+
```
52+
53+
## Local Setup
54+
55+
Create environment files:
56+
57+
```bash
58+
cp .env.example .env
59+
cp frontend/.env.example frontend/.env
60+
```
61+
62+
Add your Gemini key to `.env` when you want live AI responses:
63+
64+
```bash
65+
GEMINI_API_KEY=your_key_here
66+
ENABLE_AI_FALLBACK=false
67+
```
68+
69+
Leave `ENABLE_AI_FALLBACK=true` for local demos without a Gemini key.
70+
71+
## Backend
72+
73+
```bash
74+
cd backend
75+
python3.11 -m venv .venv
76+
source .venv/bin/activate
77+
pip install -r requirements.txt
78+
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
79+
```
80+
81+
Useful endpoints:
82+
83+
- `GET http://localhost:8000/health`
84+
- `GET http://localhost:8000/live`
85+
- `GET http://localhost:8000/ready`
86+
- `GET http://localhost:8000/metrics`
87+
- `POST http://localhost:8000/analyze`
88+
89+
Example API call:
90+
91+
```bash
92+
curl -X POST http://localhost:8000/analyze \
93+
-F "target_role=MLOps Engineer" \
94+
-F "resume_text=MLOps Engineer with Python, FastAPI, Docker, monitoring, CI/CD, and cloud deployment experience. Built production APIs and improved release reliability by 35 percent."
95+
```
96+
97+
## Frontend
98+
99+
```bash
100+
cd frontend
101+
npm install
102+
npm run dev
103+
```
104+
105+
Open `http://localhost:5173`.
106+
107+
## Dockerized Backend
108+
109+
```bash
110+
docker compose up --build backend
111+
```
112+
113+
The backend will run at `http://localhost:8000`.
114+
115+
## Render Deployment
116+
117+
This repo includes `render.yaml` for a Docker-based Render web service.
118+
119+
Set these environment variables in Render:
120+
121+
- `GEMINI_API_KEY`
122+
- `CORS_ORIGINS`, for example your Firebase Hosting URL
123+
- `ENABLE_AI_FALLBACK=false`
124+
125+
Render will use:
126+
127+
- Docker context: `./backend`
128+
- Dockerfile: `./backend/Dockerfile`
129+
- Health check: `/health`
130+
131+
## Firebase Hosting
132+
133+
From the frontend directory:
134+
135+
```bash
136+
npm run build
137+
firebase init hosting
138+
firebase deploy
139+
```
140+
141+
Use `frontend/firebase.json` and set:
142+
143+
```bash
144+
VITE_API_BASE_URL=https://your-render-service.onrender.com
145+
```
146+
147+
before building for production.
148+
149+
## CI/CD
150+
151+
GitHub Actions runs:
152+
153+
- Backend dependency install and pytest.
154+
- Frontend dependency install and production build.
155+
156+
The workflow is defined at `.github/workflows/ci.yml`.
157+
158+
## API Response Shape
159+
160+
```json
161+
{
162+
"ats_score": 82,
163+
"missing_skills": [],
164+
"strengths": [],
165+
"recommendations": []
166+
}
167+
```
168+
169+
## Notes for Workshops
170+
171+
The backend keeps the AI provider behind `GeminiResumeService`, so you can teach orchestration and reliability without mixing provider calls into the route layer. Validation happens before AI calls, structured output is enforced by Pydantic, and logs are emitted as JSON for easier monitoring demos.

‎backend/.dockerignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
__pycache__/
2+
*.pyc
3+
.pytest_cache/
4+
.venv/
5+
.env

‎backend/Dockerfile‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
FROM python:3.11-slim AS runtime
2+
3+
ENV PYTHONDONTWRITEBYTECODE=1
4+
ENV PYTHONUNBUFFERED=1
5+
ENV PIP_NO_CACHE_DIR=1
6+
ENV PORT=8000
7+
8+
WORKDIR /app
9+
10+
COPY requirements.txt .
11+
RUN python -m venv /opt/venv \
12+
&& /opt/venv/bin/pip install --upgrade pip \
13+
&& /opt/venv/bin/pip install -r requirements.txt
14+
15+
ENV PATH="/opt/venv/bin:${PATH}"
16+
17+
COPY app ./app
18+
19+
RUN useradd --create-home --shell /usr/sbin/nologin appuser \
20+
&& chown -R appuser:appuser /app
21+
22+
USER appuser
23+
24+
EXPOSE 8000
25+
26+
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
27+
CMD python -c "import os, urllib.request; urllib.request.urlopen(f'http://127.0.0.1:{os.getenv(\"PORT\", \"8000\")}/live', timeout=3)"
28+
29+
CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT}"]

‎backend/app/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
"""Application package for the AI Resume Analyzer backend."""
2+

0 commit comments

Comments
 (0)