# radiah23/stork-tracking---sequential-data-analysis architecture

> Architecture diagram of the GitHub repository radiah23/stork-tracking---sequential-data-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/radiah23/stork-tracking---sequential-data-analysis
- Repository: https://github.com/radiah23/stork-tracking---sequential-data-analysis

## Overview

This repository tracks white-stork migration from raw GPS fixes through cleaning, sequencing, feature extraction, SQLite storage, SQL analysis, and mapping; it also offers an LLM question-answering path over the stored data. The README documents the pipeline and analytical capabilities. The visualization implementation is not present in the tree, so the map is represented only by the available map.html artifact; links involving it reflect documented behavior, not inspected code.

Main entry points: [`ask_data.py`](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/ask_data.py) (Question Workflow), [`extract.py`](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py) (Tracking Database), [`run_queries.py`](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/run_queries.py) (Query Runner), [`queries.sql`](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/queries.sql) (SQL Analyses)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracking["GPS Preparation"]
  node_extract["CSV Extraction<br/>[extract.py]"]
  node_clean["Quality Cleaning<br/>[extract.py]"]
  node_sequence["Sequence Ordering<br/>[extract.py]"]
  node_features["Movement Features<br/>[extract.py]"]
  node_tracking_db[("Tracking Database<br/>[extract.py]")]
end

subgraph group_analysis["Analysis and Mapping"]
  node_query_definitions["SQL Analyses<br/>[queries.sql]"]
  node_query_runner["Query Runner<br/>[run_queries.py]"]
  node_map["Migration Map<br/>[map.html]"]
end

subgraph group_asking["Natural Language Queries"]
  node_ask["Question Workflow<br/>[ask_data.py]"]
  node_sql_safety["SQL Safety<br/>[ask_data.py]"]
end

node_data_source["Movebank GPS CSV"]
node_user(("Data User"))
node_llm["Anthropic Claude"]

node_data_source -->|"provides CSV"| node_extract
node_extract -->|"loads rows"| node_clean
node_clean -->|"orders fixes"| node_sequence
node_sequence -->|"derives features"| node_features
node_features -->|"writes table"| node_tracking_db
node_query_runner -->|"loads SQL"| node_query_definitions
node_query_runner -->|"queries"| node_tracking_db
node_query_definitions -.->|"supports visualization"| node_map
node_user -->|"asks question"| node_ask
node_ask -->|"requests SQL"| node_llm
node_ask -->|"validates query"| node_sql_safety
node_sql_safety -->|"reads only"| node_tracking_db
node_ask -->|"requests explanation"| node_llm

click node_extract "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py"
click node_clean "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py"
click node_sequence "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py"
click node_features "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py"
click node_tracking_db "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py"
click node_query_definitions "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/queries.sql"
click node_query_runner "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/run_queries.py"
click node_map "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/map.html"
click node_ask "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/ask_data.py"
click node_sql_safety "https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/ask_data.py"

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_extract,node_clean,node_sequence,node_features,node_tracking_db,node_user toneBlue
class node_query_definitions,node_query_runner,node_map toneAmber
class node_ask,node_sql_safety toneMint
class node_data_source,node_llm toneIndigo
```

## Components

### GPS Preparation

- [CSV Extraction](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py): `extract.py`
- [Quality Cleaning](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py): `extract.py`
- [Sequence Ordering](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py): `extract.py`
- [Movement Features](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py): `extract.py`
- [Tracking Database](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/extract.py): `extract.py`

### Analysis and Mapping

- [SQL Analyses](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/queries.sql): `queries.sql`
- [Query Runner](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/run_queries.py): `run_queries.py`
- [Migration Map](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/map.html): `map.html`

### Natural Language Queries

- [Question Workflow](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/ask_data.py): `ask_data.py`
- [SQL Safety](https://github.com/radiah23/stork-tracking---sequential-data-analysis/blob/main/ask_data.py): `ask_data.py`

### Other components

- **Movebank GPS CSV**
- **Data User**
- **Anthropic Claude**

## Connections

- Movebank GPS CSV → CSV Extraction: provides CSV (evidence: `README.md`)
- CSV Extraction → Quality Cleaning: loads rows (evidence: `README.md`)
- Quality Cleaning → Sequence Ordering: orders fixes (evidence: `README.md`)
- Sequence Ordering → Movement Features: derives features (evidence: `README.md`)
- Movement Features → Tracking Database: writes table (evidence: `extract.py`)
- Query Runner → SQL Analyses: loads SQL (evidence: `run_queries.py`)
- Query Runner → Tracking Database: queries (evidence: `run_queries.py`)
- SQL Analyses → Migration Map: supports visualization (evidence: `README.md`)
- Data User → Question Workflow: asks question (evidence: `README.md`)
- Question Workflow → Anthropic Claude: requests SQL (evidence: `ask_data.py`)
- Question Workflow → SQL Safety: validates query (evidence: `ask_data.py`)
- SQL Safety → Tracking Database: reads only (evidence: `ask_data.py`)
- Question Workflow → Anthropic Claude: requests explanation (evidence: `ask_data.py`)
