# bstoilov/py3-pinterest architecture

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

- Interactive diagram: https://gitdiagram.com/bstoilov/py3-pinterest
- Repository: https://github.com/bstoilov/py3-pinterest

## Overview

py3-pinterest is an unofficial Python client that mimics Pinterest’s browser-facing internal endpoints. A caller creates a Pinterest client, logs in to obtain reusable cookies, then invokes operations for pins, boards, social actions, search, or messaging; the client builds requests and exchanges them with Pinterest, returning response data. The README documents additional capabilities such as video uploads, sections, and recommendations. The excerpts show selected request, upload, bookmark, and credential paths; links for unsampled feature internals are therefore limited to documented client operations.

Main entry points: [`py3pin/Pinterest.py`](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py) (Pinterest client), [`py3pin/Registry.py`](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Registry.py) (Cookie registry), [`py3pin/RequestBuilder.py`](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/RequestBuilder.py) (Request builder), [`py3pin/BookmarkManager.py`](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/BookmarkManager.py) (Bookmark manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and Requests"]
  node_pinterest["Pinterest client<br/>[Pinterest.py]"]
  node_requestbuilder["Request builder<br/>[RequestBuilder.py]"]
  node_login["Browser login<br/>[Pinterest.py]"]
end

subgraph group_pins["Pin Operations"]
  node_pin_manage["Pin management<br/>[Pinterest.py]"]
  node_pin_upload["Image and video upload<br/>[Pinterest.py]"]
end

subgraph group_boards["Boards and Discovery"]
  node_boards["Board and sections<br/>[Pinterest.py]"]
  node_discovery["Search and recommendations<br/>[Pinterest.py]"]
end

subgraph group_social["Social and Messaging"]
  node_following["Follow actions<br/>[Pinterest.py]"]
  node_comments["Comments<br/>[Pinterest.py]"]
  node_messaging["Conversations<br/>[Pinterest.py]"]
end

subgraph group_state["Session State"]
  node_registry[("Cookie registry<br/>[Registry.py]")]
  node_bookmarks["Bookmark manager<br/>[BookmarkManager.py]"]
end

node_caller(("Python caller"))
node_pinterest_service{{"Pinterest endpoints"}}
node_s3{{"S3 upload service"}}

node_caller -->|"invokes"| node_pinterest
node_pinterest -->|"logs in"| node_login
node_login -->|"persists cookies"| node_registry
node_pinterest -->|"builds requests"| node_requestbuilder
node_pinterest -->|"dispatches"| node_pin_manage
node_pinterest -->|"dispatches"| node_pin_upload
node_pinterest -->|"dispatches"| node_boards
node_pinterest -->|"dispatches"| node_discovery
node_pinterest -->|"dispatches"| node_following
node_pinterest -->|"dispatches"| node_comments
node_pinterest -->|"dispatches"| node_messaging
node_pin_manage -->|"HTTP requests"| node_pinterest_service
node_boards -->|"HTTP requests"| node_pinterest_service
node_discovery -->|"HTTP requests"| node_pinterest_service
node_following -->|"HTTP requests"| node_pinterest_service
node_comments -->|"HTTP requests"| node_pinterest_service
node_messaging -->|"HTTP requests"| node_pinterest_service
node_pin_upload -->|"registers upload"| node_pinterest_service
node_pin_upload -->|"uploads media"| node_s3
node_pin_upload -->|"polls status"| node_pinterest_service
node_pinterest -->|"tracks pagination"| node_bookmarks
node_pinterest -->|"loads cookies"| node_registry

click node_pinterest "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_requestbuilder "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/RequestBuilder.py"
click node_login "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_registry "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Registry.py"
click node_bookmarks "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/BookmarkManager.py"
click node_pin_manage "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_pin_upload "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_boards "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_discovery "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_following "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_comments "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py"
click node_messaging "https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.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_pinterest,node_requestbuilder,node_login toneBlue
class node_pin_manage,node_pin_upload toneAmber
class node_boards,node_discovery toneMint
class node_following,node_comments,node_messaging toneRose
class node_registry,node_bookmarks,node_caller,node_pinterest_service,node_s3 toneIndigo
```

## Components

### Client and Requests

- [Pinterest client](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`
- [Request builder](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/RequestBuilder.py): `py3pin/RequestBuilder.py`
- [Browser login](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`

### Pin Operations

- [Pin management](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`
- [Image and video upload](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`

### Boards and Discovery

- [Board and sections](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`
- [Search and recommendations](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`

### Social and Messaging

- [Follow actions](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`
- [Comments](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`
- [Conversations](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Pinterest.py): `py3pin/Pinterest.py`

### Session State

- [Cookie registry](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/Registry.py): `py3pin/Registry.py`
- [Bookmark manager](https://github.com/bstoilov/py3-pinterest/blob/master/py3pin/BookmarkManager.py): `py3pin/BookmarkManager.py`

### Other components

- **Python caller**
- **Pinterest endpoints**
- **S3 upload service**

## Connections

- Python caller → Pinterest client: invokes
- Pinterest client → Browser login: logs in
- Browser login → Cookie registry: persists cookies
- Pinterest client → Request builder: builds requests
- Pinterest client → Pin management: dispatches
- Pinterest client → Image and video upload: dispatches
- Pinterest client → Board and sections: dispatches
- Pinterest client → Search and recommendations: dispatches
- Pinterest client → Follow actions: dispatches
- Pinterest client → Comments: dispatches
- Pinterest client → Conversations: dispatches
- Pin management → Pinterest endpoints: HTTP requests
- Board and sections → Pinterest endpoints: HTTP requests
- Search and recommendations → Pinterest endpoints: HTTP requests
- Follow actions → Pinterest endpoints: HTTP requests
- Comments → Pinterest endpoints: HTTP requests
- Conversations → Pinterest endpoints: HTTP requests
- Image and video upload → Pinterest endpoints: registers upload
- Image and video upload → S3 upload service: uploads media
- Image and video upload → Pinterest endpoints: polls status
- Pinterest client → Bookmark manager: tracks pagination
- Pinterest client → Cookie registry: loads cookies