/thaohienhomes/pho-chat-v1

Wiki directory

Browse AI-generated documentation for any repository.

Configuration

Relevant source files

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

The configuration system in pho.chat is primarily managed through environment variables, which allows for easy customization, deployment flexibility, and clean separation from the upstream LobeChat codebase. This approach centralizes all custom settings, reducing merge conflicts during upstream syncs.

Configurations are grouped into logical objects for branding, authentication, payments, and feature flags. A validation function runs at startup to ensure that critical environment variables are set, preventing runtime errors in production. Beyond environment variables, the application also uses structured objects and system prompts to configure agent behaviors, tools, and initial data seeding.

Environment Variable Configuration

The main application configuration is centralized in src/config/customizations.ts. This file reads environment variables and exports them as structured objects.

This diagram illustrates the flow of configuration from environment variables to the application.

Generating architecture diagram...

Sources: src/config/customizations.ts

Branding Configuration

Branding is controlled by the BRANDING_CONFIG object, which allows for customization of the application's name, logo, colors, and links.

Parameter	Environment Variable	Default Value	Description
`appName`	`NEXT_PUBLIC_BRAND_NAME`	`'pho.chat'`	The name of the application.
`appDescription`	`NEXT_PUBLIC_BRAND_DESCRIPTION`	`'Fast, convenient and affordable AI agent platform'`	A short description of the application.
`logoUrl`	`NEXT_PUBLIC_BRAND_LOGO_URL`	`'/logo/logo-full.svg'`	URL for the full logo.
`faviconUrl`	`NEXT_PUBLIC_BRAND_FAVICON_URL`	`'/favicon.ico'`	URL for the favicon.
`primaryColor`	`NEXT_PUBLIC_PRIMARY_COLOR`	`'#FF6B6B'`	The primary color for the UI theme.
`neutralColor`	`NEXT_PUBLIC_NEUTRAL_COLOR`	`'#000000'`	The neutral color for the UI theme.
`websiteUrl`	`NEXT_PUBLIC_WEBSITE_URL`	`'https://pho.chat'`	The main website URL.
`businessEmail`	`NEXT_PUBLIC_BUSINESS_EMAIL`	`'hello@pho.chat'`	Contact email for business inquiries.
`supportEmail`	`NEXT_PUBLIC_SUPPORT_EMAIL`	`'hi@pho.chat'`	Contact email for user support.
`socialLinks.discord`	`NEXT_PUBLIC_DISCORD_URL`	`undefined`	URL for the Discord community.
`socialLinks.github`	`NEXT_PUBLIC_GITHUB_URL`	`undefined`	URL for the GitHub repository.
`socialLinks.twitter`	`NEXT_PUBLIC_TWITTER_URL`	`undefined`	URL for the Twitter profile.
`legalLinks.terms`	`NEXT_PUBLIC_TERMS_URL`	`undefined`	URL for the Terms of Service page.
`legalLinks.privacy`	`NEXT_PUBLIC_PRIVACY_URL`	`undefined`	URL for the Privacy Policy page.
`legalLinks.help`	`NEXT_PUBLIC_HELP_URL`	`undefined`	URL for the help or support page.

Sources: src/config/customizations.ts:15-50

Authentication Configuration

Authentication is managed by the AUTH_CONFIG object. The application primarily uses Clerk for authentication, which can be enabled and configured via environment variables.

