ReadyToClaim - Inventory Management System

A professional inventory management system designed for insurance claims, property documentation, and asset tracking. Built with React, TypeScript, Flask, and Supabase, featuring AI-powered object detection using YOLOv8.

---

📋 Table of Contents

• Project Overview
• Project Structure
• Folder Descriptions
• File Descriptions
• Setup with Docker
• Setup without Docker (Local)
• Deployment (Vercel + Railway)
• Debugging Guide

---

🎯 Project Overview

ReadyToClaim is a full-stack web application that helps users create detailed property inventories for insurance claims. Key features include:

• User Authentication - Secure login/signup with Supabase
• Inventory Management - Create and manage property inventories
• AI Object Detection - Automatically detect furniture and items in room photos using YOLOv8
• Photo Management - Upload and organize photos by room, exterior, and items
• PDF Generation - Generate professional PDF reports for insurance claims
• Role-Based Access - Customer and specialist user roles

---

📁 Project Structure

inventory-web/
├── backend/              # Python Flask backend API
├── public/               # Static assets and HTML template
├── src/                  # React TypeScript frontend source code
├── .dockerignore         # Docker build exclusions
├── .gitignore           # Git ignore rules
├── docker-compose.yml   # Docker orchestration configuration
├── Dockerfile           # Frontend production Dockerfile (Docker/Railway)
├── Dockerfile.dev       # Frontend development Dockerfile
├── vercel.json          # Vercel build and output config
├── nginx.conf           # Nginx configuration (optional)
├── package.json         # Node.js dependencies and scripts
├── package-lock.json    # Locked dependency versions
├── postcss.config.js    # PostCSS configuration for Tailwind
├── tailwind.config.js   # Tailwind CSS configuration
├── tsconfig.json        # TypeScript configuration
└── ADD_OWNER_FIELDS.sql # Database migration script

---

📂 Folder Descriptions

backend/

Python Flask backend API server. Handles:

• PDF generation from inventory data
• AI object detection using YOLOv8
• Image processing and file uploads
• API endpoints for frontend communication

Key files:

• app.py - Main Flask application with all API routes
• requirements.txt - Python dependencies
• Dockerfile - Backend container configuration
• yolov8n.pt - YOLOv8 model weights for object detection
• uploads/ - Directory for storing uploaded and processed images

src/

React TypeScript frontend source code. Contains:

• React components and pages
• Type definitions
• Utility functions
• Application routing and state management

Subdirectories:

• components/ - Reusable React components
• pages/ - Page-level components (routes)
• types/ - TypeScript type definitions
• utils/ - Helper functions and utilities

public/

Static assets served directly by the web server:

• HTML template (index.html)
• Images (logos, signatures)
• Manifest file for PWA
• PDF documents (terms, etc.)

---

📄 File Descriptions

Root Level Files

Configuration Files

package.json

• Node.js project configuration
• Lists all npm dependencies
• Defines npm scripts (start, build, test)
• React, TypeScript, and UI library dependencies

package-lock.json

• Locked versions of all npm dependencies
• Ensures consistent installs across environments
• Auto-generated, do not edit manually

tsconfig.json

• TypeScript compiler configuration
• Defines TypeScript settings and paths
• Enables strict type checking

tailwind.config.js

• Tailwind CSS configuration
• Defines custom colors, spacing, and utilities
• Configures content paths for purging unused styles

postcss.config.js

• PostCSS configuration
• Processes CSS with Tailwind and Autoprefixer
• Required for Tailwind CSS to work

.gitignore

• Files and directories to exclude from Git
• Includes node_modules, build files, .env, etc.

.dockerignore

• Files to exclude from Docker builds
• Reduces image size and build time

Docker Files

docker-compose.yml

• Main Docker Compose configuration
• Defines backend and frontend services
• Configures volumes, networks, and environment variables
• Use this for standard development

Dockerfile

• Production Dockerfile for frontend
• Builds optimized React production bundle and serves with serve on PORT
• Used when deploying the frontend via Docker (e.g. Railway). Not used when deploying with Vercel.

vercel.json

• Vercel build configuration
• Sets buildCommand (with DISABLE_ESLINT_PLUGIN, GENERATE_SOURCEMAP=false), outputDirectory, framework
• Used when deploying the frontend to Vercel

