Relevant source files
The following files were used as context for generating this wiki page:
The project leverages several third-party services to provide core functionalities such as browser automation, email communication, caching, and cloud storage. These integrations enhance the application's capabilities, allowing for complex operations like automated web interactions and efficient data management.
This document outlines the key third-party services integrated into the application, detailing their purpose, configuration, and how they are utilized within the codebase.
Browser Automation with Browserbase
The BrowserbaseService (apps/api/src/browserbase/browserbase.service.ts) is responsible for orchestrating browser automation tasks using the Browserbase SDK and Stagehand. This service enables functionalities like creating and managing browser sessions, navigating to URLs, checking login status, and executing complex automation instructions. It also integrates with AWS S3 for storing screenshots generated during automation runs.
Key Components and Functionality
- Browserbase SDK: Used for creating and managing browser contexts and sessions.
- Stagehand: An AI agent framework that interacts with the browser to execute instructions and extract data.
- Organization Context Management: The service manages
BrowserbaseContextrecords in the database, ensuring each organization has a persistent browser context for automations. ThegetOrCreateOrgContextmethod handles the creation and retrieval of these contexts, including a retry mechanism for concurrent creation attempts. - Session Management:
createSessionWithContextestablishes a new browser session linked to an organization's context, providing aliveViewUrlfor real-time monitoring.closeSessionis used to terminate sessions. - Browser Actions:
navigateToUrl: Directs a browser session to a specified URL.checkLoginStatus: Verifies if a user is logged into a website within a session by extracting page elements.executeAutomation: The core method that uses Stagehand to perform a sequence of actions based on given instructions and a target URL. It includes logic for checking authentication status and capturing screenshots.
- Automation CRUD: Provides methods for creating, retrieving, updating, and deleting browser automation definitions stored in the database (
db.browserAutomation). - Automation Execution:
startAutomationWithLiveView: Initiates an automation run, creates a live session, and returns a URL for live monitoring.executeAutomationOnSession: Executes a predefined automation within an existing live session.runBrowserAutomation: Executes an automation in a non-live session, handling session creation and closure internally.
- Screenshot Management: Integrates with AWS S3 to upload and retrieve presigned URLs for screenshots captured during automation runs.
Browserbase Context Creation Flow
The getOrCreateOrgContext method ensures that a unique Browserbase context exists for each organization, handling potential race conditions during creation.
Sources: apps/api/src/browserbase/browserbase.service.ts:40-104
Browser Automation Execution Flow
The runBrowserAutomation method orchestrates the full lifecycle of a browser automation, from session creation to execution and cleanup.
Sources: apps/api/src/browserbase/browserbase.service.ts:167-393
Email Service with Resend
The application uses Resend for sending emails. The resend.ts file (apps/api/src/email/resend.ts) provides a utility function sendEmail to abstract the email sending process.
Key Components and Functionality
- Resend Client: Initialized with
RESEND_API_KEYfrom environment variables. If the API key is missing, the client isnull, andsendEmailwill throw an error. sendEmailFunction:- Takes parameters like
to,subject,react(for React-based email templates),marketing,system,test,cc,scheduledAt, andattachments. - Dynamically determines the
fromandtoaddresses based onmarketing,system, ortestflags and corresponding environment variables (RESEND_FROM_MARKETING,RESEND_FROM_SYSTEM,RESEND_FROM_DEFAULT,RESEND_TO_TEST). - Supports attachments by converting
EmailAttachmentobjects into the format expected by the Resend SDK. - Includes error handling for API calls and missing environment variables.
- Takes parameters like
Email Sending Logic
Sources: apps/api/src/email/resend.ts:1-74
Caching and Key-Value Store with Upstash Redis
The upstash-redis.client.ts file (apps/api/src/assistant-chat/upstash-redis.client.ts) provides a client for a key-value store, primarily used for caching and managing state, particularly for assistant chat history.
Key Components and Functionality
- Upstash Redis: A serverless Redis solution used for persistent key-value storage.
InMemoryRedis: A local, in-memory implementation of a Redis-like client. This is used as a fallback when Upstash Redis configuration is not provided, making the application runnable without external Redis. It supportsget,set, anddeloperations with optional expiration.assistantChatRedisClient: This is the exported client instance. It is conditionally initialized:- If
UPSTASH_REDIS_REST_URLandUPSTASH_REDIS_REST_TOKENenvironment variables are present, it uses the@upstash/redisSDK. - Otherwise, it defaults to the
InMemoryRedisinstance.
- If
- Purpose: Used by services like
AssistantChatServiceto save and clear chat history.
Redis Client Initialization Flow
Sources: apps/api/src/assistant-chat/upstash-redis.client.ts:1-35
Cloud Storage with AWS S3
AWS S3 is utilized for storing large binary objects, specifically screenshots generated during browser automation runs. The BrowserbaseService interacts with S3 for this purpose, and the aws.config.ts file (apps/api/src/config/aws.config.ts) defines the configuration for AWS services.
Key Components and Functionality
S3Client: An instance of the AWS SDK S3 client, configured with region and credentials.bucketName: Configured viaAPP_AWS_BUCKET_NAMEenvironment variable, defaulting tocomp-attachments.uploadScreenshot: Uploads a base64 encoded screenshot to a specified S3 key.getPresignedUrl: Generates a temporary, time-limited URL for accessing private S3 objects, ensuring secure access to screenshots.awsConfig: A configuration object (apps/api/src/config/aws.config.ts) that registers AWS settings, includingregion,accessKeyId,secretAccessKey, andbucketName. It uses Zod for schema validation of these environment variables at application startup.
AWS Configuration
The awsConfig is registered using @nestjs/config's registerAs function, ensuring that AWS settings are validated and available throughout the application.
// apps/api/src/config/aws.config.ts
const awsConfigSchema = z.object({
region: z.string().default('us-east-1'),
accessKeyId: z.string().min(1, 'AWS_ACCESS_KEY_ID is required'),
secretAccessKey: z.string().min(1, 'AWS_SECRET_ACCESS_KEY is required'),
bucketName: z.string().min(1, 'AWS_BUCKET_NAME is required'),
endpoint: z.string().optional(),
});
export const awsConfig = registerAs('aws', (): AwsConfig => {
const config = {
region: process.env.APP_AWS_REGION || 'us-east-1',
accessKeyId: process.env.APP_AWS_ACCESS_KEY_ID || '',
secretAccessKey: process.env.APP_AWS_SECRET_ACCESS_KEY || '',
bucketName: process.env.APP_AWS_BUCKET_NAME || '',
endpoint: process.env.APP_AWS_ENDPOINT || '',
};
const result = awsConfigSchema.safeParse(config);
if (!result.success) {
throw new Error(
`AWS configuration validation failed: ${result.error.issues
.map((e) => `${e.path.join('.')}: ${e.message}`)
.join(', ')}`,
);
}
return result.data;
});Sources: apps/api/src/browserbase/browserbase.service.ts:16-37, apps/api/src/config/aws.config.ts:1-29
Other Third-Party Integrations
The project's README.md (README.md) also highlights several other key technologies and platforms that contribute to its overall architecture and functionality.
- Next.js: A React framework for building web applications.
- Trigger.dev: Likely used for background jobs, workflows, or event-driven tasks. The
README.mdmentions setting up a Trigger.dev project ID. - Prisma: An ORM (Object-Relational Mapper) used for database access and management.
- Tailwind CSS: A utility-first CSS framework for styling user interfaces.
- Vercel: A platform for frontend developers, used for deployment and hosting.
These integrations form the foundation of the application, enabling a robust and scalable solution. Sources: README.md:60-65, README.md:162-165
On This Page
Browser Automation with BrowserbaseKey Components and FunctionalityBrowserbase Context Creation FlowBrowser Automation Execution FlowEmail Service with ResendKey Components and FunctionalityEmail Sending LogicCaching and Key-Value Store with Upstash RedisKey Components and FunctionalityRedis Client Initialization FlowCloud Storage with AWS S3Key Components and FunctionalityAWS ConfigurationOther Third-Party Integrations