Parameter	Environment Variable	Default Value	Description
`provider`	`NEXT_PUBLIC_AUTH_PROVIDER`	`'clerk'`	The selected authentication provider.
`clerk.enabled`	`NEXT_PUBLIC_ENABLE_CLERK_AUTH`	`false`	Enables Clerk authentication. Auto-enabled if `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` exists.
`clerk.publishableKey`	`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	`undefined`	The public-facing key for the Clerk frontend.
`clerk.secretKey`	`CLERK_SECRET_KEY`	`undefined`	The secret key for the Clerk backend.
`clerk.webhookSecret`	`CLERK_WEBHOOK_SECRET`	`undefined`	The secret for verifying Clerk webhooks.
`enableAuthProtection`	`ENABLE_AUTH_PROTECTION`	`false`	If set to `'1'`, enables auth protection.

Sources: src/config/customizations.ts:56-78

Payment Configuration

Payment integration is handled by the PAYMENT_CONFIG object. The system supports Sepay and Polar as payment providers. Sepay has a mockMode that is active if its secret key or merchant ID is not provided.

Parameter	Environment Variable	Default Value	Description
`provider`	`NEXT_PUBLIC_PAYMENT_PROVIDER`	`'sepay'`	The selected payment provider.
`currency`	`NEXT_PUBLIC_PAYMENT_CURRENCY`	`'VND'`	The default currency for payments.
`minAmount`	`NEXT_PUBLIC_MIN_PAYMENT_AMOUNT`	`1000`	The minimum payment amount.
`sepay.enabled`	`NEXT_PUBLIC_USE_SEPAY`	`false`	Enables the Sepay payment provider.
`sepay.mockMode`	N/A	`true` if keys missing	Runs Sepay in mock mode for testing.
`sepay.merchantId`	`SEPAY_MERCHANT_ID`	`undefined`	The merchant ID for Sepay.
`sepay.secretKey`	`SEPAY_SECRET_KEY`	`undefined`	The secret key for Sepay.
`sepay.apiUrl`	`SEPAY_API_URL`	`'https://api.sepay.vn/v1'`	The API endpoint for Sepay.

Sources: src/config/customizations.ts:84-122

Feature Flags

The FEATURE_FLAGS object provides a centralized way to toggle custom features on or off.

Flag	Environment Variable	Default Value	Description
`CLERK_AUTH`	`NEXT_PUBLIC_ENABLE_CLERK_AUTH`	`false`	Toggles Clerk authentication.
`PHO_BRANDING`	`NEXT_PUBLIC_USE_PHO_BRANDING`	`true`	Toggles `pho.chat` specific branding.
`SEPAY_PAYMENT`	`NEXT_PUBLIC_USE_SEPAY`	`false`	Toggles Sepay payment integration.
`COST_OPTIMIZATION`	`COST_OPTIMIZATION_ENABLED`	`false`	Toggles cost optimization features.
`USAGE_TRACKING`	`USAGE_TRACKING_ENABLED`	`false`	Toggles usage tracking.

Sources: src/config/customizations.ts:128-143

Configuration Validation

At startup, the validateCustomizationConfig function checks for the presence of critical environment variables. If any required variables are missing in a production environment, the application will throw an error and fail to start.

This flowchart shows the validation logic.

Generating architecture diagram...

Sources: src/config/customizations.ts:149-173

Desktop Application Configuration

The desktop application, built with Electron, has its own layer of configuration.

Environment File: It uses a .env.desktop file for environment-specific settings, which should be copied to .env for local development.
Build Configuration: The apps/desktop/electron.vite.config.ts file is mentioned but its contents are not provided in the context. However, the apps/desktop/README.md details the build commands for different platforms (mac, win, linux).

Sources: apps/desktop/README.md

Agent & Tool Configuration

The behavior of AI agents and their tools is configured through systemRole prompts, which are detailed instructions embedded in the code.

Local System Tool

The local-system tool's capabilities are defined in src/tools/local-system/systemRole.ts. The systemPrompt string configures the agent to interact with the user's local file system.

Key configuration points include:

User Context: Defines known locations like Desktop, Documents, and Downloads using placeholders ({{desktopPath}}).
Core Capabilities: Lists available tools such as listLocalFiles, readLocalFile, writeFile, searchLocalFiles, renameLocalFile, and moveLocalFiles.
Workflow: Outlines the steps the agent should take to handle a user request.
Tool Usage Guidelines: Provides specific instructions on how to use each tool and its parameters.
Security Considerations: Instructs the agent to confirm destructive actions with the user.
Response Format: Mandates a specific XML-like tag format (<localFile ... />) for any file paths in the response to ensure they are parsed correctly by the UI.

Sources: src/tools/local-system/systemRole.ts

Artifacts Tool

Similarly, the artifacts tool is configured via a systemPrompt in src/tools/artifacts/systemRole.ts. This prompt instructs the agent on when and how to create "artifacts" (e.g., code blocks, documents, diagrams) in a separate UI window.

Key configuration points include:

Criteria: Defines what constitutes a "good artifact" (e.g., substantial, self-contained content) versus what should remain inline.
Instructions: A step-by-step guide for the agent on how to format an artifact using <lobeArtifact> tags with identifier, title, and type attributes.
Content Types: Specifies MIME-like types for different artifacts, such as application/lobe.artifacts.code, text/html, image/svg+xml, and application/lobe.artifacts.mermaid.
Examples: Provides numerous examples of correct and incorrect usage to guide the agent's behavior.

Sources: src/tools/artifacts/systemRole.ts

Data & Seeding Configuration

Bundled Apps Seeding

The application uses a seed script to populate the database with default "bundled apps" (pre-configured agents). The configuration for these apps is defined as an array of NewBundledApp objects.

Each app configuration includes:

id, title, description, avatar, category, and tags.
systemRole: The master prompt defining the agent's personality and skills.
config: The default LLM model, provider, and parameters (temperature, top_p).
chatConfig: UI-related settings like displayMode.
openingMessage and openingQuestions: Content to start a conversation.

// Example of a bundled app configuration
{
    avatar: '🔍',
    backgroundColor: '#10b981',
    category: 'development',
    config: {
      model: 'claude-3-5-sonnet-20241022',
      params: {
        temperature: 0.3,
      },
      provider: 'anthropic',
    },
    description:
      'Get detailed code reviews with best practices, security checks, and performance optimization suggestions.',
    id: 'code-reviewer',
    isFeatured: true,
    isPublic: true,
    openingMessage: "Ready to review your code! Share the code you'd like me to analyze.",
    systemRole: `You are an expert code reviewer...`,
    tags: ['development', 'productivity', 'quality'],
    title: 'Code Reviewer',
}

Sources: scripts/seedBundledApps/index.ts:38-66

Data Import Configuration

The application supports importing user data from a JSON file. The structure of this configuration file is revealed in test fixtures. The data is versioned and contains arrays for sessionGroups, sessions, topics, and messages. During import, the system maps clientId from the file to the new database IDs to maintain relationships between entities.

For example, a session from the import file can be linked to a session group by its group property, which corresponds to the id of a session group in the same file.

Sources: packages/database/src/repositories/dataImporter/deprecated/tests/index.test.ts:208-265, packages/database/src/repositories/dataImporter/deprecated/tests/fixtures/messages.json

S3 CORS Configuration

File uploads require a specific CORS (Cross-Origin Resource Sharing) configuration on the S3 bucket. This is not an application code configuration but a critical infrastructure setting. The required configuration allows GET, PUT, POST, DELETE, and HEAD methods from specified origins like https://pho.chat and http://localhost:3000.

{
  "CORSRules": [{
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedOrigins": [
      "https://pho.chat",
      "http://localhost:3000",
      "http://localhost:3015"
    ],
    "ExposeHeaders": ["ETag", "x-amz-version-id"],
    "MaxAgeSeconds": 3000
  }]
}

Sources: FILE_UPLOAD_EXECUTIVE_SUMMARY.md

Configuration

Relevant source files

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

Environment Variable Configuration

The main application configuration is centralized in src/config/customizations.ts. This file reads environment variables and exports them as structured objects.

This diagram illustrates the flow of configuration from environment variables to the application.

Generating architecture diagram...

Sources: src/config/customizations.ts

Branding Configuration

Branding is controlled by the BRANDING_CONFIG object, which allows for customization of the application's name, logo, colors, and links.

Parameter	Environment Variable	Default Value	Description
`appName`	`NEXT_PUBLIC_BRAND_NAME`	`'pho.chat'`	The name of the application.
`appDescription`	`NEXT_PUBLIC_BRAND_DESCRIPTION`	`'Fast, convenient and affordable AI agent platform'`	A short description of the application.
`logoUrl`	`NEXT_PUBLIC_BRAND_LOGO_URL`	`'/logo/logo-full.svg'`	URL for the full logo.
`faviconUrl`	`NEXT_PUBLIC_BRAND_FAVICON_URL`	`'/favicon.ico'`	URL for the favicon.
`primaryColor`	`NEXT_PUBLIC_PRIMARY_COLOR`	`'#FF6B6B'`	The primary color for the UI theme.
`neutralColor`	`NEXT_PUBLIC_NEUTRAL_COLOR`	`'#000000'`	The neutral color for the UI theme.
`websiteUrl`	`NEXT_PUBLIC_WEBSITE_URL`	`'https://pho.chat'`	The main website URL.
`businessEmail`	`NEXT_PUBLIC_BUSINESS_EMAIL`	`'hello@pho.chat'`	Contact email for business inquiries.
`supportEmail`	`NEXT_PUBLIC_SUPPORT_EMAIL`	`'hi@pho.chat'`	Contact email for user support.
`socialLinks.discord`	`NEXT_PUBLIC_DISCORD_URL`	`undefined`	URL for the Discord community.
`socialLinks.github`	`NEXT_PUBLIC_GITHUB_URL`	`undefined`	URL for the GitHub repository.
`socialLinks.twitter`	`NEXT_PUBLIC_TWITTER_URL`	`undefined`	URL for the Twitter profile.
`legalLinks.terms`	`NEXT_PUBLIC_TERMS_URL`	`undefined`	URL for the Terms of Service page.
`legalLinks.privacy`	`NEXT_PUBLIC_PRIVACY_URL`	`undefined`	URL for the Privacy Policy page.
`legalLinks.help`	`NEXT_PUBLIC_HELP_URL`	`undefined`	URL for the help or support page.

Sources: src/config/customizations.ts:15-50

Authentication Configuration

Authentication is managed by the AUTH_CONFIG object. The application primarily uses Clerk for authentication, which can be enabled and configured via environment variables.

Parameter	Environment Variable	Default Value	Description
`provider`	`NEXT_PUBLIC_AUTH_PROVIDER`	`'clerk'`	The selected authentication provider.
`clerk.enabled`	`NEXT_PUBLIC_ENABLE_CLERK_AUTH`	`false`	Enables Clerk authentication. Auto-enabled if `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` exists.
`clerk.publishableKey`	`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	`undefined`	The public-facing key for the Clerk frontend.
`clerk.secretKey`	`CLERK_SECRET_KEY`	`undefined`	The secret key for the Clerk backend.
`clerk.webhookSecret`	`CLERK_WEBHOOK_SECRET`	`undefined`	The secret for verifying Clerk webhooks.
`enableAuthProtection`	`ENABLE_AUTH_PROTECTION`	`false`	If set to `'1'`, enables auth protection.

