# stac-iitmandi/xray-burst-detection architecture

> Architecture diagram of the GitHub repository stac-iitmandi/xray-burst-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stac-iitmandi/xray-burst-detection
- Repository: https://github.com/stac-iitmandi/xray-burst-detection

## Overview

This is a Flask-based solar X-ray burst identifier. The principal workflow is browser upload, server-side file parsing and time-series normalization, burst detection, downloadable result generation, then status/result polling and graph visualization. The graph includes the core parser, model, and output stages plus the documented upload and visualization paths. Source excerpts support the backend calls; page-template internals and unsampled UI wiring are not inspected, so those links are limited to documented or directly shown routes.

Main entry points: [`app.py`](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/app.py) (Flask routes), [`fileparsers/__init__.py`](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py) (Analysis orchestration), [`static/visualise.js`](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/static/visualise.js) (Burst visualization), [`static/upload.js`](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/static/upload.js) (File upload UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_upload_ui["File upload UI<br/>[upload.js]"]
  node_web_app["Flask routes<br/>[app.py]"]
  node_visualization["Burst visualization<br/>[visualise.js]"]
  node_guide_page["User guide page<br/>[guide.html]"]
end

subgraph group_analysis["Analysis pipeline"]
  node_analysis_orchestrator["Analysis orchestration<br/>[__init__.py]"]
  node_burst_model["Burst detection<br/>[model.py]"]
end

subgraph group_formats["File formats"]
  node_input_parsers["Input parsers<br/>[read.py]"]
  node_time_conversion["Time conversion<br/>[read.py]"]
  node_timeseries_writer["Timeseries CSV<br/>[write.py]"]
  node_result_json["JSON results<br/>[__init__.py]"]
  node_result_writers["Download writers<br/>[write.py]"]
end

subgraph group_state["Upload state"]
  node_upload_store[("Upload files")]
  node_upload_metadata[("Upload metadata<br/>[__init__.py]")]
end

node_user(("Browser user"))

node_user -->|"selects file"| node_upload_ui
node_upload_ui -.->|"submits upload"| node_web_app
node_user -->|"requests pages"| node_web_app
node_web_app -->|"saves raw file"| node_upload_store
node_web_app -->|"records upload"| node_upload_metadata
node_web_app -->|"starts analysis"| node_analysis_orchestrator
node_analysis_orchestrator -->|"parses file"| node_input_parsers
node_analysis_orchestrator -->|"converts times"| node_time_conversion
node_analysis_orchestrator -->|"writes series"| node_timeseries_writer
node_analysis_orchestrator -->|"evaluates series"| node_burst_model
node_analysis_orchestrator -->|"writes JSON"| node_result_json
node_analysis_orchestrator -->|"writes exports"| node_result_writers
node_web_app -->|"checks status"| node_upload_metadata
node_web_app -->|"serves stored files"| node_upload_store
node_visualization -->|"polls endpoints"| node_web_app
node_visualization -.->|"reads burst data"| node_result_json
node_visualization -.->|"plots time series"| node_timeseries_writer
node_user -.->|"opens guide"| node_guide_page

click node_upload_ui "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/static/upload.js"
click node_web_app "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/app.py"
click node_visualization "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/static/visualise.js"
click node_upload_store "https://github.com/stac-iitmandi/xray-burst-detection/tree/main/uploads"
click node_upload_metadata "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py"
click node_analysis_orchestrator "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py"
click node_input_parsers "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/read.py"
click node_time_conversion "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/read.py"
click node_timeseries_writer "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/write.py"
click node_burst_model "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/model.py"
click node_result_json "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py"
click node_result_writers "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/write.py"
click node_guide_page "https://github.com/stac-iitmandi/xray-burst-detection/blob/main/templates/guide.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_upload_ui,node_web_app,node_visualization,node_guide_page,node_user toneBlue
class node_analysis_orchestrator,node_burst_model toneAmber
class node_input_parsers,node_time_conversion,node_timeseries_writer,node_result_json,node_result_writers toneMint
class node_upload_store,node_upload_metadata toneRose
```

## Components

### Web interface

- [File upload UI](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/static/upload.js): `static/upload.js`
- [Flask routes](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/app.py): `app.py`
- [Burst visualization](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/static/visualise.js): `static/visualise.js`
- [User guide page](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/templates/guide.html): `templates/guide.html`

### Analysis pipeline

- [Analysis orchestration](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py): `fileparsers/__init__.py`
- [Burst detection](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/model.py): `model.py`

### File formats

- [Input parsers](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/read.py): `fileparsers/read.py`
- [Time conversion](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/read.py): `fileparsers/read.py`
- [Timeseries CSV](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/write.py): `fileparsers/write.py`
- [JSON results](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py): `fileparsers/__init__.py`
- [Download writers](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/write.py): `fileparsers/write.py`

### Upload state

- [Upload files](https://github.com/stac-iitmandi/xray-burst-detection/tree/main/uploads): `uploads`
- [Upload metadata](https://github.com/stac-iitmandi/xray-burst-detection/blob/main/fileparsers/__init__.py): `fileparsers/__init__.py`

### Other components

- **Browser user**

## Connections

- Browser user → File upload UI: selects file (evidence: `static/upload.js`)
- File upload UI → Flask routes: submits upload
- Browser user → Flask routes: requests pages (evidence: `app.py`)
- Flask routes → Upload files: saves raw file (evidence: `app.py`)
- Flask routes → Upload metadata: records upload (evidence: `app.py`)
- Flask routes → Analysis orchestration: starts analysis (evidence: `app.py`)
- Analysis orchestration → Input parsers: parses file (evidence: `fileparsers/__init__.py`)
- Analysis orchestration → Time conversion: converts times (evidence: `fileparsers/__init__.py`)
- Analysis orchestration → Timeseries CSV: writes series (evidence: `fileparsers/__init__.py`)
- Analysis orchestration → Burst detection: evaluates series (evidence: `fileparsers/__init__.py`)
- Analysis orchestration → JSON results: writes JSON (evidence: `fileparsers/__init__.py`)
- Analysis orchestration → Download writers: writes exports (evidence: `fileparsers/__init__.py`)
- Flask routes → Upload metadata: checks status (evidence: `app.py`)
- Flask routes → Upload files: serves stored files (evidence: `app.py`)
- Burst visualization → Flask routes: polls endpoints (evidence: `static/visualise.js`)
- Burst visualization → JSON results: reads burst data
- Burst visualization → Timeseries CSV: plots time series
- Browser user → User guide page: opens guide
