Imported from thethien8a/Job-Search-Web-App-Vibe-Coding (AGENTS.md). Install upstream with npx skills add thethien8a/Job-Search-Web-App-Vibe-Coding. Copyright stays with the author.

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Build/Run Commands

# Full stack (Docker)
docker-compose up -d --build

# Backend dev (from backend/)
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend dev (from frontend/)
npm install
npm run dev             # Vite on :3000, proxies /api to :8000

Architecture

Supabase (public.ready_jobs)  <--  Lakehouse-Lite pipeline loads data here
        |
   FastAPI :8000         # Read-only search API
        |
   Nginx :80             # Serves React SPA + proxies /api -> backend:8000

Frontend: React 18 + Vite + TailwindCSS + TanStack Query + Axios + Lucide React. Backend: FastAPI + SQLAlchemy 2.0 (sync) + psycopg2 → read-only on public.ready_jobs.

Critical Gotchas

• Model vs Index Script mismatch: models.py:14 maps SilverJob to public.ready_jobs, but database_indexes.sql references public_app_layer.silver_jobs. The index script is stale — do not run it as-is on the live DB. The app's actual table is public.ready_jobs with schema public.
• docker-compose.yml init script path: references ./backend/init_db.sql as a volume mount, but the actual file is ./backend/database_indexes.sql. At deployment, either rename the file or fix the compose path.
• Docs disabled in production: main.py:41-44 gates /api/docs, /api/redoc, /api/openapi.json on settings.DEBUG. If API_DEBUG=false, these routes return 404.
• SSL auto-detection: config.py:45 appends ?sslmode=require to the database URL when POSTGRES_HOST is NOT localhost or 127.0.0.1. For local dev, use localhost to avoid SSL errors.

Search Implementation (Non-Obvious)

The /api/v1/jobs endpoint uses a fetch-then-sort-in-Python pattern (routers/jobs.py:108-165):

1. Queries ALL matching job_urls (up to 2000) without ORDER BY (explicitly cleared via query.order_by(None))
2. Sorts them in Python by job_deadline DESC, then job_title
3. Slices the sorted list for pagination
4. Re-fetches full SilverJob objects for only the current page

This is an intentional workaround for PostgreSQL optimizer issues when mixing LIMIT/OFFSET with complex GIN index searches. Do NOT "optimize" this back to a SQL ORDER BY ... LIMIT pattern — pagination will silently return wrong/unsorted results.

The search combines three strategies with OR logic:

• Synonym ILIKE: Hardcoded bilingual EN-VN synonym groups in routers/jobs.py:19-28 (e.g., "intern" → also matches "thực tập", "trainee")
• Full-text search: PostgreSQL plainto_tsquery('english', ...) for English stemming
• Fuzzy matching: pg_trgm similarity with threshold 0.25

Requires pg_trgm extension enabled on the DB.

In-Memory Caching

utils.py defines a custom TTLCache class used via @cache_response() decorator:

• dropdown_cache: TTL 1 hour (locations, source-sites endpoints)
• search_cache: TTL 1 minute (stats endpoint)

This is process-level, in-memory only — cache is not shared across workers.

API Characteristics

• Read-only: CORS allows only GET methods (main.py:57)
• API prefix: /api/v1 (configurable via API_PREFIX env var)
• Rate limiting: 60 req/min per IP via slowapi (main.py:21)
• Error handling: Production hides internal details; DEBUG mode exposes full traceback (main.py:74)