Sources: src/config/customizations.ts:56-78

Payment Configuration

Parameter	Environment Variable	Default Value	Description
`provider`	`NEXT_PUBLIC_PAYMENT_PROVIDER`	`'sepay'`	The selected payment provider.
`currency`	`NEXT_PUBLIC_PAYMENT_CURRENCY`	`'VND'`	The default currency for payments.
`minAmount`	`NEXT_PUBLIC_MIN_PAYMENT_AMOUNT`	`1000`	The minimum payment amount.
`sepay.enabled`	`NEXT_PUBLIC_USE_SEPAY`	`false`	Enables the Sepay payment provider.
`sepay.mockMode`	N/A	`true` if keys missing	Runs Sepay in mock mode for testing.
`sepay.merchantId`	`SEPAY_MERCHANT_ID`	`undefined`	The merchant ID for Sepay.
`sepay.secretKey`	`SEPAY_SECRET_KEY`	`undefined`	The secret key for Sepay.
`sepay.apiUrl`	`SEPAY_API_URL`	`'https://api.sepay.vn/v1'`	The API endpoint for Sepay.

Sources: src/config/customizations.ts:84-122

Feature Flags

The FEATURE_FLAGS object provides a centralized way to toggle custom features on or off.

Flag	Environment Variable	Default Value	Description
`CLERK_AUTH`	`NEXT_PUBLIC_ENABLE_CLERK_AUTH`	`false`	Toggles Clerk authentication.
`PHO_BRANDING`	`NEXT_PUBLIC_USE_PHO_BRANDING`	`true`	Toggles `pho.chat` specific branding.
`SEPAY_PAYMENT`	`NEXT_PUBLIC_USE_SEPAY`	`false`	Toggles Sepay payment integration.
`COST_OPTIMIZATION`	`COST_OPTIMIZATION_ENABLED`	`false`	Toggles cost optimization features.
`USAGE_TRACKING`	`USAGE_TRACKING_ENABLED`	`false`	Toggles usage tracking.

