# subzeroid/instagrapi architecture

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

- Interactive diagram: https://gitdiagram.com/subzeroid/instagrapi
- Repository: https://github.com/subzeroid/instagrapi

## Overview

##### Project type and purpose
- This is a Python client library (“instagrapi”) providing an unofficial wrapper for Instagram’s private Web & Mobile APIs.
- It offers core features (login, media upload/download, direct messaging, insights, challenge resolution, 2FA) via a modular mixin design.
- It includes documentation (MkDocs), examples, tests, Dockerized development & CI/CD workflows, and plugins for docs.

##### File structure
Top-level directories:
- instagrapi/ – the core library
- config.py, exceptions.py, extractors.py, image_util.py, utils.py, zones.py
- mixins/ – one module per IG feature (account, media, direct, story, etc.)
- types.py – data models for API responses
- story.py – StoryBuilder sub-system
- docs/ – MkDocs site source, usage-guide, best practices
- examples/ – standalone scripts demonstrating library usage
- tests.py – basic test suite
- util/ – MkDocs plugins (redirects, type-alias patch)
- docker/ + docker-compose.yml – dev/test environment
- .github/ – GitHub Actions workflows and custom actions (install deps, publish docs)
- setup.py, requirements*.txt – packaging & dependencies

##### README for additional insights
- Describes two API modes (Web vs Mobile) with auto-selection to avoid limits
- Highlights the “Challenge Resolver” subsystem (Email/SMS handlers, 2FA TOTP)
- Lists major resource types (User, Media, Comment, Story, Hashtag, Location, Direct)
- Shows sample code leveraging the Client() + mixins + types

##### Elements
- Developer → Client → HTTP Transport → Instagram Web/Mobile APIs
- HTTP errors → Challenge Resolver → Email/SMS gateways → back to Client
- Codebase + docs → MkDocs → GitHub Actions → Published docs
- Codebase → Docker/Test → GitHub Actions → PyPI
- Infrastructure (Docker, CI/CD, Docs) in another

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Application"
        DevApp["Developer App"]:::business
    end

    subgraph "instagrapi Client Library"
        subgraph "Core Initialization"
            Init["__init__.py"]:::business
            Config["config.py"]:::business
            Exceptions["exceptions.py"]:::business
        end
        subgraph "Utilities"
            Extractors["extractors.py"]:::business
            ImageUtil["image_util.py"]:::business
            Utils["utils.py"]:::business
            Zones["zones.py"]:::business
        end
        subgraph "Session & Transport"
            Session["Session Manager"]:::business
            Transport["HTTP Transport"]:::business
        end
        subgraph "Mixins"
            Account["account.py"]:::business
            Media["media.py"]:::business
            Direct["direct.py"]:::business
            StoryMix["story.py"]:::business
            Comment["comment.py"]:::business
            Insights["insights.py"]:::business
            Challenge["challenge.py"]:::business
            TOTPMixin["totp.py"]:::business
        end
        Types["types.py"]:::business
        StoryBuilder["story.py"]:::business
        ChallengeResolver["Challenge Resolver"]:::business
    end

    subgraph "External Services"
        WebAPI["Instagram Web API"]:::external
        MobileAPI["Instagram Mobile API"]:::external
        Proxy["Proxy Servers"]:::external
        Gateway["Email/SMS Gateway"]:::external
    end

    subgraph "Documentation Pipeline"
        MkConfig["mkdocs.yml"]:::infra
        DocsSrc["docs/"]:::infra
        Redirects["util/mkdocs-redirects/"]:::infra
        PatchAliases["util/mkdocstrings_patch_type_aliases/"]:::infra
        DocsAction["GitHub Actions (docs)"]:::infra
    end

    subgraph "CI/CD Pipeline"
        DockerCompose["docker-compose.yml"]:::infra
        DockerDev["docker/"]:::infra
        Workflows[".github/workflows/"]:::infra
        CustomActions[".github/actions/"]:::infra
        CIAction["GitHub Actions (CI)"]:::infra
        Packaging["setup.py & requirements"]:::infra
    end

    DevApp -->|"uses"| Session
    Session --> Transport
    Transport -->|"HTTP requests"| WebAPI
    Transport -->|"HTTP requests"| MobileAPI
    Transport -->|"via proxy"| Proxy
    Transport -->|"errors"| ChallengeResolver
    ChallengeResolver -->|"send challenge"| Gateway
    Gateway -->|"callback"| Session
    Session --> Types
    Session --> StoryBuilder
    StoryManagerCall(Session) --> Types
    Account --> Transport
    Media --> Transport
    Direct --> Transport
    StoryMix --> Transport
    Comment --> Transport
    Insights --> Transport
    Challenge --> Transport
    TOTPMixin --> Transport

    MkConfig & DocsSrc & Redirects & PatchAliases -->|"build site"| DocsAction
    DocsAction -->|"publish docs"| DocsAction

    DockerCompose & DockerDev & Workflows & CustomActions -->|"run CI"| CIAction
    CIAction -->|"publish package"| Packaging

    classDef business fill:#f96,stroke:#333,stroke-width:1px;
    classDef infra fill:#6cf,stroke:#333,stroke-width:1px;
    classDef external fill:#9f6,stroke:#333,stroke-width:1px;

    click DevApp "https://github.com/subzeroid/instagrapi/tree/master/examples/"
    click Init "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/__init__.py"
    click Config "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/config.py"
    click Exceptions "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/exceptions.py"
    click Extractors "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/extractors.py"
    click ImageUtil "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/image_util.py"
    click Utils "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/utils.py"
    click Zones "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/zones.py"
    click Types "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/types.py"
    click StoryBuilder "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/story.py"
    click Account "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/account.py"
    click Media "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/media.py"
    click Direct "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/direct.py"
    click StoryMix "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/story.py"
    click Comment "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/comment.py"
    click Insights "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/insights.py"
    click Challenge "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/challenge.py"
    click TOTPMixin "https://github.com/subzeroid/instagrapi/blob/master/instagrapi/mixins/totp.py"
    click MkConfig "https://github.com/subzeroid/instagrapi/blob/master/mkdocs.yml"
    click DocsSrc "https://github.com/subzeroid/instagrapi/tree/master/docs/"
    click Redirects "https://github.com/subzeroid/instagrapi/tree/master/util/mkdocs-redirects/"
    click PatchAliases "https://github.com/subzeroid/instagrapi/tree/master/util/mkdocstrings_patch_type_aliases/"
    click DockerCompose "https://github.com/subzeroid/instagrapi/blob/master/docker-compose.yml"
    click DockerDev "https://github.com/subzeroid/instagrapi/tree/master/docker/"
    click Workflows "https://github.com/subzeroid/instagrapi/tree/master/.github/workflows/"
    click CustomActions "https://github.com/subzeroid/instagrapi/tree/master/.github/actions/"
    click Packaging "https://github.com/subzeroid/instagrapi/blob/master/setup.py"
```
