# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project overview

Urine test strip recognition system (尿检识别系统) — a full-stack web app that analyzes photos of medical urine reagent strips. Two analysis modes:

- **Image mode**: Upload a strip photo → OpenCV computer vision pipeline locates reagent pads and extracts color values in RGB/HSV/LAB.
- **JSON data mode**: Upload pre-extracted color data → OpenCV Random Trees ML models infer semi-quantitative results (negative, +, ++, etc.) per analyte.

The system was ported from a C++ HarmonyOS app (`/home/ubuntu/nanocode/UrineCheck/`).

## Commands

```bash
# Backend (Python/FastAPI)
cd backend
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8904
# OR: python app.py

# Frontend (React/Vite)
cd frontend
npm install
npm run dev          # dev server on :8905, proxies /api → :8904
npm run build        # production build to dist/
```

There are **no application-level tests** (no pytest, no Jest/Vitest).

## Architecture

```
Browser → :8905 (Vite/React) ──/api──proxy──→ :8904 (FastAPI/Uvicorn)
                                                   │
                  SSO Center (:9000) ←── JWT cookie verification
```

### Backend (`backend/`)

- **`app.py`** — FastAPI entry point. Creates SQLite tables on startup, registers `auth` and `urinecheck` routers, CORS configured for localhost + `129.211.173.87`.
- **`routers/auth.py`** — Dual-mode auth: local username/password (JWT bearer token, 30-day expiry, stored in localStorage) and SSO cookie validation (decodes JWT from `access_token` cookie using a shared secret). Default admin `admin`/`admin123` created on first startup.
- **`routers/urinecheck.py`** — Two endpoints: `POST /api/urinecheck/analyze` (multipart image upload → CV recognition) and `POST /api/urinecheck/analyze-json` (JSON body → ML inference).
- **`database.py`** / **`models.py`** — SQLAlchemy + SQLite. Single `admins` table (id, username, password_hash, created_at). Database file: `backend/urinecheck.db`.
- **`schemas.py`** — Pydantic request/response models for both endpoints.
- **`sso_client.py`** — Reads `access_token` cookie, decodes JWT locally with a shared secret key. Validates against external SSO at `http://129.211.173.87:9000`.

### Two recognition pipelines

#### Image-based CV pipeline (`urine_recognizer.py`, ~1180 lines — the largest file)

`UrineStripRecognizer` class implements a 7-step algorithm:
1. Preprocess (BGR/HSV/Gray conversion, Gaussian blur)
2. Detect locator blocks (HSV color segmentation, contour finding with Canny fallback)
3. Filter candidates (area, aspect ratio, rectangularity, Y-clustering, pair validation by color + RGB distance + area ratio)
4. Blur assessment (Laplacian variance → 3 sharpness levels)
5. Spec matching (distance ratio + area ratio → matches one of 6 PaperConfigs)
6. Calculate color block centers (edge-to-edge interpolation)
7. Read colors (white balance, circular ROI sampling → RGB/HSV/LAB output)

`PaperConfig` holds the geometric layout for 6 strip specifications (8/11/14 pads × S-type 10mm / L-type 15mm locators). `ColorReader` handles white balancing and color-space extraction.

#### JSON-based ML pipeline (`json_recognizer.py`, ~430 lines)

`UrineJsonRecognizer` class:
- Loads OpenCV RTrees models from `/usr/local/Models/*.data`
- Processes multi-frame data and takes majority vote across frames
- Applies analyte-specific result index corrections (14 correction functions per strip color type)
- Enforces PRO/MAU and SG/pH cross-correlation rules

### ML model configuration (`ml_config.py`)

`MLConfigLoader` singleton parses `/usr/local/Models/ml.json` which defines model files, positions, algorithms, and result index maps for 21 paper types × 15 positions.

### Frontend (`frontend/src/`)

- **React 18 + React Router 6 + Vite 5 + Tailwind CSS 3**
- `App.jsx` — Route definitions with `PrivateRoute` auth wrapper.
- `pages/Login.jsx` — Local auth form + SSO redirect support.
- `pages/UrineCheck.jsx` — Image upload + results display.
- `pages/JsonDataCheck.jsx` — JSON/paste upload + ML results table.
- `api/config.js` — Axios instance configured with `baseURL` from `import.meta.env.VITE_API_BASE_URL` (falls back to current origin).

## Ports

| Service | Port |
|---------|------|
| Frontend (Vite dev) | 8905 |
| Backend (Uvicorn) | 8904 |
| SSO Center | 9000 |

Frontend dev server proxies `/api/*` to `http://localhost:8904`.

## Deployment

systemd units in `deploy/`:
- `urinecheck-backend.service` — runs uvicorn as user `ubuntu` from `backend/`
- `urinecheck-frontend.service` — runs `npm run dev` as user `ubuntu` from `frontend/`

The ML model files (`/usr/local/Models/ml.json` and `/usr/local/Models/*.data`) must be present on the server — they are not in this repository.

## Key dependencies

Backend: `fastapi`, `uvicorn`, `sqlalchemy` (SQLite), `python-jose` (JWT), `passlib[bcrypt]`, `opencv-python-headless`, `numpy`
Frontend: `react` 18, `react-router-dom` 6, `axios`, `vite` 5, `tailwindcss` 3, `preline` (UI component library)