# yosefshoval/digital_hunter architecture

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

- Interactive diagram: https://gitdiagram.com/yosefshoval/digital_hunter
- Repository: https://github.com/yosefshoval/digital_hunter

## Overview

Digital Hunter consumes intel, attack, and damage events, validates them, updates target-related records, and routes malformed messages to a dead-letter topic. Its simulator generates ordinary and deliberately faulty events for Kafka. The graph shows the sampled consumer flow and documented logging integration; README provides no additional product detail, and simulator and deployment wiring beyond the sampled excerpts is not inferred.

Main entry points: [`consumer/main.py`](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/main.py) (Consumer workflow), [`consumer/mongo_connection.py`](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/mongo_connection.py) (MongoDB adapter), [`consumer/config.py`](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/config.py) (Consumer config), [`consumer/kafka_tracker.py`](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/kafka_tracker.py) (Kafka tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Event generation"]
  node_simulator["Event simulator<br/>[simulator.py]"]
end

subgraph group_ingestion["Kafka ingestion"]
  node_tracker["Kafka tracker<br/>[kafka_tracker.py]"]
end

subgraph group_processing["Event processing"]
  node_main["Consumer workflow<br/>[main.py]"]
  node_config["Consumer config<br/>[config.py]"]
  node_models["Message validation<br/>[models.py]"]
  node_distance["Distance calculation<br/>[haversine.py]"]
  node_deadletter["DLQ producer<br/>[producer.py]"]
end

subgraph group_storage["Persistence and observability"]
  node_mongodb["MongoDB adapter"]
  node_logger["Structured logger<br/>[logger.py]"]
end

node_kafka["Kafka broker"]
node_mongo[("MongoDB")]
node_elasticsearch[("Elasticsearch")]

node_simulator -->|"publishes events"| node_kafka
node_kafka -->|"supplies events"| node_tracker
node_tracker -->|"returns events"| node_main
node_main -->|"uses settings"| node_config
node_main -->|"validates events"| node_models
node_main -->|"calculates movement"| node_distance
node_main -->|"checks and updates"| node_mongodb
node_main -->|"routes invalid events"| node_deadletter
node_main -->|"logs events"| node_logger
node_tracker -->|"loads settings"| node_config
node_deadletter -->|"loads settings"| node_config
node_mongodb -->|"loads settings"| node_config
node_mongodb -->|"imports schemas"| node_models
node_mongodb -->|"reads and writes"| node_mongo
node_mongodb -->|"logs operations"| node_logger
node_logger -->|"indexes logs"| node_elasticsearch

click node_simulator "https://github.com/yosefshoval/digital_hunter/blob/main/messages_generator/simulator.py"
click node_tracker "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/kafka_tracker.py"
click node_main "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/main.py"
click node_config "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/config.py"
click node_models "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/models.py"
click node_distance "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/haversine.py"
click node_deadletter "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/producer.py"
click node_mongodb "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/mongo_connection.py"
click node_logger "https://github.com/yosefshoval/digital_hunter/blob/main/consumer/logger.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_simulator toneBlue
class node_tracker,node_mongo,node_elasticsearch toneAmber
class node_main,node_config,node_models,node_distance,node_deadletter toneMint
class node_mongodb,node_logger toneRose
class node_kafka toneIndigo
```

## Components

### Event generation

- [Event simulator](https://github.com/yosefshoval/digital_hunter/blob/main/messages_generator/simulator.py): `messages_generator/simulator.py`

### Kafka ingestion

- [Kafka tracker](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/kafka_tracker.py): `consumer/kafka_tracker.py`

### Event processing

- [Consumer workflow](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/main.py): `consumer/main.py`
- [Consumer config](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/config.py): `consumer/config.py`
- [Message validation](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/models.py): `consumer/models.py`
- [Distance calculation](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/haversine.py): `consumer/haversine.py`
- [DLQ producer](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/producer.py): `consumer/producer.py`

### Persistence and observability

- [MongoDB adapter](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/mongo_connection.py): `consumer/mongo_connection.py`
- [Structured logger](https://github.com/yosefshoval/digital_hunter/blob/main/consumer/logger.py): `consumer/logger.py`

### Other components

- **Kafka broker**
- **MongoDB**
- **Elasticsearch**

## Connections

- Event simulator → Kafka broker: publishes events (evidence: `messages_generator/simulator.py`)
- Kafka broker → Kafka tracker: supplies events (evidence: `consumer/kafka_tracker.py`)
- Kafka tracker → Consumer workflow: returns events (evidence: `consumer/main.py`)
- Consumer workflow → Consumer config: uses settings (evidence: `consumer/main.py`)
- Consumer workflow → Message validation: validates events (evidence: `consumer/main.py`)
- Consumer workflow → Distance calculation: calculates movement (evidence: `consumer/main.py`)
- Consumer workflow → MongoDB adapter: checks and updates (evidence: `consumer/main.py`)
- Consumer workflow → DLQ producer: routes invalid events (evidence: `consumer/main.py`)
- Consumer workflow → Structured logger: logs events (evidence: `consumer/main.py`)
- Kafka tracker → Consumer config: loads settings (evidence: `consumer/kafka_tracker.py`)
- DLQ producer → Consumer config: loads settings (evidence: `consumer/producer.py`)
- MongoDB adapter → Consumer config: loads settings (evidence: `consumer/mongo_connection.py`)
- MongoDB adapter → Message validation: imports schemas (evidence: `consumer/mongo_connection.py`)
- MongoDB adapter → MongoDB: reads and writes (evidence: `consumer/mongo_connection.py`)
- MongoDB adapter → Structured logger: logs operations (evidence: `consumer/mongo_connection.py`)
- Structured logger → Elasticsearch: indexes logs (evidence: `consumer/logger.py`)
