terra-view/FRONTEND_README.md

# Seismo Fleet Manager - Frontend Documentation

## Overview

This is the MVP frontend scaffold for **Seismo Fleet Manager**, built with:
- **FastAPI** (backend framework)
- **HTMX** (dynamic updates without JavaScript frameworks)
- **TailwindCSS** (utility-first styling)
- **Jinja2** (server-side templating)
- **Leaflet** (interactive maps)

No React, Vue, or other frontend frameworks are used.

## Project Structure

```
seismo-fleet-manager/
├── backend/
│   ├── main.py                 # FastAPI app entry point
│   ├── routers/
│   │   ├── roster.py          # Fleet roster endpoints
│   │   ├── units.py           # Individual unit endpoints
│   │   └── photos.py          # Photo management endpoints
│   ├── services/
│   │   └── snapshot.py        # Mock status snapshot (replace with real logic)
│   ├── static/
│   │   └── style.css          # Custom CSS
│   ├── database.py            # SQLAlchemy database setup
│   ├── models.py              # Database models
│   └── routes.py              # Legacy API routes
├── templates/
│   ├── base.html              # Base layout with sidebar & dark mode
│   ├── dashboard.html         # Main dashboard page
│   ├── roster.html            # Fleet roster page
│   ├── unit_detail.html       # Unit detail page
│   └── partials/
│       └── roster_table.html  # HTMX partial for roster table
├── data/
│   └── photos/                # Photo storage (organized by unit_id)
└── requirements.txt
```

## Running the Application

### Install Dependencies

```bash
pip install -r requirements.txt
```

### Run the Server

```bash
uvicorn backend.main:app --host 0.0.0.0 --port 8001 --reload
```

The application will be available at:
- **Web UI**: http://localhost:8001/
- **API Docs**: http://localhost:8001/docs
- **Health Check**: http://localhost:8001/health

## Features

### 1. Dashboard (`/`)

The main dashboard provides an at-a-glance view of the fleet:

- **Fleet Summary Card**: Total units, deployed units, status breakdown
- **Recent Alerts Card**: Shows units with Missing or Pending status
- **Recent Photos Card**: Placeholder for photo gallery
- **Fleet Status Preview**: Quick view of first 5 units

**Auto-refresh**: Dashboard updates every 10 seconds via HTMX

### 2. Fleet Roster (`/roster`)

A comprehensive table view of all seismograph units:

**Columns**:
- Status indicator (colored dot: green=OK, yellow=Pending, red=Missing)
- Deployment indicator (blue dot if deployed)
- Unit ID
- Last seen timestamp
- Age since last contact
- Notes
- Actions (View detail button)

**Features**:
- Auto-refresh every 10 seconds
- Sorted by priority (Missing > Pending > OK)
- Click any row to view unit details

### 3. Unit Detail Page (`/unit/{unit_id}`)

Split-screen layout with detailed information:

**Left Column**:
- Status card with real-time updates
- Deployment status
- Last contact time and file
- Notes section
- Editable metadata (mock form)

**Right Column - Tabbed Interface**:
- **Photos Tab**: Primary photo with thumbnail gallery
- **Map Tab**: Interactive Leaflet map showing unit location
- **History Tab**: Placeholder for event history

**Auto-refresh**: Unit data updates every 10 seconds

### 4. Dark/Light Mode

Toggle button in sidebar switches between themes:
- Uses Tailwind's `dark:` classes
- Preference saved to localStorage
- Smooth transitions on theme change

## API Endpoints

### Status & Fleet Data

```http
GET /api/status-snapshot
```
Returns complete fleet status snapshot with statistics.

```http
GET /api/roster
```
Returns sorted list of all units for roster table.

```http
GET /api/unit/{unit_id}
```
Returns detailed information for a single unit including coordinates.

### Photo Management

```http
GET /api/unit/{unit_id}/photos
```
Returns list of photos for a unit, sorted by recency.

```http
GET /api/unit/{unit_id}/photo/{filename}
```
Serves a specific photo file.

