giglez/docs/WEBAPP_STARTUP_GUIDE.md

# GigLez Web App Startup Guide

## Problem: Errors When Starting Web App

When running `python3 src/api/main.py`, you encountered multiple errors. Here's what was causing them and how to fix it.

---

## Root Causes

### 1. Import Path Conflict ❌

**Error**:
```
ImportError: cannot import name 'settings' from 'config.settings'
```

**Cause**: Python was importing from the system `config` package instead of the local `config/settings.py`

**Fix**: Added `sys.path.insert(0, ...)` to prioritize local imports

### 2. Database Connection Requirement ❌

**Error**: Application hangs/fails during startup trying to connect to PostgreSQL

**Cause**: The main API (`src/api/main.py`) requires:
- PostgreSQL database connection
- PostGIS extension
- Database initialization

**The startup lifecycle includes**:
```python
# Test database connection
db_config = get_db_config()
if not db_config.test_connection():
    raise RuntimeError("Database connection failed")

if not db_config.test_postgis():
    raise RuntimeError("PostGIS extension not available")
```

This blocks startup if PostgreSQL isn't configured.

---

## Solutions

### Option 1: Simplified Web Server ✅ (Recommended for Testing)

**File**: `src/api/main_simple.py`

**Features**:
- ✅ Serves web interface (HTML, CSS, JS)
- ✅ No database requirement
- ✅ Mock API endpoints (empty data)
- ✅ Perfect for testing UI/UX

**Start command**:
```bash
python3 src/api/main_simple.py
```

**Access**:
```
Web Interface: http://localhost:8000
API Docs:      http://localhost:8000/docs
Health Check:  http://localhost:8000/health
```

**Limitations**:
- ❌ Cannot upload files
- ❌ No database queries
- ❌ No device matching
- ✅ Map, search, and stats work (with empty data)

### Option 2: Full API Server (Requires Database Setup)

**File**: `src/api/main.py`

**Requirements**:
1. PostgreSQL installed and running
2. Database and user created
3. PostGIS extension installed

**Setup steps**:
```bash
# Run database setup script
./scripts/quick_db_setup.sh

# OR manually:
sudo -u postgres psql
CREATE USER giglez_user WITH PASSWORD 'giglez_secure_password_2026';
CREATE DATABASE giglez OWNER giglez_user;
\c giglez
CREATE EXTENSION postgis;
```

**Start command**:
```bash
python3 src/api/main.py
```

---

## Current Status

### ✅ Working Now (Simplified Server)

```bash
# Server is running
python3 src/api/main_simple.py

# Output:
# INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
# INFO:     Application startup complete.
```

**Test it**:
```bash
# Health check
curl http://localhost:8000/health
# Response: {"status":"healthy","database":"not_connected","mode":"simple"}

# Web interface
# Open browser: http://localhost:8000
```

---

## Web Interface Features (Working Now)

### ✅ Available
- Interactive map (Leaflet.js)
- Navigation between sections
- Responsive design
- Statistics dashboard (shows 0s without data)
- Search interface (no results without data)
- Upload form (UI only, backend disabled)

### ⏳ Requires Full Server + Database
- File uploads
- Device matching
- Database queries
- Real capture data on map

---

## Startup Scripts

### Quick Start (Simplified)

**Created**: Simple startup for testing

```bash
python3 src/api/main_simple.py
```

### Full Start (Requires DB)

```bash
# Setup database first
./scripts/quick_db_setup.sh

# Then start full server
python3 src/api/main.py
```

---

## Error Debugging

### If you see: "ImportError: cannot import name 'settings'"

**Fix**: Already fixed in `src/api/main.py` with:
```python
import sys
sys.path.insert(0, str(Path(__file__).parent.parent.parent))
```

### If you see: "Database connection failed"

**Options**:
1. Use simplified server: `python3 src/api/main_simple.py`
2. Setup PostgreSQL: `./scripts/quick_db_setup.sh`

### If you see: "Address already in use"

**Cause**: Port 8000 already in use

**Fix**:
```bash
# Find process
lsof -i :8000

# Kill it
kill -9 <PID>

# Or use different port
python3 src/api/main_simple.py  # Edit file to change port
```

---

## Testing the Web Interface

### 1. Start Server

```bash
cd /home/dell/coding/giglez
python3 src/api/main_simple.py
```

### 2. Open Browser

```
http://localhost:8000
```

### 3. Test Features

**Map View**:
- ✅ Map loads
- ✅ Controls visible
- ⏹️ No markers (no data)

**Upload View**:
- ✅ Drag-drop zone visible
- ✅ GPS input fields work
- ⏹️ Upload disabled (no backend)

**Search View**:
- ✅ Search form visible
- ✅ Filters functional
- ⏹️ No results (no data)

**Statistics View**:
- ✅ Cards display (showing 0s)
- ✅ Charts render (empty)

---

## Next Steps

### For UI/UX Testing (Now)

1. ✅ Use `src/api/main_simple.py`
2. ✅ Test navigation
3. ✅ Test responsive design
4. ✅ Test JavaScript functionality
5. ✅ Verify layout and styling

### For Full Functionality (Later)

1. Setup PostgreSQL database
2. Import signature data
3. Switch to `src/api/main.py`
4. Test uploads and matching

---

## File Comparison

### src/api/main.py (Full API)

**Lines**: 263
**Features**: Complete API with all endpoints
**Requires**: PostgreSQL + PostGIS
**Use case**: Production deployment

### src/api/main_simple.py (Simplified)

**Lines**: 141
**Features**: Web interface + mock endpoints
**Requires**: Nothing
**Use case**: Testing UI/UX

---

## Port Information

**Default Port**: 8000

**Check if running**:
```bash
curl http://localhost:8000/health
```

**View in browser**:
```
http://localhost:8000
```

**API docs**:
```
http://localhost:8000/docs
```

---

## Summary

**Problem**: Main API requires PostgreSQL database
**Solution**: Created simplified version for testing
**Status**: ✅ Web interface accessible and functional
**Command**: `python3 src/api/main_simple.py`
**URL**: http://localhost:8000

The web interface is now running successfully! 🎉