# hanzvibes/instajs architecture

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

- Interactive diagram: https://gitdiagram.com/hanzvibes/instajs
- Repository: https://github.com/hanzvibes/instajs

## Overview

1. **Repository type and runtime**
   - This is a **Node.js command-line automation tool** for Instagram, not a web app.
   - The main entrypoint is **`index.js`**, which likely presents the CLI flow and dispatches to feature modules under `src/`.

2. **Primary boundary: Instagram as the external system**
   - The only major external dependency is **Instagram itself**.
   - All bot behavior revolves around interacting with Instagram users, posts, stories, hashtags, locations, and follower graphs.

3. **Core integration layer**
   - **`src/api.js`** is the central integration module.
   - It likely wraps the low-level Instagram session/authentication and exposes reusable operations consumed by the feature-specific modules.

4. **Configuration and authentication**
   - Credentials come from **`.env`** via `dotenv`, as documented in the README.
   - This means account identity is configured outside the codebase, while runtime behavior is driven by the CLI and environment variables.

5. **Feature subsystems by content source**
   - The code is organized by where targets come from:
     - **`src/feeds/`**: actions on the user’s feed and stories.
     - **`src/hashtags/`**: actions against hashtag-generated content.
     - **`src/targetFollowers/`**: actions against followers of a chosen account.
     - **`src/targetFollowings/`**: actions against accounts followed by a chosen target.
     - **`src/targetLocation/`**: actions against posts/accounts discovered by location.
     - **`src/targets/`**: custom target-profile actions.
   - This structure is the clearest architectural boundary in the repo.

6. **Feature subsystems by action type**
   - The automation actions are split into small purpose-built modules:
     - **follow**
     - **like**
     - **comment**
     - **followLike**
     - **followLikeComment**
     - **DM variants** under `src/dm/`
     - **story_views**
   - This suggests the architecture is composed of reusable action pipelines rather than one monolithic bot loop.

7. **Account maintenance and cleanup**
   - **`src/accounts/`** handles ongoing hygiene tasks:
     - unfollowing inactive users,
     - unfollowing users with no posts,
     - unfollowing non-follow-backs,
     - cleaning media/posts.
   - These are distinct from growth/engagement actions and represent a separate maintenance subsystem.

8. **State persistence and idempotency**
   - The **`logs/`** tree is a major architectural piece.
   - Separate log folders exist for accounts, feeds, hashtags, targets, target followers, target followings, and target locations.
   - The README says the bot remembers previously interacted users, so these logs are used as persistent state to avoid reprocessing after restart.

9. **Typical data flow**
   - A CLI command selects a feature.
   - The relevant module discovers candidate users/posts from Instagram.
   - The module applies interaction rules and delays to simulate human behavior.
   - Successful actions are recorded in the corresponding log path.
   - Later runs consult those logs to skip already-processed accounts/content.

10. **Operational concerns**
   - The README emphasizes **auto-set delays** and **human-like pacing**, which indicates timing/throttling is an architectural concern, not just a utility detail.
   - This affects all action modules and likely sits in shared logic inside the API layer or the CLI dispatcher.

11. **UI/assets and packaging**
   - **`assets/`** is only for branding/screenshots/banner images, not runtime logic.
   - **`package.json`** defines the Node package/runtime dependencies, while `.gitignore` and `LICENSE` are repo scaffolding rather than architectural components.

12. **How to diagram it**
   - A good architecture diagram would show:
     - **CLI entrypoint (`index.js`)**
     - **shared Instagram API layer (`src/api.js`)**
     - **feature modules grouped by source and action**
     - **filesystem logs as persistent state**
     - **Instagram as the external service boundary**
   - The repo is essentially a **modular automation engine** with feature-specific pipelines feeding a shared Instagram interaction layer.

