# milancodess/tagspy architecture

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

- Interactive diagram: https://gitdiagram.com/milancodess/tagspy
- Repository: https://github.com/milancodess/tagspy

## Overview

##### Project type and purpose
- This is a small, open-source CLI tool (“tagspy”) written in Node.js.
- Purpose: Given a public Instagram Story URL plus a valid session cookie, it programmatically navigates to the story, extracts all user mentions (full name + username), and writes them as JSON.

##### File structure
- Top-level files only:
- index.js – main script
- mentions.json – output file
- package.json & package-lock.json – dependency and script metadata
- .gitignore, README.md
- No frontend or backend subfolders: it is a single‐process CLI app.
- Dependencies (in package.json) include puppeteer-extra + stealth plugin, dotenv for .env, etc.

##### Key insights from README
- Uses Puppeteer-Extra + stealth plugin for headless browser automation and bot‐avoidance.
- Requires IG_SESSION_ID in .env for session‐based authentication.
- Workflow: Launch Puppeteer → navigate to story URL → scrape mentions → write mentions.json.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        Env[".env"]:::config
        ConfigLoader["Configuration Loader (dotenv)"]:::config
    end

    subgraph "Core Logic"
        Script["Node.js Runtime / Main Script"]:::core
        Puppeteer["Puppeteer-Extra Controller + Stealth Plugin"]:::core
        Parser["HTML/DOM Parser"]:::core
    end

    External["Instagram Web"]:::external

    subgraph "Output"
        Writer["Output Writer"]:::data
        MentionsFile["mentions.json"]:::data
    end

    subgraph "Project Files"
        Pkg["package.json"]:::config
        PkgLock["package-lock.json"]:::data
        Readme["README.md"]:::config
        Gitignore[".gitignore"]:::config
    end

    Env -->|loads vars| ConfigLoader
    ConfigLoader -->|provides session ID| Script
    Script -->|launches| Puppeteer
    Puppeteer <-->|HTTP requests / responses| External
    Puppeteer -->|runs page.evaluate| Parser
    Parser -->|data objects| Writer
    Writer -->|writes file| MentionsFile

    classDef config fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcc99,stroke:#333,stroke-width:1px;
    classDef data fill:#d3d3d3,stroke:#333,stroke-width:1px;

    click ConfigLoader "https://github.com/milancodess/tagspy/blob/main/package.json"
    click Puppeteer "https://github.com/milancodess/tagspy/blob/main/package.json"
    click Script "https://github.com/milancodess/tagspy/blob/main/index.js"
    click Writer "https://github.com/milancodess/tagspy/blob/main/mentions.json"
    click Pkg "https://github.com/milancodess/tagspy/blob/main/package.json"
    click PkgLock "https://github.com/milancodess/tagspy/blob/main/package-lock.json"
    click Readme "https://github.com/milancodess/tagspy/blob/main/README.md"
    click Gitignore "https://github.com/milancodess/tagspy/blob/main/.gitignore"
```
