# unseenap/carouselqueue architecture

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

## Overview

This package prepares and publishes four-slide Instagram carousels from classic and funny content queues. The main workflow selects a complete, unposted task, generates slides, uploads them to Cloudinary, publishes them through Instagram, and records the result. It also supports dry-run previews, series alternation, cooldown handling, and scheduled or manual runs. The source excerpt is partial, so details of omitted helper implementations and exact internal call wiring are not represented beyond the documented lifecycle.

Main entry points: [`automation/instagram_publisher.py`](https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py) (Publisher entry point), [`generated_images`](https://github.com/unseenap/carouselqueue/tree/main/generated_images) (Classic images and covers), [`generated_images_2`](https://github.com/unseenap/carouselqueue/tree/main/generated_images_2) (Funny images and covers), [`data`](https://github.com/unseenap/carouselqueue/tree/main/data) (Posting history and cooldown)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content preparation"]
  node_queues["Classic and funny queues"]
  node_classic_queue["Classic queue"]
  node_funny_queue["Funny queue"]
  node_selector["Task parsing and selection"]
  node_assets["Carousel image assets"]
  node_classic_assets["Classic images and covers"]
  node_funny_assets["Funny images and covers"]
end

subgraph group_publisher["Publishing runtime"]
  node_publisher["Publisher entry point"]
  node_renderer["Four-slide renderer"]
  node_preview["Local preview"]
  node_client["Instagram client"]
end

subgraph group_integrations["External services"]
  node_cloudinary["Cloudinary"]
  node_instagram["Instagram Graph API"]
end

subgraph group_operations["Scheduling and state"]
  node_actions["GitHub Actions"]
  node_state[("Posting history and cooldown")]
end

node_operator(("Operator / CLI"))

node_operator -->|"runs"| node_publisher
node_actions -->|"runs"| node_publisher
node_publisher -->|"selects task"| node_selector
node_classic_queue -->|"provides entries"| node_selector
node_funny_queue -->|"provides entries"| node_selector
node_selector -->|"checks files"| node_classic_assets
node_selector -->|"checks files"| node_funny_assets
node_state -->|"provides history"| node_selector
node_selector -->|"returns task"| node_publisher
node_publisher -->|"builds slides"| node_renderer
node_classic_assets -->|"provides images"| node_renderer
node_funny_assets -->|"provides images"| node_renderer
node_renderer -->|"writes preview"| node_preview
node_publisher -->|"uploads media"| node_cloudinary
node_cloudinary -->|"returns URLs"| node_publisher
node_publisher -->|"creates carousel"| node_client
node_client -->|"verifies and publishes"| node_instagram
node_instagram -->|"returns media ID"| node_client
node_publisher -->|"records result"| node_state

click node_actions "https://github.com/unseenap/carouselqueue/blob/main/.github/workflows/instagram-daily.yml"
click node_publisher "https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py"
click node_classic_queue "https://github.com/unseenap/carouselqueue/blob/main/website_image_tasks.md"
click node_funny_queue "https://github.com/unseenap/carouselqueue/blob/main/100_website_Useful_2.md"
click node_selector "https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py"
click node_classic_assets "https://github.com/unseenap/carouselqueue/tree/main/generated_images"
click node_funny_assets "https://github.com/unseenap/carouselqueue/tree/main/generated_images_2"
click node_renderer "https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py"
click node_preview "https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py"
click node_client "https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py"
click node_state "https://github.com/unseenap/carouselqueue/tree/main/data"

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_queues,node_classic_queue,node_funny_queue,node_selector,node_assets,node_classic_assets,node_funny_assets toneBlue
class node_publisher,node_renderer,node_preview,node_client toneAmber
class node_cloudinary,node_instagram toneMint
class node_actions,node_state toneRose
class node_operator toneIndigo
```

## Components

### Content preparation

- **Classic and funny queues**
- [Classic queue](https://github.com/unseenap/carouselqueue/blob/main/website_image_tasks.md): `website_image_tasks.md`
- [Funny queue](https://github.com/unseenap/carouselqueue/blob/main/100_website_Useful_2.md): `100_website_Useful_2.md`
- [Task parsing and selection](https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py): `automation/instagram_publisher.py`
- **Carousel image assets**
- [Classic images and covers](https://github.com/unseenap/carouselqueue/tree/main/generated_images): `generated_images`
- [Funny images and covers](https://github.com/unseenap/carouselqueue/tree/main/generated_images_2): `generated_images_2`

### Publishing runtime

- [Publisher entry point](https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py): `automation/instagram_publisher.py`
- [Four-slide renderer](https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py): `automation/instagram_publisher.py`
- [Local preview](https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py): `automation/instagram_publisher.py`
- [Instagram client](https://github.com/unseenap/carouselqueue/blob/main/automation/instagram_publisher.py): `automation/instagram_publisher.py`

### External services

- **Cloudinary**
- **Instagram Graph API**

### Scheduling and state

- [GitHub Actions](https://github.com/unseenap/carouselqueue/blob/main/.github/workflows/instagram-daily.yml): `.github/workflows/instagram-daily.yml`
- [Posting history and cooldown](https://github.com/unseenap/carouselqueue/tree/main/data): `data`

### Other components

- **Operator / CLI**

## Connections

- Operator / CLI → Publisher entry point: runs
- GitHub Actions → Publisher entry point: runs
- Publisher entry point → Task parsing and selection: selects task
- Classic queue → Task parsing and selection: provides entries
- Funny queue → Task parsing and selection: provides entries
- Task parsing and selection → Classic images and covers: checks files
- Task parsing and selection → Funny images and covers: checks files
- Posting history and cooldown → Task parsing and selection: provides history
- Task parsing and selection → Publisher entry point: returns task
- Publisher entry point → Four-slide renderer: builds slides
- Classic images and covers → Four-slide renderer: provides images
- Funny images and covers → Four-slide renderer: provides images
- Four-slide renderer → Local preview: writes preview
- Publisher entry point → Cloudinary: uploads media
- Cloudinary → Publisher entry point: returns URLs
- Publisher entry point → Instagram client: creates carousel
- Instagram client → Instagram Graph API: verifies and publishes
- Instagram Graph API → Instagram client: returns media ID
- Publisher entry point → Posting history and cooldown: records result