Real-time fish freshness assessment using Edge AI — ensure consumer safety, vendor transparency, and minimize food waste.
Report Bug
·
Request Feature
FreshScan AI analyzes three biologically-significant freshness markers — gill, eye, and body — to produce a single Freshness Index (0–100). Inference runs in under 50ms directly on-device, and anonymized scan data is aggregated onto an interactive Market Trust Map to surface reliable vendor locations.
| Category | Technology |
|---|---|
| Frontend | React 19, TypeScript, Vite, TailwindCSS |
| Backend | FastAPI, Python 3.12 |
| AI / ML | PyTorch, Grad-CAM |
| Database | Supabase (Postgres + Auth + Storage) |
| Deployment | Vercel (frontend), Hugging Face Spaces (backend) |
FreshScanAi/
├── backend/ # FastAPI backend (inference, auth, history, vendors)
│ ├── main.py
│ ├── api/
│ ├── migrations/
│ └── requirements.txt
├── src/ # React frontend
│ ├── components/
│ ├── pages/ # Scanner, Dashboard, MarketMap
│ ├── lib/ # API client and utilities
│ └── App.tsx
├── public/ # Static assets
├── Models/ # Pre-compiled PyTorch model weights
├── Training_Notebook/ # Model training pipelines (Jupyter)
├── scripts/ # Dev setup and backend start scripts
├── DOCUMENTATION.md # Full architecture reference
└── CONTRIBUTING.md # Contribution guidelines
| Requirement | Version |
|---|---|
| Node.js | v18 or later |
| Python | 3.12 or later |
| Git | Any recent version |
git clone https://github.com/jpdevhub/FreshScanAi.git
cd FreshScanAi
npm run setup
npm run devOpen http://localhost:5173 and click DEV LOGIN to bypass Google OAuth locally.
The setup script detects your environment automatically:
| Environment | Database |
|---|---|
| No Docker | Shared dev Supabase (isolated by user_id) |
| Docker + Supabase CLI | Fully local Docker Supabase |
Frontend — copy .env.example to .env.local:
VITE_API_URL= # leave blank for local dev; Vite proxy handles /api/*
VITE_DEV_MODE=true # enables DEV LOGIN button; never set true in productionBackend — copy backend/.env.example to backend/.env:
SUPABASE_URL=http://localhost:54321
SUPABASE_KEY=<auto-filled by npm run setup>
SUPABASE_SERVICE_KEY=
FRONTEND_URL=http://localhost:5173
API_BASE_URL=http://localhost:8000
DEV_BYPASS_AUTH=true # never set true in production| Script | Description |
|---|---|
npm run setup |
Install dependencies, write .env.local (frontend) & .env (backend), optionally start local Supabase |
npm run dev |
Start frontend and backend concurrently |
npm run build |
Production build (TypeScript + Vite) |
npm run lint |
Run ESLint across the codebase |
npm run supabase:start |
Start local Supabase Docker containers |
npm run supabase:stop |
Stop local Supabase Docker containers |
npm run supabase:reset |
Wipe and re-apply migrations with seed data |
| Feature | Status |
|---|---|
| Full UI | localhost:5173 |
| Google OAuth | Bypassed via DEV LOGIN button |
| Fish scanning | Demo mode — random scores, no .pth files needed |
| Grad-CAM heatmap | Synthetic overlay (PIL only) |
| Scan history / DB | Local Docker or shared dev Supabase |
| Market map | Pre-seeded with 8 Kolkata fish markets |
| Real ML inference | Optional — set MODEL_DIR in backend/.env |
| Service | Role | URL |
|---|---|---|
| Vercel | React SPA | https://fresh-scan-ai-sage.vercel.app |
| Hugging Face Spaces | FastAPI + PyTorch | https://karansingh12-freshscan-api.hf.space |
| Supabase | Auth, database, storage | Your project dashboard |
| Variable | Value |
|---|---|
VITE_API_URL |
https://karansingh12-freshscan-api.hf.space |
| Secret | Description |
|---|---|
SUPABASE_URL |
Supabase project URL |
SUPABASE_KEY |
Anon/public key |
SUPABASE_SERVICE_KEY |
Service role key |
FRONTEND_URL |
https://fresh-scan-ai-sage.vercel.app |
API_BASE_URL |
https://karansingh12-freshscan-api.hf.space |
HF_MODEL_REPO |
karansingh12/freshscan-models |
MODEL_TOKEN |
HF token for private model repo |
The Space runs via Dockerfile + startup.sh. Models are downloaded from HF Hub automatically at container start.
In Authentication → URL Configuration, add:
| Setting | Value |
|---|---|
| Site URL | https://fresh-scan-ai-sage.vercel.app |
| Redirect URLs | http://localhost:5173/**, https://fresh-scan-ai-sage.vercel.app/** |
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.
- Fork the repository
- Create a branch:
git checkout -b feat/your-feature - Commit your changes:
git commit -m "feat: description" - Push to your fork:
git push origin feat/your-feature - Open a pull request against
main
For larger changes, open an issue first to discuss your approach.
| Channel | Handle / Address |
|---|---|
| Discord | Razen04 |
| karanrathore23@zohomail.in |
Distributed under the MIT License. See LICENSE for details.