System Architecture
Core Features
Data Management
Frontend Components
Extensibility
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.
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.
BrowserbaseContext records in the database, ensuring each organization has a persistent browser context for automations. The getOrCreateOrgContext method handles the creation and retrieval of these contexts, including a retry mechanism for concurrent creation attempts.createSessionWithContext establishes a new browser session linked to an organization's context, providing a liveViewUrl for real-time monitoring. closeSession is used to terminate sessions.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.db.browserAutomation).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.The getOrCreateOrgContext method ensures that a unique Browserbase context exists for each organization, handling potential race conditions during creation.
The runBrowserAutomation method orchestrates the full lifecycle of a browser automation, from session creation to execution and cleanup.
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.
RESEND_API_KEY from environment variables. If the API key is missing, the client is null, and sendEmail will throw an error.sendEmail Function:
to, subject, react (for React-based email templates), marketing, system, test, cc, scheduledAt, and attachments.from and to addresses based on marketing, system, or test flags and corresponding environment variables (RESEND_FROM_MARKETING, RESEND_FROM_SYSTEM, RESEND_FROM_DEFAULT, RESEND_TO_TEST).EmailAttachment objects into the format expected by the Resend SDK.Sources: apps/api/src/email/resend.ts:1-74
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.
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 supports get, set, and del operations with optional expiration.assistantChatRedisClient: This is the exported client instance. It is conditionally initialized:
UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN environment variables are present, it uses the @upstash/redis SDK.InMemoryRedis instance.AssistantChatService to save and clear chat history.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.
S3Client: An instance of the AWS SDK S3 client, configured with region and credentials.bucketName: Configured via APP_AWS_BUCKET_NAME environment variable, defaulting to comp-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, including region, accessKeyId, secretAccessKey, and bucketName. It uses Zod for schema validation of these environment variables at application startup.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
The project's README.md (README.md) also highlights several other key technologies and platforms that contribute to its overall architecture and functionality.
README.md mentions setting up a Trigger.dev project ID.These integrations form the foundation of the application, enabling a robust and scalable solution. Sources: README.md:60-65, README.md:162-165