How tlcfem/motion-base works
Project type and purpose
• motion-base is a full-stack web application (with an optional Electron desktop app and Python client) that provides a unified interface to search, index, and process ground-motion records from multiple national databases.
• Key indicators:
• A “gui” folder with React/Vite code
• Python code under “src/mb” with FastAPI endpoints and Celery tasks
• Docker and Kubernetes manifests for “back”, “front”, “storage”, “worker”
• README describing web UI, Python client, MongoDB and RabbitMQ
File structure
• Top-level dirs:
• docker/ (Compose files, K8s configs, .env template)
• gui/ (React/TypeScript front end)
• electron/ (desktop wrapper around the front end)
• src/mb/ (backend code: API routes in app/, parsing logic in record/, shared utilities)
• tests/ (unit tests for API and record parsers; a locustfile for load testing)
• scripts/ (helper scripts for building, committing, packaging)
• Entrypoints:
• mb_runner.py — launches uvicorn or Celery
• back.Dockerfile, front.Dockerfile
• Config & hooks:
• extra-hooks for Celery and Uvicorn logging, utility/config.py for environment variables
Extract insights from the README
• Backend uses MongoDB for storage and RabbitMQ as Celery broker
• Frontend is a SPA in React served by Vite in dev or Nginx in production
• Supports asynchronous processing (sampling, filtering, response spectra) via Celery workers
• Offers a Python client (mb.client) and an Electron desktop UI
a. Main components
• Clients
• Browser (SPA)
• Electron app (desktop)
• Python client/CLI (async API consumer)
• Frontend service
• Static assets (HTML/CSS/JS) served by Nginx or Vite dev server
• API Gateway / Web server
• FastAPI running under Uvicorn/Gunicorn
• Async processing
• RabbitMQ message broker
• Celery worker pool (parsers, data-processing tasks)
• Data storage
• MongoDB (ground motion records, metadata)
• (Optional) Elasticsearch index for advanced search
• External systems
• Raw data sources (Japan, NZ repositories)
b. Relationships and data flow
1. Client (Browser/Electron/CLI) → HTTP(S) → Frontend or directly to API
2. Frontend → REST API calls → FastAPI server
3. FastAPI routes
– simple queries → MongoDB (or Elasticsearch)
– heavy processing → submit tasks to RabbitMQ → Celery workers
4. Celery workers → process raw files (parse, compute spectra) → store results in MongoDB (and index in ES if used)
5. Backend → return results → Frontend → render to user
c. Architectural patterns & design principles
• Clear separation of concerns:
• gui/ vs src/mb/app vs src/mb/record vs src/mb/utility
• Asynchronous task queue (Celery) for CPU-bound processing
• Microservices-style deployment: each service in its own container
• Configuration via environment variables, Docker Compose, Kubernetes
d. Key technologies & frameworks
• Frontend: React + TypeScript + Vite
• Desktop: Electron
• Backend API: FastAPI + Uvicorn
• Async tasks: Celery + RabbitMQ
• Storage: MongoDB (and optional Elasticsearch)
• Deployment: Docker Compose, Nginx, Kubernetes
Key reminders
• Every piece: browser, Electron, CLI client, static server, API, broker, workers, DB
• Raw-data ingestion paths (Japan & NZ) into the processing pipeline
• “mb_runner.py” as the unified entrypoint for launching API & Celery
• Both Docker Compose and Kubernetes deployment variants if needed