Backend API and web interface for managing seismograph fleet status. Track multiple seismographs calling in data from remote deployments, monitor their status, and manage your fleet through a unified database.

Features

Web Dashboard: Modern, responsive UI with dark/light mode support
Fleet Monitoring: Track all seismograph units in one place
Roster Management: Full CRUD operations via API or CSV import (New in v0.1.1)
Status Management: Automatically mark units as OK, Pending (>12h), or Missing (>24h)
Data Ingestion: Accept reports from emitter scripts via REST API
Photo Management: Upload and view photos for each unit
Interactive Maps: Leaflet-based maps showing unit locations
SQLite Storage: Lightweight, file-based database for easy deployment

Tech Stack

FastAPI: Modern, fast web framework
SQLAlchemy: SQL toolkit and ORM
SQLite: Lightweight database
HTMX: Dynamic updates without heavy JavaScript frameworks
TailwindCSS: Utility-first CSS framework
Leaflet: Interactive maps
Jinja2: Server-side templating
uvicorn: ASGI server
Docker: Containerization for easy deployment

Quick Start with Docker Compose (Recommended)

Prerequisites

Docker and Docker Compose installed

Running the Application

Start the service:
```
docker compose up -d
```
Check logs:
```
docker compose logs -f
```
Stop the service:
```
docker compose down
```

The application will be available at:

Web Interface: http://localhost:8001
API Documentation: http://localhost:8001/docs
Health Check: http://localhost:8001/health

Data Persistence

The SQLite database and photos are stored in the ./data directory, which is mounted as a volume. Your data will persist even if you restart or rebuild the container.

Local Development (Without Docker)

Prerequisites

Python 3.11+
pip

Setup

Install dependencies:
```
pip install -r requirements.txt
```

Run the server:

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

The application will be available at http://localhost:8001

API Endpoints

Web Pages

GET / - Dashboard home page
GET /roster - Fleet roster page
GET /unit/{unit_id} - Unit detail page

Fleet Status & Monitoring

GET /api/status-snapshot - Complete fleet status snapshot
GET /api/roster - List of all units with metadata
GET /api/unit/{unit_id} - Detailed unit information
GET /health - Health check endpoint

Roster Management (New in v0.1.1)

POST /api/roster/add - Add new unit to roster

curl -X POST http://localhost:8001/api/roster/add \
  -F "id=BE1234" \
  -F "unit_type=series3" \
  -F "deployed=true" \
  -F "note=Main site sensor"

POST /api/roster/set-deployed/{unit_id} - Toggle deployment status
POST /api/roster/set-retired/{unit_id} - Toggle retired status
POST /api/roster/set-note/{unit_id} - Update unit notes

POST /api/roster/import-csv - Bulk import from CSV

curl -X POST http://localhost:8001/api/roster/import-csv \
  -F "file=@roster.csv" \
  -F "update_existing=true"

CSV Import Format

Create a CSV file with the following columns (only unit_id is required):

unit_id,unit_type,deployed,retired,note,project_id,location
BE1234,series3,true,false,Primary sensor,PROJ-001,San Francisco CA
BE5678,series3,true,false,Backup sensor,PROJ-001,Los Angeles CA

See sample_roster.csv for a working example.

Emitter Reporting

POST /emitters/report - Submit status report from a seismograph unit
POST /api/series3/heartbeat - Series3 multi-unit telemetry payload
GET /fleet/status - Retrieve status of all seismograph units (legacy)

Photo Management

GET /api/unit/{unit_id}/photos - List photos for a unit
GET /api/unit/{unit_id}/photo/{filename} - Serve specific photo file

API Documentation

Once running, interactive API documentation is available at:

Swagger UI: http://localhost:8001/docs
ReDoc: http://localhost:8001/redoc

Testing the API

Using curl

Submit a report:

curl -X POST http://localhost:8001/emitters/report \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "SEISMO-001",
    "unit_type": "series3",
    "timestamp": "2025-11-20T10:30:00",
    "file": "event_20251120_103000.dat",
    "status": "OK"
  }'

Get fleet status:

curl http://localhost:8001/api/roster

Import roster from CSV:

