terra-view/README.md

Seismo Fleet Manager - Backend v0.1

Backend API 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

• Fleet Monitoring: Track all seismograph units in one place
• Status Management: Automatically mark units as OK, Pending (>12h), or Missing (>24h)
• Data Ingestion: Accept reports from emitter scripts via REST API
• SQLite Storage: Lightweight, file-based database for easy deployment

Tech Stack

• FastAPI: Modern, fast web framework
• SQLAlchemy: SQL toolkit and ORM
• SQLite: Lightweight database
• uvicorn: ASGI server
• Docker: Containerization for easy deployment

Quick Start with Docker Compose (Recommended)

Prerequisites

• Docker and Docker Compose installed

Running the Application

1. Start the service:

   docker compose up -d
   

2. Check logs:

   docker compose logs -f
   

3. Stop the service:

   docker compose down
   

The API will be available at http://localhost:8000

Data Persistence

The SQLite database is 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

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run the server:

   python main.py
   

   Or with auto-reload:

   uvicorn main:app --reload
   

The API will be available at http://localhost:8000

API Endpoints

Root

• GET / - Health check

Emitter Report

• POST /emitters/report
• Submit status report from a seismograph unit
• Request Body:

  {
    "unit": "SEISMO-001",
    "unit_type": "series3",
    "timestamp": "2025-11-20T10:30:00",
    "file": "event_20251120_103000.dat",
    "status": "OK"
  }
  

• Response:

  {
    "message": "Emitter report received",
    "unit": "SEISMO-001",
    "status": "OK"
  }
  

Fleet Status

• GET /fleet/status
• Retrieve status of all seismograph units
• Response:

  [
    {
      "id": "SEISMO-001",
      "unit_type": "series3",
      "last_seen": "2025-11-20T10:30:00",
      "last_file": "event_20251120_103000.dat",
      "status": "OK",
      "notes": null
    }
  ]
  

API Documentation

Once running, interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Testing the API

Using curl

Submit a report:

curl -X POST http://localhost:8000/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:8000/fleet/status

Using Python

import requests
from datetime import datetime

# Submit report
response = requests.post(
    "http://localhost:8000/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:8000/fleet/status")
print(response.json())

Data Model

Emitters Table

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/
├── main.py              # FastAPI app entry point
├── database.py          # SQLAlchemy database configuration
├── models.py            # Database models
├── routes.py            # API endpoints
├── requirements.txt     # Python dependencies
├── Dockerfile           # Docker container definition
├── docker-compose.yml   # Docker Compose configuration
├── .dockerignore        # Docker ignore rules
└── data/                # SQLite database directory (created at runtime)

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

Stop and remove containers:

docker compose down

Remove containers and volumes:

docker compose down -v

Future Enhancements

• Automated status updates based on last_seen timestamps
• Web-based dashboard for fleet monitoring
• Email/SMS alerts for missing units
• Historical data tracking and reporting
• Multi-user authentication
• PostgreSQL support for larger deployments

License

MIT

Version

0.1.0 - Initial Release