# datalux/osintgram architecture

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

- Interactive diagram: https://gitdiagram.com/datalux/osintgram
- Repository: https://github.com/datalux/osintgram

## Overview

Osintgram is a localhost web application for investigating public Instagram data and producing an answer with inspectable results. A user chooses commands directly or asks a question for a local model to select tools; the app runs those lookups through a service layer and a configured Instagram backend, then presents results and optional analysis or exports. The README also describes cost controls, caching, history, dossiers, snapshots, and sharing features. Edges below follow explicit README statements and source-index references; unsampled subsystems are included where documented, with uncertain wiring omitted.

Main entry points: [`src/web/app.py`](https://github.com/datalux/osintgram/blob/development/src/web/app.py) (Web application), [`src/osint_service.py`](https://github.com/datalux/osintgram/blob/development/src/osint_service.py) (OSINT service), [`src/web/tools.py`](https://github.com/datalux/osintgram/blob/development/src/web/tools.py) (Lookup tools), [`src/web/llm_client.py`](https://github.com/datalux/osintgram/blob/development/src/web/llm_client.py) (AI mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web workflow"]
  node_web["Web application<br/>[app.py]"]
  node_manual["Base mode<br/>[app.py]"]
  node_ai["AI mode<br/>[llm_client.py]"]
  node_tools["Lookup tools<br/>[tools.py]"]
end

subgraph group_investigation["OSINT analysis"]
  node_service["OSINT service<br/>[osint_service.py]"]
  node_audience["Audience audit<br/>[bot_detector.py]"]
  node_cross["Cross-platform scan<br/>[cross_platform.py]"]
  node_websearch["Public web search<br/>[web_search.py]"]
end

subgraph group_data["Instagram access"]
  node_instagram["Instagram backend"]
  node_hiker["HikerAPI"]
  node_instagrapi["instagrapi"]
end

subgraph group_support["Results and state"]
  node_cost["Cost controls<br/>[cost.py]"]
  node_cache[("Request cache<br/>[request_cache.py]")]
  node_history[("Search history<br/>[history.py]")]
  node_dossier["HTML dossier<br/>[dossier.py]"]
  node_download["Media download<br/>[download.py]"]
  node_graph["Graph export<br/>[graph_export.py]"]
  node_snapshot[("Snapshot tracking")]
  node_webhook["Webhook dispatch"]
end

node_user(("Local user"))
node_localmodel["Local model server"]
node_webhookservice["Webhook destinations"]

node_user -->|"submits query"| node_web
node_web -->|"offers mode"| node_manual
node_web -->|"offers mode"| node_ai
node_ai -->|"requests tool calls"| node_localmodel
node_web -->|"builds tools"| node_tools
node_ai -->|"selects tools"| node_tools
node_manual -->|"runs selections"| node_tools
node_tools -->|"calls lookups"| node_service
node_service -->|"calls backend"| node_instagram
node_instagram -->|"adapts client"| node_instagrapi
node_service -->|"audits followers"| node_audience
node_service -->|"scans usernames"| node_cross
node_tools -->|"searches public web"| node_websearch
node_service -.->|"fetches Instagram data"| node_hiker
node_web -->|"estimates cost"| node_cost
node_web -->|"uses cache"| node_cache
node_web -->|"uses history"| node_history
node_web -->|"creates report"| node_dossier
node_web -->|"serves downloads"| node_download
node_web -->|"exports graph"| node_graph
node_web -->|"tracks snapshots"| node_snapshot
node_web -.->|"dispatches changes"| node_webhook
node_webhook -.->|"sends notifications"| node_webhookservice

click node_web "https://github.com/datalux/osintgram/blob/development/src/web/app.py"
click node_manual "https://github.com/datalux/osintgram/blob/development/src/web/app.py"
click node_ai "https://github.com/datalux/osintgram/blob/development/src/web/llm_client.py"
click node_tools "https://github.com/datalux/osintgram/blob/development/src/web/tools.py"
click node_service "https://github.com/datalux/osintgram/blob/development/src/osint_service.py"
click node_instagram "https://github.com/datalux/osintgram/blob/development/src/instagrapi_backend.py"
click node_audience "https://github.com/datalux/osintgram/blob/development/src/web/bot_detector.py"
click node_cross "https://github.com/datalux/osintgram/blob/development/src/web/cross_platform.py"
click node_websearch "https://github.com/datalux/osintgram/blob/development/src/web/web_search.py"
click node_cost "https://github.com/datalux/osintgram/blob/development/src/web/cost.py"
click node_cache "https://github.com/datalux/osintgram/blob/development/src/web/request_cache.py"
click node_history "https://github.com/datalux/osintgram/blob/development/src/web/history.py"
click node_dossier "https://github.com/datalux/osintgram/blob/development/src/web/dossier.py"
click node_download "https://github.com/datalux/osintgram/blob/development/src/web/download.py"
click node_graph "https://github.com/datalux/osintgram/blob/development/src/web/graph_export.py"
click node_snapshot "https://github.com/datalux/osintgram/blob/development/src/snapshot_tracker.py"
click node_webhook "https://github.com/datalux/osintgram/blob/development/src/webhook_dispatcher.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_web,node_manual,node_ai,node_tools,node_user toneBlue
class node_service,node_audience,node_cross,node_websearch toneAmber
class node_instagram,node_hiker,node_instagrapi,node_localmodel,node_webhookservice toneMint
class node_cost,node_cache,node_history,node_dossier,node_download,node_graph,node_snapshot,node_webhook toneRose
```

## Components

### Web workflow

- [Web application](https://github.com/datalux/osintgram/blob/development/src/web/app.py): `src/web/app.py`
- [Base mode](https://github.com/datalux/osintgram/blob/development/src/web/app.py): `src/web/app.py`
- [AI mode](https://github.com/datalux/osintgram/blob/development/src/web/llm_client.py): `src/web/llm_client.py`
- [Lookup tools](https://github.com/datalux/osintgram/blob/development/src/web/tools.py): `src/web/tools.py`

### OSINT analysis

- [OSINT service](https://github.com/datalux/osintgram/blob/development/src/osint_service.py): `src/osint_service.py`
- [Audience audit](https://github.com/datalux/osintgram/blob/development/src/web/bot_detector.py): `src/web/bot_detector.py`
- [Cross-platform scan](https://github.com/datalux/osintgram/blob/development/src/web/cross_platform.py): `src/web/cross_platform.py`
- [Public web search](https://github.com/datalux/osintgram/blob/development/src/web/web_search.py): `src/web/web_search.py`

### Instagram access

- [Instagram backend](https://github.com/datalux/osintgram/blob/development/src/instagrapi_backend.py): `src/instagrapi_backend.py`
- **HikerAPI**
- **instagrapi**

### Results and state

- [Cost controls](https://github.com/datalux/osintgram/blob/development/src/web/cost.py): `src/web/cost.py`
- [Request cache](https://github.com/datalux/osintgram/blob/development/src/web/request_cache.py): `src/web/request_cache.py`
- [Search history](https://github.com/datalux/osintgram/blob/development/src/web/history.py): `src/web/history.py`
- [HTML dossier](https://github.com/datalux/osintgram/blob/development/src/web/dossier.py): `src/web/dossier.py`
- [Media download](https://github.com/datalux/osintgram/blob/development/src/web/download.py): `src/web/download.py`
- [Graph export](https://github.com/datalux/osintgram/blob/development/src/web/graph_export.py): `src/web/graph_export.py`
- [Snapshot tracking](https://github.com/datalux/osintgram/blob/development/src/snapshot_tracker.py): `src/snapshot_tracker.py`
- [Webhook dispatch](https://github.com/datalux/osintgram/blob/development/src/webhook_dispatcher.py): `src/webhook_dispatcher.py`

### Other components

- **Local user**
- **Local model server**
- **Webhook destinations**

## Connections

- Local user → Web application: submits query (evidence: `README.md`)
- Web application → Base mode: offers mode (evidence: `README.md`)
- Web application → AI mode: offers mode (evidence: `README.md`)
- AI mode → Local model server: requests tool calls (evidence: `README.md`)
- Web application → Lookup tools: builds tools (evidence: `src/web/app.py`)
- AI mode → Lookup tools: selects tools (evidence: `README.md`)
- Base mode → Lookup tools: runs selections (evidence: `README.md`)
- Lookup tools → OSINT service: calls lookups (evidence: `src/web/tools.py`)
- OSINT service → Instagram backend: calls backend (evidence: `src/osint_service.py`)
- Instagram backend → instagrapi: adapts client (evidence: `src/instagrapi_backend.py`)
- OSINT service → Audience audit: audits followers (evidence: `src/osint_service.py`)
- OSINT service → Cross-platform scan: scans usernames (evidence: `src/osint_service.py`)
- Lookup tools → Public web search: searches public web (evidence: `src/web/tools.py`)
- OSINT service → HikerAPI: fetches Instagram data
- Web application → Cost controls: estimates cost (evidence: `src/web/app.py`)
- Web application → Request cache: uses cache (evidence: `src/web/app.py`)
- Web application → Search history: uses history (evidence: `src/web/app.py`)
- Web application → HTML dossier: creates report (evidence: `src/web/app.py`)
- Web application → Media download: serves downloads (evidence: `src/web/app.py`)
- Web application → Graph export: exports graph (evidence: `src/web/app.py`)
- Web application → Snapshot tracking: tracks snapshots (evidence: `src/web/app.py`)
- Web application → Webhook dispatch: dispatches changes (evidence: `src/web/app.py`)
- Webhook dispatch → Webhook destinations: sends notifications
