# shredzwho/ig-detective architecture

> Architecture diagram of the GitHub repository shredzwho/ig-detective, 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/shredzwho/ig-detective
- Repository: https://github.com/shredzwho/ig-detective

## Overview

IG-Detective is an interactive Instagram OSINT application. An investigator authenticates or loads a saved session, selects a target in the shell, and invokes reconnaissance, analysis, monitoring, or export commands. Reconnaissance fetches and structures profile and post data; analysis covers network, temporal, linguistic, and engagement patterns, while location and recovery investigations provide distinct OSINT stages. Export assembles profile, follower/following, and media data into an archive; surveillance compares snapshots in SQLite. README documents additional capabilities whose implementation wiring is not fully visible in the sampled source, so those links are not inferred.

Main entry points: [`src/cli/shell.py`](https://github.com/shredzwho/ig-detective/blob/main/src/cli/shell.py) (Interactive Shell), [`src/modules/recon.py`](https://github.com/shredzwho/ig-detective/blob/main/src/modules/recon.py) (Recon Engine), [`src/api/client.py`](https://github.com/shredzwho/ig-detective/blob/main/src/api/client.py) (Instagram Client), [`src/modules/exporter.py`](https://github.com/shredzwho/ig-detective/blob/main/src/modules/exporter.py) (Data Exporter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Investigator Interface"]
  node_main["Application Entry<br/>[main.py]"]
  node_shell["Interactive Shell<br/>[shell.py]"]
  node_formatters["Rich Presentation<br/>[formatters.py]"]
end

subgraph group_access["Session and Access"]
  node_session["Session Manager<br/>[auth.py]"]
  node_client["Instagram Client<br/>[client.py]"]
  node_endpoints["Endpoint Builder<br/>[endpoints.py]"]
end

subgraph group_intelligence["Recon and Analysis"]
  node_recon["Recon Engine<br/>[recon.py]"]
  node_cache[("TTL Cache<br/>[cache.py]")]
  node_evasion["Request Evasion<br/>[evasion.py]"]
  node_models["Domain Models<br/>[models.py]"]
  node_analytics["OSINT Analytics<br/>[analytics.py]"]
end

subgraph group_investigation["Investigation Management"]
  node_exporter["Data Exporter<br/>[exporter.py]"]
  node_surveillance["Surveillance Engine<br/>[surveillance.py]"]
  node_snapshots[("Snapshot Database<br/>[surveillance.py]")]
end

node_investigator(("Investigator"))
node_instagram(("Instagram"))
node_external_geo(("Geocoding Service"))

node_investigator -->|"launches"| node_main
node_main -->|"authenticates"| node_session
node_main -->|"starts"| node_shell
node_shell -->|"prompts"| node_investigator
node_shell -->|"renders"| node_formatters
node_shell -->|"requests recon"| node_recon
node_shell -->|"runs analysis"| node_analytics
node_shell -->|"requests export"| node_exporter
node_shell -->|"requests monitoring"| node_surveillance
node_session -->|"loads cookies"| node_client
node_client -->|"loads session"| node_session
node_client -->|"builds requests"| node_endpoints
node_client -->|"fetches data"| node_instagram
node_recon -->|"fetches profile and posts"| node_client
node_recon -->|"reads and writes"| node_cache
node_recon -->|"applies jitter"| node_evasion
node_recon -->|"creates records"| node_models
node_exporter -->|"fetches profile and posts"| node_recon
node_exporter -->|"fetches follower lists"| node_client
node_exporter -->|"downloads media"| node_instagram
node_surveillance -->|"reads and writes"| node_snapshots
node_shell -.->|"resolves addresses"| node_external_geo

click node_main "https://github.com/shredzwho/ig-detective/blob/main/main.py"
click node_shell "https://github.com/shredzwho/ig-detective/blob/main/src/cli/shell.py"
click node_formatters "https://github.com/shredzwho/ig-detective/blob/main/src/cli/formatters.py"
click node_session "https://github.com/shredzwho/ig-detective/blob/main/src/api/auth.py"
click node_client "https://github.com/shredzwho/ig-detective/blob/main/src/api/client.py"
click node_endpoints "https://github.com/shredzwho/ig-detective/blob/main/src/api/endpoints.py"
click node_recon "https://github.com/shredzwho/ig-detective/blob/main/src/modules/recon.py"
click node_cache "https://github.com/shredzwho/ig-detective/blob/main/src/core/cache.py"
click node_evasion "https://github.com/shredzwho/ig-detective/blob/main/src/modules/evasion.py"
click node_models "https://github.com/shredzwho/ig-detective/blob/main/src/core/models.py"
click node_analytics "https://github.com/shredzwho/ig-detective/blob/main/src/modules/analytics.py"
click node_exporter "https://github.com/shredzwho/ig-detective/blob/main/src/modules/exporter.py"
click node_surveillance "https://github.com/shredzwho/ig-detective/blob/main/src/modules/surveillance.py"
click node_snapshots "https://github.com/shredzwho/ig-detective/blob/main/src/modules/surveillance.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_main,node_shell,node_formatters toneBlue
class node_session,node_client,node_endpoints toneAmber
class node_recon,node_cache,node_evasion,node_models,node_analytics toneMint
class node_exporter,node_surveillance,node_snapshots toneRose
class node_investigator,node_instagram,node_external_geo toneIndigo
```

## Components

### Investigator Interface

- [Application Entry](https://github.com/shredzwho/ig-detective/blob/main/main.py): `main.py`
- [Interactive Shell](https://github.com/shredzwho/ig-detective/blob/main/src/cli/shell.py): `src/cli/shell.py`
- [Rich Presentation](https://github.com/shredzwho/ig-detective/blob/main/src/cli/formatters.py): `src/cli/formatters.py`

### Session and Access

- [Session Manager](https://github.com/shredzwho/ig-detective/blob/main/src/api/auth.py): `src/api/auth.py`
- [Instagram Client](https://github.com/shredzwho/ig-detective/blob/main/src/api/client.py): `src/api/client.py`
- [Endpoint Builder](https://github.com/shredzwho/ig-detective/blob/main/src/api/endpoints.py): `src/api/endpoints.py`

### Recon and Analysis

- [Recon Engine](https://github.com/shredzwho/ig-detective/blob/main/src/modules/recon.py): `src/modules/recon.py`
- [TTL Cache](https://github.com/shredzwho/ig-detective/blob/main/src/core/cache.py): `src/core/cache.py`
- [Request Evasion](https://github.com/shredzwho/ig-detective/blob/main/src/modules/evasion.py): `src/modules/evasion.py`
- [Domain Models](https://github.com/shredzwho/ig-detective/blob/main/src/core/models.py): `src/core/models.py`
- [OSINT Analytics](https://github.com/shredzwho/ig-detective/blob/main/src/modules/analytics.py): `src/modules/analytics.py`

### Investigation Management

- [Data Exporter](https://github.com/shredzwho/ig-detective/blob/main/src/modules/exporter.py): `src/modules/exporter.py`
- [Surveillance Engine](https://github.com/shredzwho/ig-detective/blob/main/src/modules/surveillance.py): `src/modules/surveillance.py`
- [Snapshot Database](https://github.com/shredzwho/ig-detective/blob/main/src/modules/surveillance.py): `src/modules/surveillance.py`

### Other components

- **Investigator**
- **Instagram**
- **Geocoding Service**

## Connections

- Investigator → Application Entry: launches
- Application Entry → Session Manager: authenticates
- Application Entry → Interactive Shell: starts
- Interactive Shell → Investigator: prompts
- Interactive Shell → Rich Presentation: renders
- Interactive Shell → Recon Engine: requests recon
- Interactive Shell → OSINT Analytics: runs analysis
- Interactive Shell → Data Exporter: requests export
- Interactive Shell → Surveillance Engine: requests monitoring
- Session Manager → Instagram Client: loads cookies
- Instagram Client → Session Manager: loads session
- Instagram Client → Endpoint Builder: builds requests
- Instagram Client → Instagram: fetches data
- Recon Engine → Instagram Client: fetches profile and posts
- Recon Engine → TTL Cache: reads and writes
- Recon Engine → Request Evasion: applies jitter
- Recon Engine → Domain Models: creates records
- Data Exporter → Recon Engine: fetches profile and posts
- Data Exporter → Instagram Client: fetches follower lists
- Data Exporter → Instagram: downloads media
- Surveillance Engine → Snapshot Database: reads and writes
- Interactive Shell → Geocoding Service: resolves addresses