Sources: src/config/customizations.ts:128-143

Configuration Validation

This flowchart shows the validation logic.

Generating architecture diagram...

Sources: src/config/customizations.ts:149-173

Desktop Application Configuration

The desktop application, built with Electron, has its own layer of configuration.

Environment File: It uses a .env.desktop file for environment-specific settings, which should be copied to .env for local development.
Build Configuration: The apps/desktop/electron.vite.config.ts file is mentioned but its contents are not provided in the context. However, the apps/desktop/README.md details the build commands for different platforms (mac, win, linux).

Sources: apps/desktop/README.md

Agent & Tool Configuration

The behavior of AI agents and their tools is configured through systemRole prompts, which are detailed instructions embedded in the code.

Local System Tool

The local-system tool's capabilities are defined in src/tools/local-system/systemRole.ts. The systemPrompt string configures the agent to interact with the user's local file system.

Key configuration points include:

User Context: Defines known locations like Desktop, Documents, and Downloads using placeholders ({{desktopPath}}).
Core Capabilities: Lists available tools such as listLocalFiles, readLocalFile, writeFile, searchLocalFiles, renameLocalFile, and moveLocalFiles.
Workflow: Outlines the steps the agent should take to handle a user request.
Tool Usage Guidelines: Provides specific instructions on how to use each tool and its parameters.
Security Considerations: Instructs the agent to confirm destructive actions with the user.
Response Format: Mandates a specific XML-like tag format (<localFile ... />) for any file paths in the response to ensure they are parsed correctly by the UI.