Main entry points: [`index.js`](https://github.com/hanzvibes/instajs/blob/main/index.js) (CLI entry), [`logs`](https://github.com/hanzvibes/instajs/tree/main/logs) (Logs), [`src/feeds`](https://github.com/hanzvibes/instajs/tree/main/src/feeds) (Feed actions), [`src/hashtags`](https://github.com/hanzvibes/instajs/tree/main/src/hashtags) (Hashtag actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI"]
  node_node_index["CLI entry<br/>node.js entrypoint<br/>[index.js]"]
  node_node_pkg["Package<br/>runtime metadata<br/>[package.json]"]
end

subgraph group_group_core["Core"]
  node_node_api["API layer<br/>instagram adapter<br/>[api.js]"]
  node_node_info["Account info<br/>profile lookup<br/>[info.js]"]
end

subgraph group_group_sources["Target sources"]
  node_node_feeds["Feed actions<br/>content source"]
  node_node_hashtags["Hashtag actions<br/>content source"]
  node_node_tfollowers["Followers target<br/>audience source"]
  node_node_tfollowings["Followings target<br/>audience source"]
  node_node_tlocation["Location target<br/>location source"]
  node_node_targets["Custom target<br/>manual target source"]
  node_node_dm["DM actions<br/>direct message pipeline"]
  node_node_story["Story views<br/>view action<br/>[story_views.js]"]
end

subgraph group_group_maintenance["Maintenance"]
  node_node_accounts["Account cleanup<br/>maintenance"]
end

subgraph group_group_state["State"]
  node_node_logs[("Logs<br/>persistent state")]
end

subgraph group_group_external["External"]
  node_node_instagram{{"Instagram<br/>external service"}}
end

node_node_follow["Follow<br/>engagement action<br/>[follow.js]"]
node_node_like["Like<br/>engagement action<br/>[like.js]"]
node_node_comment["Comment<br/>engagement action<br/>[comment.js]"]
node_node_combo["Combined flow<br/>multi-action pipeline"]

node_node_index -->|"dispatches"| node_node_api
node_node_index -->|"runs"| node_node_feeds
node_node_index -->|"runs"| node_node_hashtags
node_node_index -->|"runs"| node_node_tfollowers
node_node_index -->|"runs"| node_node_tfollowings
node_node_index -->|"runs"| node_node_tlocation
node_node_index -->|"runs"| node_node_targets
node_node_index -->|"runs"| node_node_accounts
node_node_index -->|"runs"| node_node_dm
node_node_feeds -->|"uses"| node_node_like
node_node_feeds -->|"uses"| node_node_combo
node_node_feeds -->|"uses"| node_node_story
node_node_hashtags -->|"uses"| node_node_follow
node_node_hashtags -->|"uses"| node_node_like
node_node_hashtags -->|"uses"| node_node_comment
node_node_tfollowers -->|"uses"| node_node_combo
node_node_tfollowings -->|"uses"| node_node_follow
node_node_tlocation -->|"uses"| node_node_comment
node_node_targets -->|"uses"| node_node_like
node_node_accounts -->|"uses"| node_node_api
node_node_dm -->|"uses"| node_node_api
node_node_api -->|"integrates"| node_node_instagram
node_node_logs -->|"persists"| node_node_feeds
node_node_logs -->|"persists"| node_node_hashtags
node_node_logs -->|"persists"| node_node_tfollowers
node_node_logs -->|"persists"| node_node_tfollowings
node_node_logs -->|"persists"| node_node_tlocation
node_node_logs -->|"persists"| node_node_targets
node_node_logs -->|"persists"| node_node_accounts

click node_node_index "https://github.com/hanzvibes/instajs/blob/main/index.js"
click node_node_pkg "https://github.com/hanzvibes/instajs/blob/main/package.json"
click node_node_api "https://github.com/hanzvibes/instajs/blob/main/src/api.js"
click node_node_info "https://github.com/hanzvibes/instajs/blob/main/src/info.js"
click node_node_feeds "https://github.com/hanzvibes/instajs/tree/main/src/feeds"
click node_node_hashtags "https://github.com/hanzvibes/instajs/tree/main/src/hashtags"
click node_node_tfollowers "https://github.com/hanzvibes/instajs/tree/main/src/targetFollowers"
click node_node_tfollowings "https://github.com/hanzvibes/instajs/tree/main/src/targetFollowings"
click node_node_tlocation "https://github.com/hanzvibes/instajs/tree/main/src/targetLocation"
click node_node_targets "https://github.com/hanzvibes/instajs/tree/main/src/targets"
click node_node_accounts "https://github.com/hanzvibes/instajs/tree/main/src/accounts"
click node_node_dm "https://github.com/hanzvibes/instajs/tree/main/src/dm"
click node_node_follow "https://github.com/hanzvibes/instajs/blob/main/src/hashtags/follow.js"
click node_node_like "https://github.com/hanzvibes/instajs/blob/main/src/feeds/like.js"
click node_node_comment "https://github.com/hanzvibes/instajs/blob/main/src/hashtags/comment.js"
click node_node_combo "https://github.com/hanzvibes/instajs/blob/main/src/hashtags/followLikeComment.js"
click node_node_story "https://github.com/hanzvibes/instajs/blob/main/src/feeds/story_views.js"
click node_node_logs "https://github.com/hanzvibes/instajs/tree/main/logs"

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_node_index,node_node_pkg toneBlue
class node_node_api,node_node_info toneAmber
class node_node_feeds,node_node_hashtags,node_node_tfollowers,node_node_tfollowings,node_node_tlocation,node_node_targets,node_node_dm,node_node_story toneMint
class node_node_accounts toneRose
class node_node_logs toneIndigo
class node_node_instagram toneTeal
class node_node_follow,node_node_like,node_node_comment,node_node_combo toneNeutral
```

## Components

### CLI

Command entrypoint and package runtime

- [CLI entry](https://github.com/hanzvibes/instajs/blob/main/index.js): node.js entrypoint · Main command dispatcher for the automation flows · `index.js`
- [Package](https://github.com/hanzvibes/instajs/blob/main/package.json): runtime metadata · Dependencies and scripts for the Node.js tool · `package.json`

### Core

Shared Instagram integration and account info

- [API layer](https://github.com/hanzvibes/instajs/blob/main/src/api.js): instagram adapter · Shared integration layer wrapping Instagram session and actions · `src/api.js`
- [Account info](https://github.com/hanzvibes/instajs/blob/main/src/info.js): profile lookup · Helper for retrieving or presenting account information · `src/info.js`

### Target sources

Feature pipelines organized by where candidates come from

- [Feed actions](https://github.com/hanzvibes/instajs/tree/main/src/feeds): content source · Interactions driven by the user feed and stories · `src/feeds`
- [Hashtag actions](https://github.com/hanzvibes/instajs/tree/main/src/hashtags): content source · Interactions driven by hashtag-discovered content · `src/hashtags`
- [Followers target](https://github.com/hanzvibes/instajs/tree/main/src/targetFollowers): audience source · Actions against followers of a chosen account · `src/targetFollowers`
- [Followings target](https://github.com/hanzvibes/instajs/tree/main/src/targetFollowings): audience source · Actions against accounts followed by a chosen target · `src/targetFollowings`
- [Location target](https://github.com/hanzvibes/instajs/tree/main/src/targetLocation): location source · Actions against posts or users found by location · `src/targetLocation`
- [Custom target](https://github.com/hanzvibes/instajs/tree/main/src/targets): manual target source · Actions against explicitly chosen target profiles · `src/targets`
- [DM actions](https://github.com/hanzvibes/instajs/tree/main/src/dm): direct message pipeline · Follow-like-comment variants that include messaging · `src/dm`
- [Story views](https://github.com/hanzvibes/instajs/blob/main/src/feeds/story_views.js): view action · Story viewing automation for feed stories · `src/feeds/story_views.js`

### Maintenance

Account cleanup and hygiene tasks

- [Account cleanup](https://github.com/hanzvibes/instajs/tree/main/src/accounts): maintenance · Hygiene tasks such as unfollowing and media cleanup · `src/accounts`

### State

Persistent logs used to avoid reprocessing

- [Logs](https://github.com/hanzvibes/instajs/tree/main/logs): persistent state · Filesystem records that track processed accounts and content · `logs`

### External

Outside system boundary

- **Instagram**: external service · Target platform and network boundary

### Other components

- [Follow](https://github.com/hanzvibes/instajs/blob/main/src/hashtags/follow.js): engagement action · Core follow operation used by multiple source pipelines · `src/hashtags/follow.js`
- [Like](https://github.com/hanzvibes/instajs/blob/main/src/feeds/like.js): engagement action · Core like operation reused across source pipelines · `src/feeds/like.js`
- [Comment](https://github.com/hanzvibes/instajs/blob/main/src/hashtags/comment.js): engagement action · Commenting operation used in combined engagement flows · `src/hashtags/comment.js`
- [Combined flow](https://github.com/hanzvibes/instajs/blob/main/src/hashtags/followLikeComment.js): multi-action pipeline · Follow-like and follow-like-comment variants · `src/hashtags/followLikeComment.js`

## Connections

- CLI entry → API layer: dispatches · CLI routes commands into the shared integration layer
- CLI entry → Feed actions: runs · CLI can start feed-based automation flows
- CLI entry → Hashtag actions: runs · CLI can start hashtag-based automation flows
- CLI entry → Followers target: runs · CLI can start follower-targeted flows
- CLI entry → Followings target: runs · CLI can start followings-targeted flows
- CLI entry → Location target: runs · CLI can start location-targeted flows
- CLI entry → Custom target: runs · CLI can start custom target flows
- CLI entry → Account cleanup: runs · CLI can trigger maintenance tasks
- CLI entry → DM actions: runs · CLI can start DM-enhanced engagement flows
- Feed actions → Like: uses · Feed flows perform likes
- Feed actions → Combined flow: uses · Feed flows can combine actions
- Feed actions → Story views: uses · Feed subsystem includes story viewing
- Hashtag actions → Follow: uses · Hashtag flows can follow discovered users
- Hashtag actions → Like: uses · Hashtag flows can like discovered content
- Hashtag actions → Comment: uses · Hashtag flows can comment on content
- Followers target → Combined flow: uses · Follower-targeted flows favor combined engagement sequences
- Followings target → Follow: uses · Following-targeted flows emphasize follow actions
- Location target → Comment: uses · Location-targeted flows support comments
- Custom target → Like: uses · Custom target flows can like posts
- Account cleanup → API layer: uses · Maintenance tasks share the same Instagram integration
- DM actions → API layer: uses · DM variants depend on the shared API layer
- API layer → Instagram: integrates · All automation ultimately acts on Instagram
- Logs → Feed actions: persists · Feed interactions are recorded for idempotency
- Logs → Hashtag actions: persists · Hashtag interactions are recorded for idempotency
- Logs → Followers target: persists · Follower-targeted runs are recorded for idempotency
- Logs → Followings target: persists · Following-targeted runs are recorded for idempotency
- Logs → Location target: persists · Location-targeted runs are recorded for idempotency
- Logs → Custom target: persists · Custom target runs are recorded for idempotency
- Logs → Account cleanup: persists · Maintenance tasks also use logs as durable state