# diezo/ensta architecture

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

- Interactive diagram: https://gitdiagram.com/diezo/ensta
- Repository: https://github.com/diezo/ensta

## Overview

##### Project Type & Purpose
- Type: Open-source Python SDK / API wrapper
- Purpose: Expose Instagram Mobile (and deprecated Web) endpoints through a high-level Python interface (Mobile, Guest, Web classes).
- Key use cases: authentication, profile fetch, follow/unfollow, media upload, direct messaging.

##### File Structure
- Top-level package “ensta/” holds all modules.
- Core modules:
– Authentication.py, Credentials.py, PasswordEncryption.py → handle login and credential security
– SessionManager.py, WebSession.py → manage HTTP sessions, cookies, proxies
– Mobile.py, Guest.py, Web.py, Direct.py, MediaResolver.py, Utils.py → implement API endpoints
- Subfolders:
– containers/ → typed response wrappers (e.g., Profile, Post)
– parser/ → JSON→container parsers
– structures/ → domain models for individual data items
– lib/ → shared utilities (exceptions, searcher)
- Tests and CI config confirm usage of the Python “requests” library and proxy support.

##### README for Insights
- Confirms two main client classes: Mobile (full features) and Guest (limited). Web is deprecated.
- Highlights support for proxies, multi-stage operations (e.g., upload_id generation → media upload).
- No database or persistent storage—state is kept in in-memory SessionManager.

##### Main Components & Interactions
a. User Application
– Your code imports ensta.Mobile / Guest / Web.
b. Client Layer
– Mobile/Guest/Web classes expose methods (profile, follow, upload, direct, etc.).
c. Auth & Session
– Credentials + PasswordEncryption → Authentication → SessionManager initializes an HTTP session (requests.Session), applies proxies, headers, cookies.
d. Transport & Endpoint Resolution
– MediaResolver constructs URLs and payloads for each endpoint. Utils assists with parameter formatting.
e. HTTP Transport
– SessionManager uses requests library to send HTTP(S) calls to Instagram servers (Mobile API endpoints or Web endpoints).
f. Response Handling
– Raw JSON responses flow into parser/ modules (e.g., ProfileParser), which emit container classes.
– containers/ wrap related structures (from structures/) into high-level objects returned to the user.
g. Error Handling & Utilities
– ensta.lib.Exceptions catches HTTP or parsing errors. ensta.lib.Searcher helps locate items in nested data.

##### Architectural Patterns & Principles
- Layered architecture:
1) Client interface
2) Auth & Session management
3) Transport & resolver
4) Parsing & data modeling
- Separation of concerns: Each folder/module group has a single responsibility.
- Dependency injection: SessionManager, Credentials injected into client classes.
- Extensibility: New endpoints added via MediaResolver + matching parser + container + structure.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    U["User Application"]

    %% Client API Layer
    subgraph "Client API" 
        direction TB
        Mobile["Mobile Client"]:::clientapi
        Guest["Guest Client"]:::clientapi
        Web["Web Client (deprecated)"]:::clientapi
    end

    %% Auth & Session Layer
    subgraph "Auth & Session Management"
        direction TB
        Authn["Authentication"]:::core
        Creds["Credentials"]:::core
        PassEnc["PasswordEncryption"]:::core
        SessMgr["SessionManager"]:::core
        WebSess["WebSession"]:::core
    end

    %% Resolver & Utils Layer
    subgraph "Endpoint Resolution & Utilities"
        direction TB
        Resolver["MediaResolver"]:::core
        Utils["Utils"]:::utils
    end

    %% HTTP Transport Layer
    HTTP["HTTP Transport (requests, proxies)"]:::utils

    %% Parsing & Data Modeling Layer
    subgraph "Parsing & Data Modeling"
        direction TB
        Parser["Parser Modules"]:::parsing
        Containers["Typed Response Wrappers"]:::parsing
        Structures["Domain Models (structures)"]:::parsing
    end

    %% Shared Utilities & Error Handling
    subgraph "Shared Utilities"
        direction TB
        Exceptions["Exceptions"]:::utils
        Searcher["Searcher"]:::utils
    end

    %% External Instagram API
    External["Instagram API Endpoints"]:::external

    %% Tests & CI
    subgraph "Tests & CI"
        direction TB
        Tests["test_ensta/"]:::tests
        Resources["test_ensta/resources/"]:::tests
        CI[".github/workflows"]:::tests
    end

    %% Connections
    U -->|"imports"| Mobile
    U -->|"imports"| Guest
    U -->|"imports"| Web

    Mobile -->|"authenticate"| Authn
    Guest -->|"authenticate"| Authn
    Authn -->|"uses"| Creds
    Authn -->|"uses"| PassEnc
    Authn -->|"init session"| SessMgr
    SessMgr -->|"extends"| WebSess

    Mobile -->|"construct request"| Resolver
    Guest -->|"construct request"| Resolver
    Resolver -->|"format params"| Utils
    Utils -->|"search nested"| Searcher

    SessMgr -->|"send HTTP"| HTTP
    HTTP -->|"HTTP calls"| External
    External -->|"JSON response"| SessMgr

    SessMgr -->|"raw JSON"| Parser
    Parser -->|"parsed data"| Containers
    Containers -->|"wraps"| Structures
    Parser -->|"errors"| Exceptions

    Structures -->|"returned to"| Mobile
    Structures -->|"returned to"| Guest

    %% Tests connections
    Tests -->|"validates"| Mobile
    Tests -->|"validates"| Resolver
    Tests -->|"validates"| Utils

    %% Click Events
    click Mobile "https://github.com/diezo/ensta/blob/master/ensta/Mobile.py"
    click Guest "https://github.com/diezo/ensta/blob/master/ensta/Guest.py"
    click Web "https://github.com/diezo/ensta/blob/master/ensta/Web.py"
    click Authn "https://github.com/diezo/ensta/blob/master/ensta/Authentication.py"
    click Creds "https://github.com/diezo/ensta/blob/master/ensta/Credentials.py"
    click PassEnc "https://github.com/diezo/ensta/blob/master/ensta/PasswordEncryption.py"
    click SessMgr "https://github.com/diezo/ensta/blob/master/ensta/SessionManager.py"
    click WebSess "https://github.com/diezo/ensta/blob/master/ensta/WebSession.py"
    click Resolver "https://github.com/diezo/ensta/blob/master/ensta/MediaResolver.py"
    click Utils "https://github.com/diezo/ensta/blob/master/ensta/Utils.py"
    click Parser "https://github.com/diezo/ensta/tree/master/ensta/parser/"
    click Containers "https://github.com/diezo/ensta/tree/master/ensta/containers/"
    click Structures "https://github.com/diezo/ensta/tree/master/ensta/structures/"
    click Exceptions "https://github.com/diezo/ensta/blob/master/ensta/lib/Exceptions.py"
    click Searcher "https://github.com/diezo/ensta/blob/master/ensta/lib/Searcher.py"
    click Tests "https://github.com/diezo/ensta/tree/master/test_ensta/"
    click Resources "https://github.com/diezo/ensta/tree/master/test_ensta/resources/"
    click CI "https://github.com/diezo/ensta/tree/master/.github/workflows"

    %% Styles
    classDef clientapi fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef core fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef parsing fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef utils fill:#ECEFF1,stroke:#90A4AE,color:#000
    classDef external fill:#FFCDD2,stroke:#D32F2F,color:#000
    classDef tests fill:#E1BEE7,stroke:#8E24AA,color:#000
```
