nanocode/urinecheck/CLAUDE.md

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

# 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)