curl -X POST http://localhost:8001/api/roster/import-csv \
  -F "file=@sample_roster.csv" \
  -F "update_existing=true"

Using Python

import requests
from datetime import datetime

# Submit report
response = requests.post(
    "http://localhost:8001/emitters/report",
    json={
        "unit": "SEISMO-001",
        "unit_type": "series3",
        "timestamp": datetime.utcnow().isoformat(),
        "file": "event_20251120_103000.dat",
        "status": "OK"
    }
)
print(response.json())

# Get fleet status
response = requests.get("http://localhost:8001/api/roster")
print(response.json())

# Import CSV
with open('roster.csv', 'rb') as f:
    files = {'file': f}
    data = {'update_existing': 'true'}
    response = requests.post(
        "http://localhost:8001/api/roster/import-csv",
        files=files,
        data=data
    )
print(response.json())

Data Model

RosterUnit Table (Your Fleet Roster)

Field	Type	Description
id	string	Unit identifier (primary key)
unit_type	string	Type of seismograph (default: "series3")
deployed	boolean	Whether unit is deployed in field
retired	boolean	Whether unit is retired from service
note	string	Notes about the unit
project_id	string	Associated project identifier
location	string	Deployment location description
last_updated	datetime	Last modification timestamp

Emitter Table (Device Check-ins)

Field	Type	Description
id	string	Unit identifier (primary key)
unit_type	string	Type of seismograph (e.g., "series3")
last_seen	datetime	Last report timestamp
last_file	string	Last file processed
status	string	Current status: OK, Pending, Missing
notes	string	Optional notes (nullable)

Project Structure

seismo-fleet-manager/
├── backend/
│   ├── main.py              # FastAPI app entry point
│   ├── database.py          # SQLAlchemy database configuration
│   ├── models.py            # Database models (RosterUnit, Emitter)
│   ├── routes.py            # Legacy API endpoints
│   ├── routers/             # Modular API routers
│   │   ├── roster.py        # Fleet status endpoints
│   │   ├── roster_edit.py   # Roster management & CSV import
│   │   ├── units.py         # Unit detail endpoints
│   │   ├── photos.py        # Photo management
│   │   ├── dashboard.py     # Dashboard partials
│   │   └── dashboard_tabs.py # Dashboard tab endpoints
│   ├── services/
│   │   └── snapshot.py      # Fleet status snapshot logic
│   └── static/              # Static assets (CSS, etc.)
├── templates/               # Jinja2 HTML templates
│   ├── base.html            # Base layout with sidebar
│   ├── dashboard.html       # Main dashboard
│   ├── roster.html          # Fleet roster table
│   ├── unit_detail.html     # Unit detail page
│   └── partials/            # HTMX partial templates
├── data/                    # SQLite database & photos (persisted)
├── requirements.txt         # Python dependencies
├── Dockerfile               # Docker container definition
├── docker-compose.yml       # Docker Compose configuration
├── CHANGELOG.md             # Version history
├── FRONTEND_README.md       # Frontend documentation
└── README.md                # This file

Docker Commands

Build the image:

docker compose build

Start in foreground:

docker compose up

Start in background:

docker compose up -d

View logs:

docker compose logs -f seismo-backend

Restart service:

docker compose restart

Rebuild and restart:

docker compose up -d --build

Stop and remove containers:

docker compose down

Remove containers and volumes:

docker compose down -v

What's New in v0.1.1

Roster Editing API: Full CRUD operations for managing your fleet roster
CSV Import: Bulk upload roster data from CSV files
Enhanced Data Model: Added project_id and location fields to roster
Bug Fixes: Improved database session management and error handling
Dashboard Improvements: Separate views for Active, Benched, and Retired units

See CHANGELOG.md for complete version history.

Future Enhancements

Email/SMS alerts for missing units
Historical data tracking and reporting
Multi-user authentication
PostgreSQL support for larger deployments
Advanced filtering and search
Export roster to various formats
Automated backup and restore

License

MIT

Version

Current: 0.1.1 - Roster Management & CSV Import (2025-12-02)

Previous: 0.1.0 - Initial Release (2024-11-20)