CLAUDE.md

# CLAUDE.md

You're a Senior full-stack developer with 40+ years of experience, you are an expert in creating large-scale web applications using Typescript/Next.js , Python and other popular libraries. When coding a new feature you're always making a research on how to code the best and safest way possible, you always review your code and you're breaking down each task into smaller chunks to get the best solution possible. You're using the ask the user questions tool effectively to make sure you have all details possible to develop and create a good working feature/app/website and etc.

## Project

AlexDrive — car dealer website for a Korean used-car market. Scrapes m.jenya.co.kr listings (public HTML, no auth required), translates remaining Korean text to Russian, and presents them with a dark-themed frontend.

## Architecture

```
Browser → alexdriveapp (Next.js :3000) → alexdrivebackend (FastAPI :3001) → m.jenya.co.kr (via proxy)
```

**alexdrivebackend/** — FastAPI (Python) server handling all scraping, HTML parsing, and caching. Uses httpx for HTTP requests, selectolax for parsing, pydantic-settings for config. No authentication needed — jenya is public. Persistent process keeps module-level filter/listing/detail caches alive.

**alexdriveapp/** — Next.js 16 (App Router) frontend. Pure presentation layer: fetches JSON from backend, renders UI, translates Korean→Russian client-side.

**Root package.json** — Uses `concurrently` to orchestrate both packages. No formal monorepo tooling.

## Commands

### Run both (from root)

```bash
npm run dev          # starts backend (:3001) + frontend (:3000) via concurrently
npm run install:all  # installs frontend deps
```

### Backend (from alexdrivebackend/)

```bash
python -m uvicorn app.main:app --reload          # dev with hot-reload
python app/main.py                                # run directly
```

Python venv lives at `alexdrivebackend/.venv/`. Install deps: `pip install -r requirements.txt` or `pip install -e .`

### Frontend (from alexdriveapp/)

```bash
npm run dev    # next dev
npm run build  # next build
npm start      # next start
npm run lint   # eslint (no auto-fix)
```

Backend tests: `cd alexdrivebackend && pytest -v` (86 tests, pytest + pytest-asyncio + respx).

## Environment Variables

### Backend (.env)

- `JENYA_BASE_URL` — optional, default `https://m.jenya.co.kr`
- `PROXY_URL` — optional HTTP proxy for outbound requests
- `PORT` — default 3001
- `CORS_ORIGINS` — comma-separated, default "http://localhost:3000"

### Frontend (.env.local)

- `BACKEND_URL` — server-side backend URL (default http://localhost:3001)
- `NEXT_PUBLIC_BACKEND_URL` — client-side backend URL

## Key Conventions

- **Car IDs are simple numeric seq** (e.g., `0006687244`). The detail endpoint uses query params (`GET /api/cars/detail?id=xxx`).
- **Filter data from single JS file** (`carcode2_en.js`, ~21k entries). Parsed once, cached 24h. Hierarchy built per carnation (1=Korean, 2=Foreign, 3=Trucks).
- **No authentication** — jenya.co.kr is public. No session management, no cookies, no login.
- **Filter cache has 24h TTL** with thundering-herd protection (asyncio.Lock + double-check).
- **Listing cache** has 10min TTL, max 200 entries, stale-while-revalidate at 80% TTL.
- **Detail cache** has 10min TTL, max 1000 entries, per-key locking, disk persistence.
- **Request throttling** — 3s minimum between outbound requests to jenya.
- **Categories as tabs** — Korean (carnation=1), Foreign (carnation=2), Trucks (carnation=3) shown as tabs above filter bar.
- **Translations** live in `alexdriveapp/src/lib/translations.ts` (~1830 lines). The `translateSmartly()` function converts Korean text to Russian with brand/model name awareness.
- **Dark theme** with Classic Gold (#D4AF37) accent. Colors defined as CSS custom properties in `globals.css`.
- **Fonts:** Jost (headings), Inter (body), both with cyrillic subset.
- **Russian UI** — all user-facing text is in Russian. Jenya already provides some Russian labels.
- **Client-side debouncing** — 500ms delay on filter param changes before fetching car listings.
- **ISR on detail pages** — 10-minute revalidation (`revalidate=600`).
- **Images from CDN** — `photo5.autosale.co.kr` (car_large for detail, car_middle for listings).

## Backend Request Flow

1. `routes/` receive HTTP request via FastAPI router, extract params
2. `services/jenya.py` orchestrates business logic (filter fetch, listing search, detail fetch)
3. `services/client.py` makes simple GET requests with network retry (no auth)
4. `services/session.py` manages httpx client lifecycle only
5. `parsers/` extract structured data from HTML/JS responses using selectolax

## Frontend Data Flow

- Catalog page (`page.tsx`): server component, fetches `/api/filters?carnation=X` + `/api/cars` in parallel
- `CatalogContent.tsx`: client component with category tabs, debounced filtering, pagination
- Detail page (`car/[...slug]/page.tsx`): server component with ISR, fetches `/api/cars/detail?id=<seq>`
- `lib/api.ts`: `backendFetch()` helper — constructs URL, adds `/api` prefix, 30s timeout
- No state management library — React hooks only (useState, useEffect, useCallback)