# akira0610/eq-impactmap architecture

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

- Interactive diagram: https://gitdiagram.com/akira0610/eq-impactmap
- Repository: https://github.com/akira0610/eq-impactmap

## Overview

##### Project type and purpose
- This is a full-stack web application (“Global Earthquake Realtime Visualization Platform”) that fetches real-time data from the USGS, processes it, exposes it via a REST API (FastAPI), and visualizes it on an interactive map in the browser.

##### File structure
- Top-level:
- `.github/workflows/deploy.yml` → CI/CD pipeline
- `Dockerfile` → containerization
- `java-fetcher/` → Java-based periodic data-fetcher
- `python-api/` → FastAPI application (routers, services, templates)
- `static/` → CSS/JS assets for the frontend
- Key patterns:
- `java-fetcher/src/EarthquakeFetcher.java` → scheduled fetch-and-push job
- `python-api/routers` and `python-api/services` → clear separation of routing vs business logic
- `python-api/templates` + `static/` → backend-served static assets and HTML views
- Deployment/config: Docker, GitHub Actions

##### README insights
- Components described: USGS → Java Fetcher → FastAPI → Frontend → deck.gl + Mapbox
- Tech stack: Java, Python (FastAPI), HTML/CSS/JS, pydeck/Mapbox

##### Essential elements to capture
- External USGS feed
- Java‐based fetcher service and its schedule
- FastAPI server’s routers and services
- Static/template serving path
- Client-side visualization stack (deck.gl + Mapbox)
- CI/CD pipeline and Docker deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        USGS["USGS Earthquake Catalog\n(REST Feed)"]:::dataSource
    end

    %% Backend Components
    subgraph "Backend Services"
        direction TB
        Fetcher["Java Fetcher Service\n(periodic ETL)"]:::backend
        API["FastAPI Server"]:::backend
        subgraph "FastAPI Components"
            direction TB
            RouterEQ["Router: /earthquakes"]:::backend
            RouterMap["Router: /map"]:::backend
            ServiceFetch["Service: fetcher"]:::backend
            ServiceFilter["Service: filter"]:::backend
            Templates["Templates & Static Handler"]:::backend
        end
    end

    %% Frontend Components
    subgraph "Frontend / Visualization"
        direction TB
        Browser["Browser / Client"]:::frontend
        Template["HTML Template\n(map.html)"]:::frontend
        JS["JavaScript\n(main.js)"]:::frontend
        CSS["CSS\n(styles.css)"]:::frontend
        Viz["Deck.gl + Mapbox GL JS"]:::frontend
    end

    %% DevOps & Infrastructure
    subgraph "DevOps / Infrastructure"
        direction TB
        CI["GitHub Actions\n(deploy.yml)"]:::infra
        Docker["Docker Container\n(Dockerfile)"]:::infra
    end

    %% Data Flows
    USGS -->|"poll every 5 min"| Fetcher
    Fetcher -->|"POST JSON"| API
    API -->|"calls RouterEQ"| RouterEQ
    API -->|"calls RouterMap"| RouterMap
    RouterEQ -->|"uses fetcher logic"| ServiceFetch
    RouterEQ -->|"uses filter logic"| ServiceFilter
    RouterMap -->|"renders map view"| Templates
    Templates --> Template
    Template --> JS
    Template --> CSS
    Browser -->|"GET /earthquakes"| RouterEQ
    Browser -->|"GET /map"| RouterMap
    Browser -->|"load assets"| JS
    Browser -->|"load styles"| CSS
    JS -->|"render data"| Viz
    CI -->|"build & push image"| Docker

    %% Click Events
    click Fetcher "https://github.com/akira0610/eq-impactmap/blob/main/java-fetcher/src/EarthquakeFetcher.java"
    click API "https://github.com/akira0610/eq-impactmap/blob/main/python-api/main.py"
    click RouterEQ "https://github.com/akira0610/eq-impactmap/blob/main/python-api/routers/earthquake.py"
    click RouterMap "https://github.com/akira0610/eq-impactmap/blob/main/python-api/routers/page_map.py"
    click ServiceFetch "https://github.com/akira0610/eq-impactmap/blob/main/python-api/services/fetcher.py"
    click ServiceFilter "https://github.com/akira0610/eq-impactmap/blob/main/python-api/services/filter.py"
    click Template "https://github.com/akira0610/eq-impactmap/blob/main/python-api/templates/map.html"
    click CSS "https://github.com/akira0610/eq-impactmap/blob/main/static/css/styles.css"
    click JS "https://github.com/akira0610/eq-impactmap/blob/main/static/js/main.js"
    click Docker "https://github.com/akira0610/eq-impactmap/tree/main/Dockerfile"
    click CI "https://github.com/akira0610/eq-impactmap/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef dataSource fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