Sources: src/tools/local-system/systemRole.ts

Artifacts Tool

Key configuration points include:

Criteria: Defines what constitutes a "good artifact" (e.g., substantial, self-contained content) versus what should remain inline.
Instructions: A step-by-step guide for the agent on how to format an artifact using <lobeArtifact> tags with identifier, title, and type attributes.
Content Types: Specifies MIME-like types for different artifacts, such as application/lobe.artifacts.code, text/html, image/svg+xml, and application/lobe.artifacts.mermaid.
Examples: Provides numerous examples of correct and incorrect usage to guide the agent's behavior.

Sources: src/tools/artifacts/systemRole.ts

Data & Seeding Configuration

Bundled Apps Seeding

The application uses a seed script to populate the database with default "bundled apps" (pre-configured agents). The configuration for these apps is defined as an array of NewBundledApp objects.

Each app configuration includes:

id, title, description, avatar, category, and tags.
systemRole: The master prompt defining the agent's personality and skills.
config: The default LLM model, provider, and parameters (temperature, top_p).
chatConfig: UI-related settings like displayMode.
openingMessage and openingQuestions: Content to start a conversation.

// Example of a bundled app configuration
{
    avatar: '🔍',
    backgroundColor: '#10b981',
    category: 'development',
    config: {
      model: 'claude-3-5-sonnet-20241022',
      params: {
        temperature: 0.3,
      },
      provider: 'anthropic',
    },
    description:
      'Get detailed code reviews with best practices, security checks, and performance optimization suggestions.',
    id: 'code-reviewer',
    isFeatured: true,
    isPublic: true,
    openingMessage: "Ready to review your code! Share the code you'd like me to analyze.",
    systemRole: `You are an expert code reviewer...`,
    tags: ['development', 'productivity', 'quality'],
    title: 'Code Reviewer',
}

Sources: scripts/seedBundledApps/index.ts:38-66

Data Import Configuration

For example, a session from the import file can be linked to a session group by its group property, which corresponds to the id of a session group in the same file.

Sources: packages/database/src/repositories/dataImporter/deprecated/tests/index.test.ts:208-265, packages/database/src/repositories/dataImporter/deprecated/tests/fixtures/messages.json

S3 CORS Configuration

{
  "CORSRules": [{
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedOrigins": [
      "https://pho.chat",
      "http://localhost:3000",
      "http://localhost:3015"
    ],
    "ExposeHeaders": ["ETag", "x-amz-version-id"],
    "MaxAgeSeconds": 3000
  }]
}

Sources: FILE_UPLOAD_EXECUTIVE_SUMMARY.md