# cdzchen/gnss-llm architecture

> Architecture diagram of the GitHub repository cdzchen/gnss-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cdzchen/gnss-llm
- Repository: https://github.com/cdzchen/gnss-llm

## Overview

This repository is a modular GNSS spoofing and jamming monitor. Its principal workflow ingests GNSS feature data, builds multi-source features and a context state, lets an agent choose and invoke detectors, fuses their results, and manages event-level alerts; an optional LLM summarizes structured event logs for operators. Training, evaluation, and model deployment are meaningful supporting capabilities. The README documents the overall flow; sampled code confirms details of parsing, context encoding, policy selection, fusion, event management, and temporal detection, but not every runtime connection.

Main entry points: [`src/agent/executor.py`](https://github.com/cdzchen/gnss-llm/blob/main/src/agent/executor.py) (Agent executor), [`src/data/parser.py`](https://github.com/cdzchen/gnss-llm/blob/main/src/data/parser.py) (Data parser), [`src/event/event_manager.py`](https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_manager.py) (Event manager), [`src/agent/tool_registry.py`](https://github.com/cdzchen/gnss-llm/blob/main/src/agent/tool_registry.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and features"]
  node_parser["Data parser<br/>[parser.py]"]
  node_quality["Data quality<br/>[quality.py]"]
  node_features["Feature extraction"]
end

subgraph group_decision["Context and orchestration"]
  node_context["Context encoder<br/>[context_encoder.py]"]
  node_executor["Agent executor<br/>[executor.py]"]
  node_policy["Policy and planner<br/>[policy.py]"]
  node_registry["Tool registry<br/>[tool_registry.py]"]
end

subgraph group_detect["Detection and fusion"]
  node_detectors["Detector library"]
  node_temporal["Deep temporal detector<br/>[deep_temporal.py]"]
  node_fusion["Result fusion<br/>[result_fusion.py]"]
end

subgraph group_events["Events and reporting"]
  node_manager["Event manager<br/>[event_manager.py]"]
  node_record["Event records<br/>[event_record.py]"]
  node_logger["Event logger<br/>[event_logger.py]"]
  node_llm["LLM summaries<br/>[summarizer.py]"]
  node_report["Reports<br/>[report.py]"]
end

subgraph group_lifecycle["Model lifecycle"]
  node_trainer["Model training"]
  node_dataset["Windowed datasets<br/>[dataset.py]"]
  node_evaluation["Evaluation"]
  node_deployment["Model deployment"]
end

node_source(("GNSS data"))
node_operator(("Monitoring operator"))
node_llm_service(("LLM service"))

node_source -->|"provides data"| node_parser
node_parser -->|"checks quality"| node_quality
node_parser -->|"supplies records"| node_features
node_features -->|"provides features"| node_context
node_context -->|"provides context"| node_executor
node_executor -->|"requests plan"| node_policy
node_executor -->|"dispatches tools"| node_registry
node_registry -->|"invokes detectors"| node_detectors
node_registry -->|"invokes temporal model"| node_temporal
node_executor -->|"fuses results"| node_fusion
node_executor -->|"updates events"| node_manager
node_manager -->|"updates record"| node_record
node_manager -->|"logs events"| node_logger
node_logger -->|"supplies event logs"| node_llm
node_llm -.->|"requests summary"| node_llm_service
node_llm -->|"creates report"| node_report
node_report -->|"presents summary"| node_operator
node_manager -->|"raises alerts"| node_operator
node_parser -->|"supplies records"| node_dataset
node_dataset -->|"builds windows"| node_trainer
node_trainer -->|"trains model"| node_temporal
node_temporal -->|"exports model"| node_deployment
node_trainer -->|"evaluates experiments"| node_evaluation

click node_parser "https://github.com/cdzchen/gnss-llm/blob/main/src/data/parser.py"
click node_quality "https://github.com/cdzchen/gnss-llm/blob/main/src/data/quality.py"
click node_features "https://github.com/cdzchen/gnss-llm/tree/main/src/features"
click node_context "https://github.com/cdzchen/gnss-llm/blob/main/src/context/context_encoder.py"
click node_executor "https://github.com/cdzchen/gnss-llm/blob/main/src/agent/executor.py"
click node_policy "https://github.com/cdzchen/gnss-llm/blob/main/src/agent/policy.py"
click node_registry "https://github.com/cdzchen/gnss-llm/blob/main/src/agent/tool_registry.py"
click node_detectors "https://github.com/cdzchen/gnss-llm/tree/main/src/detectors"
click node_temporal "https://github.com/cdzchen/gnss-llm/blob/main/src/detectors/deep_temporal.py"
click node_fusion "https://github.com/cdzchen/gnss-llm/blob/main/src/fusion/result_fusion.py"
click node_manager "https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_manager.py"
click node_record "https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_record.py"
click node_logger "https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_logger.py"
click node_llm "https://github.com/cdzchen/gnss-llm/blob/main/src/llm/summarizer.py"
click node_report "https://github.com/cdzchen/gnss-llm/blob/main/src/llm/report.py"
click node_trainer "https://github.com/cdzchen/gnss-llm/tree/main/src/train"
click node_dataset "https://github.com/cdzchen/gnss-llm/blob/main/src/train/dataset.py"
click node_evaluation "https://github.com/cdzchen/gnss-llm/tree/main/src/eval"
click node_deployment "https://github.com/cdzchen/gnss-llm/tree/main/src/deploy"

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_parser,node_quality,node_features toneBlue
class node_context,node_executor,node_policy,node_registry toneAmber
class node_detectors,node_temporal,node_fusion toneMint
class node_manager,node_record,node_logger,node_llm,node_report toneRose
class node_trainer,node_dataset,node_evaluation,node_deployment,node_source,node_operator,node_llm_service toneIndigo
```

## Components

### Data and features

- [Data parser](https://github.com/cdzchen/gnss-llm/blob/main/src/data/parser.py): `src/data/parser.py`
- [Data quality](https://github.com/cdzchen/gnss-llm/blob/main/src/data/quality.py): `src/data/quality.py`
- [Feature extraction](https://github.com/cdzchen/gnss-llm/tree/main/src/features): `src/features`

### Context and orchestration

- [Context encoder](https://github.com/cdzchen/gnss-llm/blob/main/src/context/context_encoder.py): `src/context/context_encoder.py`
- [Agent executor](https://github.com/cdzchen/gnss-llm/blob/main/src/agent/executor.py): `src/agent/executor.py`
- [Policy and planner](https://github.com/cdzchen/gnss-llm/blob/main/src/agent/policy.py): `src/agent/policy.py`
- [Tool registry](https://github.com/cdzchen/gnss-llm/blob/main/src/agent/tool_registry.py): `src/agent/tool_registry.py`

### Detection and fusion

- [Detector library](https://github.com/cdzchen/gnss-llm/tree/main/src/detectors): `src/detectors`
- [Deep temporal detector](https://github.com/cdzchen/gnss-llm/blob/main/src/detectors/deep_temporal.py): `src/detectors/deep_temporal.py`
- [Result fusion](https://github.com/cdzchen/gnss-llm/blob/main/src/fusion/result_fusion.py): `src/fusion/result_fusion.py`

### Events and reporting

- [Event manager](https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_manager.py): `src/event/event_manager.py`
- [Event records](https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_record.py): `src/event/event_record.py`
- [Event logger](https://github.com/cdzchen/gnss-llm/blob/main/src/event/event_logger.py): `src/event/event_logger.py`
- [LLM summaries](https://github.com/cdzchen/gnss-llm/blob/main/src/llm/summarizer.py): `src/llm/summarizer.py`
- [Reports](https://github.com/cdzchen/gnss-llm/blob/main/src/llm/report.py): `src/llm/report.py`

### Model lifecycle

- [Model training](https://github.com/cdzchen/gnss-llm/tree/main/src/train): `src/train`
- [Windowed datasets](https://github.com/cdzchen/gnss-llm/blob/main/src/train/dataset.py): `src/train/dataset.py`
- [Evaluation](https://github.com/cdzchen/gnss-llm/tree/main/src/eval): `src/eval`
- [Model deployment](https://github.com/cdzchen/gnss-llm/tree/main/src/deploy): `src/deploy`

### Other components

- **GNSS data**
- **Monitoring operator**
- **LLM service**

## Connections

- GNSS data → Data parser: provides data
- Data parser → Data quality: checks quality
- Data parser → Feature extraction: supplies records
- Feature extraction → Context encoder: provides features
- Context encoder → Agent executor: provides context
- Agent executor → Policy and planner: requests plan
- Agent executor → Tool registry: dispatches tools
- Tool registry → Detector library: invokes detectors
- Tool registry → Deep temporal detector: invokes temporal model
- Agent executor → Result fusion: fuses results
- Agent executor → Event manager: updates events
- Event manager → Event records: updates record
- Event manager → Event logger: logs events
- Event logger → LLM summaries: supplies event logs
- LLM summaries → LLM service: requests summary
- LLM summaries → Reports: creates report
- Reports → Monitoring operator: presents summary
- Event manager → Monitoring operator: raises alerts
- Data parser → Windowed datasets: supplies records
- Windowed datasets → Model training: builds windows
- Model training → Deep temporal detector: trains model
- Deep temporal detector → Model deployment: exports model
- Model training → Evaluation: evaluates experiments