Convex Database Schema

Relevant source files

The following files were used as context for generating this wiki page:

• convex/schema.ts
• server/shared/convexClient.ts
• convex/_generated/dataModel.d.ts
• tests/convex/helpers.ts
• tests/convex/crons.test.ts
• AGENTS.md

The Convex Database Schema serves as the central data definition for the bot-auto-ig project. It manages state for automation profiles, Instagram accounts, message templates, and a complex workflow execution system. The schema is built using Convex's type-safe defineSchema and defineTable utilities, ensuring consistency across the backend, frontend, and Python automation runners.

Sources: convex/schema.ts:1-5, AGENTS.md:28-35

Core Data Entities

The database is structured around several primary tables that manage the lifecycle of automation activities.

Lists and Profiles

The lists table provides a grouping mechanism for automation targets, while the profiles table stores detailed configuration for browser environments, including proxy settings, fingerprints, and scraping session states.

Table	Field	Type	Description
lists	name	string	Name of the list grouping.
profiles	name	string	Unique identifier for the profile.
	proxy	optional(string)	Proxy address (IP:Port).
	cookiesJson	optional(string)	Serialized browser cookies.
	listIds	optional(array(id("lists")))	References to associated lists.
	dailyScrapingLimit	optional(number)	Cap for daily scraping operations.

Sources: convex/schema.ts:5-36, server/shared/convexClient.ts:39-65

Instagram Accounts

The instagramAccounts table tracks the status of specific accounts used within the automation. It includes fields for tracking subscription status and messaging history, and can be assigned to specific browser profiles.

Sources: convex/schema.ts:38-51

Workflow System Tables

The workflow system is a sophisticated orchestration engine that manages automated task sequences. It uses two primary tables to track definitions and execution outputs.

Workflow Definitions

The workflows table stores the graph structure (nodes and edges) compatible with ReactFlow, along with scheduling configurations and execution state.

Workflow Artifacts

workflowArtifacts store the results of executed workflow nodes, such as scraped follower lists. They link back to the originating workflow and node, and track storage references for generated data files.

Sources: convex/schema.ts:114-142

Data Relationships and Flow

The system facilitates a flow where browser profiles are assigned to lists, and workflows execute tasks against those lists to generate artifacts.

Database Indices

To optimize query performance, several indices are defined across the tables, particularly for status-based filtering and relationship lookups.

Table	Index Name	Indexed Fields
profiles	by_name	["name"]
	by_status	["status"]
instagramAccounts	by_userName	["userName"]
	by_assignedTo_status	["assignedTo", "status"]
workflows	by_isActive	["isActive"]
	by_scheduledAt	["scheduledAt"]
workflowArtifacts	by_workflowId_nodeId	["workflowId", "nodeId"]

Sources: convex/schema.ts:35-36, 48-51, 107-112, 140-142

Keywords and Templates

The schema also includes utility tables for content management:

• Keywords: Stores newline-separated word lists (e.g., us_male_names.txt) used for filtration logic.
• Message Templates: Stores text arrays for automated messaging, categorized by "kind."

Sources: convex/schema.ts:53-58, 148-152, tests/convex/keywords.test.ts:8-15

Conclusion

The Convex Database Schema is the foundational layer of the bot-auto-ig platform. By centralizing profile configurations, workflow definitions, and scraping results within a single type-safe schema, it enables seamless communication between the React-based frontend and the Python-driven automation runners. The inclusion of specialized tables like workflowArtifacts and keywords demonstrates a design focused on scalable data extraction and targeted automation.