Developer Workflow & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page outlines the standard procedures, architectural dependencies, and environment configurations required for developing and running the bot-auto-ig project. The system is a multi-component automation platform comprising a React frontend, an Express-based server, a Python automation runtime, and a Convex backend.
The project follows a distributed architecture where the frontend communicates with both a centralized Convex backend for data persistence and a local Express server for executing automation tasks. Developers must manage environment variables across these layers to ensure secure and functional local execution.
Sources: AGENTS.md:1-40, server/shared/convexClient.ts:1-30
Project Architecture Overview
The system is divided into several distinct domains, each with specific responsibilities and technology stacks.
| Domain | Technology | Responsibility |
|---|---|---|
| Frontend | React, React Router, Tailwind CSS | UI for profiles, workflows, monitoring, and VNC access. |
| Server | Express, Node.js, WebSockets | API gateway for automation, local hardware management, and real-time logs. |
| Python | Python 3, Pytest | Automation runtime (runners, browser lifecycle, Instagram actions). |
| Convex | Convex Backend | Database schema, crons, and cloud functions. |
| Data Uploader | Node.js | Service for CSV and workflow-artifact ingestion. |
The following diagram illustrates the high-level relationship between these components:
Sources: AGENTS.md:38-51, frontend/package.json:37-65
Local Development Setup
Environment Configuration
Local setup requires a .env file at the project root. This file is the system of record for credentials and service endpoints. Critical variables include CONVEX_URL and INTERNAL_API_KEY, which are used by the Express server to communicate with the Convex HTTP API.
// Example of how environment variables are loaded in the server
dotenv.config({ path: path.resolve(__dirname, '../../.env'), quiet: true });
const convexCloudUrl = process.env.CONVEX_URL;
const convexApiKey = process.env.INTERNAL_API_KEY?.trim() || '';
Sources: server/shared/convexClient.ts:11-30, AGENTS.md:73-75
Quick Start Commands
The project provides several npm scripts to manage the lifecycle of different components.
| Action | Command |
|---|---|
| Full Stack | npm run dev (root) |
| Build Project | npm run build (root) |
| Frontend Dev | npm --prefix frontend run dev |
| Server Dev | npm --prefix server run dev |
| Convex Tests | npm run test:convex |
| Python Tests | python -m pytest python/tests -q |
| Docker Start | docker compose up --build |
Sources: AGENTS.md:53-65, frontend/package.json:6-15
Coding & Testing Standards
Language Conventions
- TypeScript/TSX: Uses 2-space indentation and single quotes. React components use
PascalCasefilenames, while hooks useuseX.tsoruseX.tsx. - Python: Follows PEP 8 guidelines and uses
snake_casefor naming. - Convex: Modifications to the schema or modules require running
npm run test:convexto ensure no regressions.
Regression Testing
Developers use specialized scripts to verify workflow integrity before merging changes. For example, workflow-regression-proof.ts checks that critical API wiring for creating, duplicating, and stopping workflows remains intact and that runtime protocol files in server/, convex/, and python/ have not been altered unexpectedly.
Component-Specific Workflows
Frontend Development
The frontend is a React Router application. Key feature-owned UI code resides in frontend/src/features/. When adding new UI components, developers should utilize the predefined UI library (Radix UI, Lucide icons) as specified in the dependencies.
Automation Runtime Development
Developing for the Python runtime involves working in the python/ directory. Developers must ensure that any changes to automation behavior (e.g., retries or state handling) are accompanied by updated tests in python/tests/.
Backend (Convex) Integration
The Express server acts as a bridge to Convex using an HTTP client with built-in retry logic. The convexFetch function implements exponential backoff to handle transient network issues (e.g., ECONNRESET, ETIMEDOUT).
Security and Best Practices
- Secret Management: Never commit
.envor.env.localfiles. - API Security: Validate authentication and CORS behavior when modifying
server/security/*. - Relative Linking: Keep all documentation and internal links repo-relative to ensure portability across environments.
Sources: AGENTS.md:73-77
The developer workflow is designed to maintain a strict separation of concerns while providing robust tools for local testing and integration verification. By utilizing the root-level scripts and adherence to the regression testing protocols, developers can ensure that the complex interactions between the Express server, Python runtime, and Convex cloud functions remain stable.