hanzvibes/instajs

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.