# tlcfem/motion-base architecture

> Architecture diagram of the GitHub repository tlcfem/motion-base, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tlcfem/motion-base
- Repository: https://github.com/tlcfem/motion-base

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Browser["Browser SPA"]:::client
        Electron["Electron Desktop App"]:::client
        CLI["Python Client/CLI"]:::client
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        Nginx["Static Server (Nginx/Vite)"]:::frontend
        Frontend["React SPA"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        API["FastAPI Server"]:::backend
        Runner["mb_runner.py"]:::backend
    end

    %% Async Processing
    subgraph "Async Processing"
        Broker["RabbitMQ"]:::async
        Worker["Celery Workers"]:::async
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["MongoDB"]:::data
        ES["Elasticsearch (optional)"]:::data
    end

    %% External Data Sources
    subgraph "External Data Sources"
        Japan["Japan Raw Data"]:::external
        NZ["NZ Raw Data"]:::external
    end

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        Docker["Docker / Kubernetes"]:::deployment
    end

    %% Connections
    Browser --> Nginx
    Browser --> Frontend
    Electron --> Frontend
    CLI --> API
    Frontend --> API
    Nginx --> Frontend
    API -->|"Query / Write"| DB
    API -->|"Query"| ES
    API -->|"Enqueue Task"| Broker
    Broker --> Worker
    Worker -->|"Process & Store"| DB
    Worker -->|"Index Results"| ES
    Japan --> Worker
    NZ --> Worker
    Runner --> API
    Runner --> Worker

    Docker --- Nginx
    Docker --- API
    Docker --- Broker
    Docker --- Worker
    Docker --- DB
    Docker --- ES

    %% Click Events
    click Browser "https://github.com/tlcfem/motion-base/tree/master/gui/"
    click Electron "https://github.com/tlcfem/motion-base/tree/master/electron/"
    click CLI "https://github.com/tlcfem/motion-base/blob/master/src/mb/client.py"
    click API "https://github.com/tlcfem/motion-base/tree/master/src/mb/app/"
    click Runner "https://github.com/tlcfem/motion-base/blob/master/mb_runner.py"
    click Broker "https://github.com/tlcfem/motion-base/blob/master/src/mb/celery.py"
    click Docker "https://github.com/tlcfem/motion-base/tree/master/docker/"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef frontend fill:#d4edda,stroke:#155724,color:#155724;
    classDef backend fill:#fff3cd,stroke:#856404,color:#856404;
    classDef async fill:#ffeeba,stroke:#856404,color:#856404;
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef deployment fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