Dockerfile.dev

• Development Dockerfile for frontend
• Sets up React development server with hot-reload
• Used by docker-compose for local development

nginx.conf

• Nginx web server configuration
• Used for serving production frontend builds
• Defines routing and proxy settings

Database Files

ADD_OWNER_FIELDS.sql

• SQL migration script
• Adds owner-related fields to database
• Run this in Supabase SQL editor if needed

Backend Files (backend/)

app.py

• Main Flask application
• Defines all API endpoints:
  • POST /generate-pdf - Generate PDF reports
  • POST /api/detect-furniture - AI object detection
  • GET /health - Health check
• Handles image processing, PDF generation, and YOLO model integration
• ~500 lines of Python code

requirements.txt

• Python package dependencies:
  • Flask - Web framework
  • Flask-CORS - Cross-origin resource sharing
  • gunicorn - Production WSGI server (used in Docker/Railway)
  • ultralytics - YOLOv8 object detection
  • opencv-python-headless - Computer vision
  • numpy - Numerical computing
  • reportlab - PDF generation
  • Pillow - Image processing

Dockerfile

• Backend container configuration
• Installs system dependencies for OpenCV, PyTorch (CPU), and Python deps
• Runs with Gunicorn (production WSGI), listens on PORT (set by Railway)
• Sets YOLO_CONFIG_DIR for writable config in containers
• Exposes port 5000 (default when PORT not set)

yolov8n.pt

• YOLOv8 nano model weights file
• Pre-trained neural network for object detection
• Auto-downloads if not present
• Large file (~6MB)

Frontend Source Files (src/)

Root Files

index.tsx

• React application entry point
• Renders root App component
• Sets up React DOM root

index.css

• Global CSS styles
• Tailwind CSS imports
• Base styles for the application

App.tsx

• Main App component
• Defines React Router routes
• Handles navigation and routing:
  • / - Login page
  • /signup - Signup page
  • /dashboard - User dashboard
  • /inventory/new - Create new inventory
  • /inventory/:id - View/edit inventory
  • /media - Media gallery
  • /specialist-guidelines - Specialist guidelines

supabaseClient.ts

• Supabase client configuration
• Creates and exports Supabase client instance
• Handles authentication and database connections
• Validates environment variables

Components (src/components/)

Header.tsx

• Application header/navigation bar
• Displays logo and navigation links
• User menu and logout functionality

Layout.tsx

• Layout wrapper component
• Provides Header and Footer for protected routes
• Wraps dashboard and inventory pages

inventory/ExteriorPhotosSection.tsx

• Component for uploading exterior photos
• Manages exterior photo gallery
• Part of inventory creation flow

inventory/HouseInfoSection.tsx

• Component for entering house/property information
• Form fields for address, property details, etc.
• Used in inventory creation

inventory/InventoryNameInput.tsx

• Component for entering inventory name
• Simple input field with validation
• Used at start of inventory creation

inventory/ItemInventorySection.tsx

• Main component for managing inventory items
• Handles item creation, editing, deletion
• Manages item photos, descriptions, values
• Complex component with form handling

inventory/RoomDetectionSection.tsx

• AI-powered room detection component
• Upload room photos and detect furniture automatically
• Uses YOLOv8 model via backend API
• Displays detected objects with confidence scores
• Only auto-fills item names if confidence ≥ 50%

inventory/RoomPhotosSection.tsx

• Component for uploading room photos
• Manages room photo galleries
• Organizes photos by room name

Pages (src/pages/)

LoginPage.tsx

• User login page
• Email/password authentication
• Redirects to dashboard on success
• Auto-creates customer profile for new users

SignupPage.tsx

• User registration page
• Creates new user accounts
• Password validation
• Redirects to dashboard after signup

DashboardPage.tsx

• Main user dashboard
• Displays user's inventories
• Role-based view (customer vs specialist)
• Navigation to create/view inventories

InventoryPage.tsx

• Page for creating new inventory
• Initial form for inventory name
• Redirects to detail page after creation

InventoryDetailPage.tsx

• Main inventory editing/viewing page
• Complex page with multiple sections:
  • House information
  • Exterior photos
  • Room photos
  • AI room detection
  • Item inventory
• Handles form submission and PDF generation
• Integrates with AI detection results

MediaPage.tsx

