Account & Profile Management
Relevant source files
The following files were used as context for generating this wiki page:
- convex/schema.ts
- convex/profiles/helpers.ts
- server/shared/convexClient.ts
- frontend/src/features/profiles/hooks/useProfilesPage.ts
- frontend/src/features/profiles/components/ProfileForm.tsx
- frontend/src/features/profiles/components/ProfileDetails.tsx
- frontend/src/features/accounts/components/AccountsTaskDetails.tsx
The Account & Profile Management system is a core component of the bot-auto-ig architecture, responsible for orchestrating the relationships between automated browser profiles, proxies, and Instagram accounts. Profiles serve as the execution environment, encapsulating session data (cookies), hardware fingerprints, and network configurations (proxies) to simulate human-like browsing behavior. Instagram accounts are entities assigned to these profiles, governed by limits and status tracking to ensure scraping efficiency and account safety.
Sources: convex/schema.ts:11-54, AGENTS.md:28-35
Profile Architecture and Data Model
Profiles are the primary units of automation. Each profile record maintains detailed state regarding its connectivity, browser identity, and resource utilization.
Data Schema
The profiles table in Convex stores all configuration and runtime state for browser instances.
| Field | Type | Description |
|---|---|---|
name | string | Unique identifier for the profile. |
proxy | string (optional) | Proxy connection string (host:port:user:pass). |
status | string | Current runtime state (e.g., "idle", "running"). |
using | boolean | Indicates if the profile is currently active in a session. |
fingerprintSeed | string | Seed used to generate consistent browser fingerprints. |
cookiesJson | string | JSON string containing serialized browser cookies. |
dailyScrapingLimit | number | Hard cap on items scraped per 24-hour period. |
scrapeLeaseOwner | string | ID of the worker currently holding an execution lease. |
Sources: convex/schema.ts:11-36, server/shared/convexClient.ts:40-65
Lease & Health Management
Profiles utilize a leasing mechanism to prevent concurrent access by multiple workers. A lease is claimed for a specific duration (leaseMs) and must be refreshed or released upon task completion. Profile "health" is tracked numerically (0-100), decreasing upon scrape failures and recovering upon successes.
Sources: convex/profiles/helpers.ts:182-243
Instagram Account Management
Instagram accounts represent the target identities or personas being managed. These accounts are linked to specific profiles for consistency in IP addresses and browser fingerprints.
Account Attributes
| Field | Type | Description |
|---|---|---|
userName | string | The Instagram handle. |
assignedTo | ID (profiles) | Reference to the profile managing this account. |
status | string | Account status (e.g., "available", "flagged"). |
lastMessagedAt | number | Timestamp of the last outbound communication. |
Sources: convex/schema.ts:38-51
Assignment Logic
Profiles have an assignedAccountsLimit (defaulting to 10) which restricts how many Instagram accounts a single profile can manage. This prevents over-utilization of a single proxy or browser environment.
Sources: convex/profiles/helpers.ts:5-6, frontend/src/features/profiles/components/ProfileForm.tsx:300-330
Implementation Details
Profile Lifecycle and Transitions
Profiles transition between states based on automated workflows or manual user intervention in the frontend.
Browser Fingerprinting
The system generates a fingerprintSeed and tracks fingerprintOs (Windows, macOS, or Linux) to ensure that automated sessions remain consistent across restarts. This is critical for bypassing platform detection mechanisms.
Sources: frontend/src/features/profiles/components/ProfileForm.tsx:210-250, convex/profiles/helpers.ts:107-111
Scraping Capacity Control
Capacity is managed through daily limits and usage tracking:
- Limit Definition: Users set
dailyScrapingLimitin theProfileForm. - Usage Tracking: Each successful scrape increments
dailyScrapingUsed. - Availability Check: The helper
hasRemainingDailyCapacityreturns false if the limit is reached, preventing the profile from being selected for new tasks.
Sources: convex/profiles/helpers.ts:52-56, frontend/src/features/profiles/components/ProfileForm.tsx:255-295
Summary
The Account & Profile Management system provides the necessary abstraction for safe Instagram automation. By decoupling the browser environment (Profiles) from the social identities (Accounts) and strictly managing proxies, fingerprints, and scraping leases, the system ensures a high level of operational stability and detection avoidance.
Sources: convex/schema.ts:1-55, server/shared/convexClient.ts:1-300