# alb-310/geogramint architecture

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

- Interactive diagram: https://gitdiagram.com/alb-310/geogramint
- Repository: https://github.com/alb-310/geogramint

## Overview

##### Project Type and Purpose
- Geogramint is a standalone OSINT geolocation tool for Telegram, shipped as both a GUI desktop application (built on Kivy) and a CLI utility.
- It queries Telegram’s “People Nearby” API, processes the returned user/group data, visualizes it on a map or prints it to the console, and caches results locally.

##### Top-Level Architecture and Components
A. User Interfaces
1. GUI Layer
– geogramint.py (entry point)
– geogramint.kv + mapfiles/… (.kv and .py files under mapfiles)
– kivy_garden/mapview widget for map display
2. CLI Layer
– CLI/geogramint_cli.py (main CLI dispatcher)
– CLI/*_cli.py modules for commands: settings, resources, surveillance, TelegramAPIRequests_CLI
B. API Layer
– api/TelegramAPIRequests.py (core Telethon-based requests module)
– CLI/TelegramAPIRequests_CLI.py (wrapper for CLI mode)
C. Business Logic / Domain Objects
– utils/Group.py, utils/User.py (data models)
– utils/osintracker_export.py (export logic)
– utils/ressources.py, utils/resultDisplay.py (post-processing, formatting)
– utils/settings.py (in-memory config management)
D. Configuration and Data Storage
– appfiles/config.ini (persistent user settings)
– Geogramint/cache_telegram/ (JSON, CSV result files + profile pictures)
E. External Service
– Telegram API (“People Nearby” endpoint via Telethon)

##### Relationships & Data Flow
- UI (GUI or CLI) reads/writes configuration → utils/settings → config.ini
- UI issues “start search” command → business logic layer
- Business logic invokes API layer → Telegram API → raw data (JSON)
- API layer returns JSON → utils classes (User, Group) → caching module → writes to cache_telegram
- Business logic forwards processed data to resultDisplay (CLI) or to MapView (GUI)
- CLI prints tabular/JSON summary or invokes osintracker_export to produce CSV/HTML

##### Key Architectural Patterns & Principles
- Separation of Concerns: clear UI / API / domain / persistence layers
- MVC-style in GUI: .py files handle logic, .kv files handle view definitions
- Modular command structure in CLI: one file per command submodule
- Config-driven behavior: all credentials and preferences live in config.ini

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer (Blue)
    subgraph "User Interfaces"
        direction TB
        subgraph GUI
            direction TB
            GEOPY["geogramint.py"]:::ui
            KVL["geogramint.kv"]:::ui
            subgraph Mapfiles
                direction TB
                MAPPY["mapfiles/map.py"]:::ui
                MAPKV["mapfiles/map.kv"]:::ui
                MC["mapfiles/markercenter.py"]:::ui
                MCKV["mapfiles/markercenter.kv"]:::ui
            end
            MGV["kivy_garden/mapview"]:::ui
        end
        subgraph CLI
            direction TB
            CLIDIS["CLI/geogramint_cli.py"]:::ui
            CLIAPI["CLI/TelegramAPIRequests_CLI.py"]:::ui
            CLIRSC["CLI/ressources_cli.py"]:::ui
            CLISTS["CLI/settings_cli.py"]:::ui
            CLISUR["CLI/surveillance_cli.py"]:::ui
        end
    end

    %% API Layer (Green)
    COREAPI["api/TelegramAPIRequests.py"]:::api

    %% Business Logic & Domain Models (Green)
    subgraph "Business Logic & Domain Models"
        direction TB
        GRP["utils/Group.py"]:::logic
        USR["utils/User.py"]:::logic
        EXPORT["utils/osintracker_export.py"]:::logic
        RRES["utils/ressources.py"]:::logic
        RDISP["utils/resultDisplay.py"]:::logic
        SSET["utils/settings.py"]:::logic
    end

    %% Data Storage (Yellow)
    subgraph "Data Storage"
        direction TB
        CONFIG["appfiles/config.ini"]:::storage
        CACHE["Geogramint/cache_telegram/"]:::storage
    end

    %% External Service (Gray)
    TELE["Telegram API (People Nearby)"]:::external

    %% Data Flows
    GEOPY -->|"read config"| SSET
    CLIDIS -->|"read config"| SSET
    SSET -->|"write config"| CONFIG

    GEOPY -->|"start search"| COREAPI
    CLIDIS -->|"start search"| COREAPI

    COREAPI -->|"fetch nearby"| TELE
    TELE -->|"raw JSON"| COREAPI

    COREAPI -->|"process JSON"| GRP
    COREAPI -->|"process JSON"| USR

    GRP -->|"cache results"| CACHE
    USR -->|"cache results"| CACHE

    GRP -->|"data objects"| RDISP
    USR -->|"data objects"| RDISP

    RDISP -->|"print output"| CLIDIS
    RRES -->|"post-process"| CLIRSC
    EXPORT -->|"export format"| CLIRSC

    GRP -->|"data objects"| GEOPY
    USR -->|"data objects"| GEOPY

    GEOPY -->|"render map"| MGV
    MGV -->|"place markers"| MAPPY
    MAPPY -->|"define marker UI"| MC
    MC -->|"layout KV"| MCKV

    %% Click Events
    click GEOPY "https://github.com/alb-310/geogramint/blob/master/geogramint.py"
    click KVL "https://github.com/alb-310/geogramint/blob/master/geogramint.kv"
    click MAPPY "https://github.com/alb-310/geogramint/blob/master/mapfiles/map.py"
    click MAPKV "https://github.com/alb-310/geogramint/blob/master/mapfiles/map.kv"
    click MC "https://github.com/alb-310/geogramint/blob/master/mapfiles/markercenter.py"
    click MCKV "https://github.com/alb-310/geogramint/blob/master/mapfiles/markercenter.kv"
    click MGV "https://github.com/alb-310/geogramint/tree/master/kivy_garden/mapview"
    click CLIDIS "https://github.com/alb-310/geogramint/blob/master/CLI/geogramint_cli.py"
    click CLIAPI "https://github.com/alb-310/geogramint/blob/master/CLI/TelegramAPIRequests_CLI.py"
    click CLIRSC "https://github.com/alb-310/geogramint/blob/master/CLI/ressources_cli.py"
    click CLISTS "https://github.com/alb-310/geogramint/blob/master/CLI/settings_cli.py"
    click CLISUR "https://github.com/alb-310/geogramint/blob/master/CLI/surveillance_cli.py"
    click COREAPI "https://github.com/alb-310/geogramint/blob/master/api/TelegramAPIRequests.py"
    click GRP "https://github.com/alb-310/geogramint/blob/master/utils/Group.py"
    click USR "https://github.com/alb-310/geogramint/blob/master/utils/User.py"
    click EXPORT "https://github.com/alb-310/geogramint/blob/master/utils/osintracker_export.py"
    click RRES "https://github.com/alb-310/geogramint/blob/master/utils/ressources.py"
    click RDISP "https://github.com/alb-310/geogramint/blob/master/utils/resultDisplay.py"
    click SSET "https://github.com/alb-310/geogramint/blob/master/utils/settings.py"
    click CONFIG "https://github.com/alb-310/geogramint/blob/master/appfiles/config.ini"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#005FAD,color:#000
    classDef api fill:#DFFFE0,stroke:#2E8B57,color:#000
    classDef logic fill:#E0FFD8,stroke:#228B22,color:#000
    classDef storage fill:#FFF3B0,stroke:#DAA520,color:#000
    classDef external fill:#EEEEEE,stroke:#666,color:#000
```