• Media gallery page
• Displays all photos across all inventories
• Browse and view uploaded images

SpecialistGuidelinesPage.tsx

• Guidelines page for specialists
• Displays specialist-specific information
• Role-based content

Types (src/types/)

inventory.ts

• TypeScript type definitions
• Defines Inventory, InventoryItem, and related interfaces
• Ensures type safety across the application

Utils (src/utils/)

imageUtils.ts

• Image processing utility functions
• Image compression, format conversion
• Helper functions for image handling

Public Files (public/)

index.html

• HTML template for React app
• Contains root div and meta tags
• References manifest and favicon

logoV2.png

• Application logo image
• Used in header and login page

signature.png

• Digital signature image
• Used in PDF generation

manifest.json

• Progressive Web App manifest
• Defines app metadata for PWA features

terms.pdf

• Terms and conditions PDF
• Referenced in application

---

🐳 Setup with Docker

Prerequisites

• Docker Desktop installed and running
• Git (if cloning repository)

Step 1: Environment Configuration

Create a .env file in the inventory-web directory:

REACT_APP_SUPABASE_URL=https://your-project.supabase.co
REACT_APP_SUPABASE_ANON_KEY=your_anon_key_here
REACT_APP_API_URL=http://localhost:5000

Get Supabase credentials:

1. Go to https://app.supabase.com
2. Select your project
3. Go to Settings → API
4. Copy Project URL and anon/public key

Step 2: Build and Start Containers

# Navigate to project directory
cd inventory-web

# Build and start all services
docker-compose up --build

First build takes 5-10 minutes (downloads images, installs dependencies)

Step 3: Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:5000
• Health Check: http://localhost:5000/health

Docker Commands

# Start in background (detached mode)
docker-compose up -d

# Stop containers
docker-compose down

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f frontend
docker-compose logs -f backend

# Rebuild after dependency changes
docker-compose up --build

# Restart a service
docker-compose restart frontend
docker-compose restart backend

# Check container status
docker-compose ps

Docker Features

• Hot-reload: Code changes reflect immediately (both frontend and backend)
• Isolated environments: Each service runs in its own container
• Persistent uploads: Images saved in backend/uploads/ persist between restarts
• Network isolation: Services communicate via Docker network

---

💻 Setup without Docker (Local)

Prerequisites

• Node.js (v16 or higher) and npm
• Python (3.11 or higher) and pip
• Git (if cloning repository)

Step 1: Frontend Setup

# Navigate to project directory
cd inventory-web

# Install Node.js dependencies
npm install

# Create .env file (see Docker setup for contents)
# Copy .env.example to .env and fill in values

# Start development server
npm start

Frontend will run on http://localhost:3000

Step 2: Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Start Flask server
python app.py

Backend will run on http://localhost:5000

Step 3: Environment Variables

Create .env file in inventory-web directory:

REACT_APP_SUPABASE_URL=https://your-project.supabase.co
REACT_APP_SUPABASE_ANON_KEY=your_anon_key_here
REACT_APP_API_URL=http://localhost:5000

Note: For local development, you may need to restart the frontend after creating/updating .env file.

Running Both Services

You'll need two terminal windows:

Terminal 1 (Frontend):

cd inventory-web
npm start

Terminal 2 (Backend):

cd inventory-web/backend
python app.py
# or with venv:
venv\Scripts\activate
python app.py

Local Development Features

• Hot-reload: React dev server auto-reloads on file changes
• Backend auto-reload: Flask debug mode reloads on code changes
• Direct file access: Edit files directly, no container overhead

---

🚀 Deployment (Vercel + Railway)

Production setup: Vercel for the frontend, Railway for the backend.

Frontend: Vercel

1. Connect the repo

   • Vercel → Add New Project → Import tbgpt (or your repo).

2. Root Directory

   • Settings → General → Root Directory → inventory-web.

3. Environment variables (Settings → Environment Variables):

   Name	Value	Notes
   REACT_APP_SUPABASE_URL	https://your-project.supabase.co	From Supabase → Settings → API
   REACT_APP_SUPABASE_ANON_KEY	your anon key	From Supabase → Settings → API
   REACT_APP_API_URL	https://your-backend.up.railway.app	Backend public URL (Railway)
   REACT_APP_PDF_API_URL	https://your-backend.up.railway.app	Same as REACT_APP_API_URL