### Legacy Endpoints

```http
POST /emitters/report
```
Endpoint for emitters to report status (from original backend).

```http
GET /fleet/status
```
Returns database-backed fleet status (from original backend).

## Mock Data

### Location: `backend/services/snapshot.py`

The `emit_status_snapshot()` function currently returns mock data with 8 units:

- **BE1234**: OK, deployed (San Francisco)
- **BE5678**: Pending, deployed (Los Angeles)
- **BE9012**: Missing, deployed (New York)
- **BE3456**: OK, benched (Chicago)
- **BE7890**: OK, deployed (Houston)
- **BE2468**: Pending, deployed
- **BE1357**: OK, benched
- **BE8642**: Missing, deployed

**To replace with real data**: Update the `emit_status_snapshot()` function to call your Series3 emitter logic.

## Styling

### Color Palette

The application uses your brand colors:

```css
orange:   #f48b1c
navy:     #142a66
burgundy: #7d234d
```

These are configured in the Tailwind config as `seismo-orange`, `seismo-navy`, `seismo-burgundy`.

### Cards

All cards use the consistent styling:
```html
<div class="rounded-xl shadow-lg bg-white dark:bg-slate-800 p-6">
```

### Status Indicators

- Green dot: OK status
- Yellow dot: Pending status
- Red dot: Missing status
- Blue dot: Deployed
- Gray dot: Benched

## HTMX Usage

HTMX enables dynamic updates without writing JavaScript:

### Auto-refresh Example (Dashboard)

```html
<div hx-get="/api/status-snapshot"
     hx-trigger="load, every 10s"
     hx-swap="none"
     hx-on::after-request="updateDashboard(event)">
```

This fetches the snapshot on page load and every 10 seconds, then calls a JavaScript function to update the DOM.

### Partial Template Loading (Roster)

```html
<div hx-get="/partials/roster-table"
     hx-trigger="load, every 10s"
     hx-swap="innerHTML">
```

This replaces the entire inner HTML with the server-rendered roster table every 10 seconds.

## Adding Photos

To add photos for a unit:

1. Create a directory: `data/photos/{unit_id}/`
2. Add image files (jpg, jpeg, png, gif, webp)
3. Photos will automatically appear on the unit detail page
4. Most recent file becomes the primary photo

Example:
```bash
mkdir -p data/photos/BE1234
cp my-photo.jpg data/photos/BE1234/deployment-site.jpg
```

## Customization

### Adding New Pages

1. Create a template in `templates/`
2. Add a route in `backend/main.py`:

```python
@app.get("/my-page", response_class=HTMLResponse)
async def my_page(request: Request):
    return templates.TemplateResponse("my_page.html", {"request": request})
```

3. Add a navigation link in `templates/base.html`

### Adding New API Endpoints

1. Create a router file in `backend/routers/`
2. Include the router in `backend/main.py`:

```python
from backend.routers import my_router
app.include_router(my_router.router)
```

## Docker Deployment

The project includes Docker configuration:

```bash
docker-compose up
```

This will start the application on port 8001 (configured to avoid conflicts with port 8000).

## Next Steps

1. **Replace Mock Data**: Update `backend/services/snapshot.py` with real Series3 emitter logic
2. **Database Integration**: The existing SQLAlchemy models can store historical data
3. **Photo Upload**: Add a form to upload photos from the UI
4. **Projects Management**: Implement the "Projects" page
5. **Settings**: Add user preferences and configuration
6. **Event History**: Populate the History tab with real event data
7. **Authentication**: Add user login/authentication if needed
8. **Notifications**: Add real-time alerts for critical status changes

## Development Tips

- The `--reload` flag auto-reloads the server when code changes
- Use browser DevTools to debug HTMX requests (look for `HX-Request` headers)
- Check `/docs` for interactive API documentation (Swagger UI)
- Dark mode state persists in browser localStorage
- All timestamps are currently mock data - replace with real values

## License

See main README.md for license information.