Introduction & Repository Map
Relevant source files
The following files were used as context for generating this wiki page:
This page provides a high-level overview of the bot-auto-ig repository, outlining its architectural components, data models, and the organizational structure of the codebase. The project is an automation platform designed for Instagram operations, utilizing a React-based frontend, a Node.js/Express server, a Python-based automation runtime, and a Convex backend for data persistence and real-time synchronization.
The repository is structured as a monorepo containing distinct services that communicate via HTTP APIs and shared database schemas. Key domains include profile management, workflow automation, scraped data handling (artifacts), and account monitoring.
Architectural Overview
The system architecture is divided into four primary layers: the User Interface (Frontend), the API Gateway (Server), the Automation Runtime (Python), and the Persistence Layer (Convex).
System Component Flow
The following diagram illustrates how different parts of the repository interact during a standard operation, such as starting a workflow.
Repository Structure
The repository follows a clear separation of concerns across different technological stacks.
| Directory | Primary Responsibility | Key Technologies |
|---|---|---|
frontend/ | User dashboard, workflow editor, and monitoring UI. | React Router, ReactFlow, Tailwind CSS |
server/ | API routes for automation, profiles, and WebSocket management. | Node.js, Express |
python/ | Automation runtime, Instagram domain actions, and browser lifecycle. | Python, Playwright/Selenium |
convex/ | Database schema, crons, migrations, and serverless functions. | TypeScript, Convex |
datauploader/ | Ingest service for CSV and workflow artifacts. | Node.js |
data/ | Local storage for runtime logs and uploads. | Filesystem |
Sources: AGENTS.md:20-33, frontend/package.json:28-56
Data Model & Schema
The core of the system relies on the Convex schema, which defines the state for profiles, workflows, and the data scraped during automation tasks.
Entity Relationships
The data model centers around Workflows that generate Artifacts and Profiles that execute the automation.
Sources: convex/schema.ts:5-135
Core Tables Summary
| Table | Purpose | Key Fields |
|---|---|---|
profiles | Represents an automation identity with browser fingerprints and proxy settings. | name, proxy, status, cookiesJson, fingerprintSeed |
workflows | Defines automation logic using a node-based graph and scheduling config. | nodes, edges, scheduleType, isActive, status |
workflowArtifacts | Stores results from completed scrapes, including file storage references. | workflowId, kind, storageId, stats, targets |
instagramAccounts | High-level account data associated with specific profiles. | userName, status, assignedTo, lastMessagedAt |
Sources: convex/schema.ts:11-125
Development & Operations
Standard Workflow
The project follows a specific developer workflow governed by the system of record located in the docs/ directory. For changes involving the backend, tests are run via npm run test:convex. Automation logic changes require updates to the Python tests located in python/tests.
Security and Environment
The system relies heavily on environment variables (.env and .env.local). A critical security component is the INTERNAL_API_KEY, which is used to authorize requests between the different services (Python runtime, Express server, and Convex HTTP endpoints).
Sources: AGENTS.md:35-59, server/shared/convexClient.ts:19-24
Summary
The bot-auto-ig repository is a multi-layered automation system. It leverages React for a sophisticated "node-editor" based workflow builder, Python for robust browser-based automation, and Convex for a reactive, real-time backend. The repository structure ensures that UI, API, automation, and data logic remain decoupled while sharing a unified data schema for consistent state management.