4. Build

   • vercel.json sets buildCommand, outputDirectory, and framework.
   • Deploys run npm install and npm run build; no Docker.

5. Deploy

   • Push to the connected branch or use Redeploy in the Vercel dashboard.

---

Backend: Railway

1. New service

   • Railway → New Project → Deploy from GitHub repo.

2. Root Directory

   • Settings → Root Directory → inventory-web/backend
     (or backend if the project root is already inventory-web).

3. Build

   • Railway uses backend/Dockerfile:
     • Installs PyTorch (CPU), OpenCV, Ultralytics, Gunicorn, etc.
     • Runs: gunicorn -w 1 -b 0.0.0.0:${PORT} --timeout 120 app:app

4. Environment

   • PORT is set by Railway; no need to add it.
   • Optional: FLASK_DEBUG=1 only for debug; leave unset in production.
   • Optional: MODEL_PATH if using a custom YOLO weights path.

5. Public domain

   • Settings → Networking → Generate Domain so the backend has a public URL (e.g. https://your-service.up.railway.app).
   • Use this URL for REACT_APP_API_URL and REACT_APP_PDF_API_URL in Vercel.

6. Endpoints

   • GET /health – health check
   • POST /api/detect-furniture – object detection
   • POST /generate-pdf – PDF generation

---

Deployment summary

	Frontend (Vercel)	Backend (Railway)
Root	inventory-web	inventory-web/backend (or backend)
Build	vercel.json + npm run build	backend/Dockerfile → Gunicorn
Env	REACT_APP_* (Supabase, API URLs)	PORT (automatic), optional MODEL_PATH
URL	Vercel project URL	Railway generated domain

---

After deployment

1. Set Vercel REACT_APP_API_URL and REACT_APP_PDF_API_URL to the Railway backend public URL.
2. Redeploy the Vercel project so the new values are baked into the build.
3. Confirm backend: https://your-backend.up.railway.app/health
4. Open the Vercel URL to use the app.

---

🐛 Debugging Guide

Frontend Debugging

Browser Console Errors

1. Open browser DevTools (F12)
2. Check Console tab for errors
3. Check Network tab for failed API calls
4. Check React DevTools extension for component state

Common Frontend Issues

White Screen / Blank Page

• Check browser console for errors
• Verify .env file exists and has correct values
• Check if backend is running (http://localhost:5000/health)
• Clear browser cache and hard refresh (Ctrl+Shift+R)

API Connection Errors

• Verify REACT_APP_API_URL in .env matches backend URL
• Check if backend is running
• Check CORS settings in backend
• Verify network tab for failed requests

TypeScript Errors

• Check terminal where npm start is running
• Fix type errors shown in terminal
• Ensure all imports are correct

Debugging Commands

# Check for TypeScript errors
npm run build

# Check for linting errors
npm run lint

# Clear npm cache if issues
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Backend Debugging

Flask Debug Mode (local only)

When running locally with python app.py, debug is on when FLASK_DEBUG=1:

app.run(host='0.0.0.0', port=port, debug=os.environ.get('FLASK_DEBUG', '0') == '1')

This provides:

• Auto-reload on code changes
• Detailed error messages
• Interactive debugger (if enabled)

Note: In production (Docker/Railway), the backend uses Gunicorn (backend/Dockerfile); the app.run block is not used. Do not set FLASK_DEBUG=1 in production.

Common Backend Issues

Import Errors (libGL.so.1, etc.)

• Already fixed in Dockerfile with libgl1 package
• For local: Install system dependencies:

  # Ubuntu/Debian
  sudo apt-get install libgl1-mesa-glx libglib2.0-0
  
  # Mac (usually not needed)
  # Windows (usually not needed)

YOLO Model Not Loading

• Check if yolov8n.pt exists in backend/ directory
• Model will auto-download on first use if missing
• Check backend logs for YOLO initialization messages
• Verify ultralytics is installed: pip list | grep ultralytics

Port Already in Use

# Windows - Find process using port 5000
netstat -ano | findstr :5000

# Kill process (replace <PID> with actual process ID)
taskkill /PID <PID> /F

# Mac/Linux
lsof -ti:5000 | xargs kill

Module Not Found Errors

• Verify virtual environment is activated
• Reinstall dependencies: pip install -r requirements.txt
• Check Python version: python --version (should be 3.11+)

Backend Logs

Check backend terminal output for:

• Flask startup messages
• YOLO model loading status
• API request logs
• Error tracebacks

Docker Debugging

Container Not Starting

# Check container status
docker-compose ps

# View all logs
docker-compose logs

# View specific service logs
docker-compose logs backend
docker-compose logs frontend

# Follow logs in real-time
docker-compose logs -f

Common Docker Issues

Build Fails

# Clean Docker cache and rebuild
docker-compose down -v
docker system prune -a
docker-compose up --build

Port Conflicts

# Find what's using the port
netstat -ano | findstr :3000
netstat -ano | findstr :5000

# Kill the process or change ports in docker-compose.yml

Container Keeps Restarting

# Check logs for errors
docker-compose logs backend

# Common causes:
# - Missing environment variables
# - Import errors (check requirements.txt)
# - Port conflicts

Volume Mount Issues

• Verify file paths in docker-compose.yml
• Check file permissions
• Ensure source files exist

Docker Commands for Debugging

# Enter running container
docker-compose exec backend bash
docker-compose exec frontend sh

# Check container resources
docker stats

# Inspect container configuration
docker-compose config

# View container environment variables
docker-compose exec backend env

AI Detection Debugging

YOLO Model Issues

Model Not Detecting Objects

• Check backend logs for YOLO initialization
• Verify image is being sent correctly (check Network tab)
• Lower confidence threshold in frontend (currently 0.10)
• Check if model file exists: backend/yolov8n.pt

Low Detection Accuracy

• This is normal - YOLOv8n is a general-purpose model
• Only high-confidence detections (≥50%) auto-fill names
• Low-confidence items still create inventory entries with images
• Users can manually identify low-confidence items

Detection Endpoint Errors

• Check backend logs for Python errors
• Verify OpenCV is working (check for libGL errors)
• Test endpoint directly: POST http://localhost:5000/api/detect-furniture

Database Debugging

Supabase Connection Issues

Authentication Errors

• Verify REACT_APP_SUPABASE_URL and REACT_APP_SUPABASE_ANON_KEY in .env
• Check Supabase project is active
• Verify Row Level Security (RLS) policies in Supabase

Database Query Errors

• Check browser console for Supabase errors
• Verify table names match in code
• Check Supabase dashboard for table structure
• Review RLS policies if data access fails

General Debugging Tips

1. Check Logs First

   • Browser console (F12)
   • Backend terminal output
   • Docker logs (docker-compose logs)

2. Verify Environment

   • .env file exists and has correct values
   • All services are running
   • Ports are not in use

3. Clear Caches

   • Browser cache (Ctrl+Shift+Delete)
   • npm cache (npm cache clean --force)
   • Docker cache (docker system prune)

4. Check Dependencies

   • npm install for frontend
   • pip install -r requirements.txt for backend
   • Verify versions match package.json and requirements.txt

5. Test Incrementally

   • Test backend API directly (http://localhost:5000/health)
   • Test frontend without backend (will show connection errors)
   • Test each feature individually

---

📝 Notes

• First-time setup takes longer due to dependency installation
• YOLO model auto-downloads on first backend start (~6MB)
• Hot-reload works in both Docker and local development
• Environment variables must be set before starting services
• Database migrations may be needed - check ADD_OWNER_FIELDS.sql
• Production: Frontend on Vercel, backend on Railway — see Deployment

---

🚀 Quick Start Summary

With Docker:

cd inventory-web
# Create .env file with Supabase credentials
docker-compose up --build
# Open http://localhost:3000

Without Docker:

# Terminal 1 - Frontend
cd inventory-web
npm install
npm start

# Terminal 2 - Backend
cd inventory-web/backend
pip install -r requirements.txt
python app.py
# Open http://localhost:3000

Production (Vercel + Railway):

• Frontend: Deploy inventory-web to Vercel (Root: inventory-web). Set REACT_APP_API_URL, REACT_APP_PDF_API_URL, and Supabase vars.
• Backend: Deploy inventory-web/backend to Railway (Root: backend). Generate a public domain and use that URL in the frontend env vars. See Deployment.

---

For more detailed information, refer to individual file comments and code documentation.