# ResumeLens Development Skill

Use this skill when building or modifying features in the ResumeLens application.

## Project at a glance

- Stack: Go backend (`chi` router) + React 19 + TypeScript + Vite frontend.
- Core purpose: accept a resume PDF and job description, call OpenAI, and return structured scoring + feedback.
- Backend entrypoint: `cmd/server/main.go`.
- Frontend entrypoint: `web/src/main.tsx`.
- API endpoint: `POST /api/analyze`.

## Repository map

- `cmd/server/main.go`: starts HTTP server on `:3000`, mounts middleware and API routes.
- `internal/api/`: CORS + rate-limit middleware and route mounting.
- `internal/handlers/analyze.go`: multipart request validation + JSON response.
- `internal/services/analyzer.go`: PDF text extraction + OpenAI call + JSON parsing.
- `internal/services/prompt.go`: system prompt contract for LLM output.
- `internal/models/analysis.go`: canonical backend response schema.
- `web/src/pages/`: app routes (`/`, `/upload`, `/demo`, `/results`).
- `web/src/components/analysis/`: reusable result UI sections.
- `web/src/types/resumeAnalysis.ts`: frontend schema mirror of backend response.
- `docker-compose.yml`: local multi-container runtime (`backend` + `frontend` at `:3005`).

## Local development workflow

### Backend

- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Backend listens on `http://localhost:3000`.

### Frontend

- Install deps: `cd web && npm ci`
- Dev server: `cd web && npm run dev`
- Build: `cd web && npm run build`
- Lint: `cd web && npm run lint`

### Full stack with Docker

- Run: `docker compose up --build`
- Frontend served at `http://localhost:3005`
- Nginx proxies `/api/*` to backend service (`web/nginx.conf`).

## Configuration and env vars

- Backend requires `OPENAI_API_KEY`.
- Frontend optionally uses `VITE_API_BASE_URL`.
  - If unset: dev defaults to `http://localhost:3000`.
  - If production build: defaults to relative path (`/api/...`) for nginx proxying.

Do not hardcode keys or expose secrets in client code.

## API contract (critical)

`POST /api/analyze` expects `multipart/form-data`:

- `resume`: uploaded file (backend expects a parseable PDF).
- `job_description`: non-empty string.

Responses:

- `200`: JSON matching `AnalysisResult` / `ResumeAnalysisResult`.
- `400`: invalid form payload (missing file/job description).
- `429`: per-IP rate limit exceeded.
- `500`: analysis failure (PDF parse issue, OpenAI issue, JSON parse issue).

Keep backend model and frontend type definitions synchronized whenever fields change.

## Existing behavior to preserve

- Rate limiting is in-memory and per source IP: max 10 requests/hour.
- CORS currently allows:
  - `http://localhost:5173`
  - `http://localhost`
  - `http://localhost:80`
- Results page depends on router state; direct navigation to `/results` redirects to `/`.
- Download JSON action exists on results page.
- Prompt injection output fields are supported in both backend and frontend:
  - `injection_detected`
  - `injection_details`

## LLM integration details

- LLM call uses `openai-go` chat completions with model `gpt-4o-mini`.
- System prompt in `internal/services/prompt.go` requires strict JSON-only output.
- Parsing is strict JSON unmarshal into `models.AnalysisResult`.

When adding fields:

1. Update `internal/models/analysis.go`.
2. Update prompt JSON contract in `internal/services/prompt.go`.
3. Update `web/src/types/resumeAnalysis.ts`.
4. Update UI components in `web/src/components/analysis/` and pages consuming the data.

## Known implementation quirks

- Upload UI currently accepts files with MIME `image/*` in `handleFileSelect`, but the file input element only allows `.pdf`, and backend parser expects PDF bytes.
- PDF extraction buffers full file in memory before parsing (`io.ReadAll`), so large-file behavior should be considered when adding limits.
- Current rate limiter is process-local; scaling to multiple backend replicas will need shared storage.

## Feature development checklist

When implementing a new feature, follow this order:

1. Define data contract impact first (backend model + frontend type).
2. Update API handler/service behavior.
3. Update UI and route behavior.
4. Add or update tests (`go test ./...`; frontend lint/build).
5. Validate end-to-end flow with one manual upload + analyze run.

## Validation commands before shipping

- Backend tests: `go test ./...`
- Frontend checks: `cd web && npm run lint && npm run build`
- Optional full-stack smoke test: `docker compose up --build`

## Deployment notes

- CI workflow (`.github/workflows/deploy.yml`) builds and pushes backend/frontend images on pushes to `master`.
- Manual image commands are documented in `DEPLOY.md`.

If you add runtime dependencies or env vars, update:

- Dockerfiles
- `docker-compose.yml`
- CI workflow
- this skill file