Customization

This guide explains the different customization areas in your Pika project and how to use them effectively.

Overview

Pika Framework provides several designated areas where you can add your custom code without worrying about it being overwritten during framework updates. These areas are protected from sync operations and are designed to be your primary extension points.

Central Configuration

Project Configuration

Location: pika-config.ts (root directory)

Purpose: Central configuration file for project names and settings used across your Pika project.

What to customize here:

• Project Names: Update the project names for both Pika backend and Pika Chat frontend stacks
• Resource Naming: All AWS resources will use these names for consistent naming across your infrastructure
• Stack Descriptions: Stack descriptions are automatically generated from these names

Example customization:

export const pikaConfig: PikaConfig = {
    pika: {
        projNameL: '**   mycompany**', // All lowercase: mycompany
        projNameKebabCase: 'mycompany', // Kebab case: mycompany
        projNameTitleCase: 'MyCompany', // Title case: MyCompany
        projNameCamel: 'mycompany', // Camel case: mycompany
        projNameHuman: 'My Company' // Human readable: My Company
    },
    pikaChat: {
        projNameL: 'mycompanychat', // All lowercase: mycompanychat
        projNameKebabCase: 'mycompany-chat', // Kebab case: mycompany-chat
        projNameTitleCase: 'MyCompanyChat', // Title case: MyCompanyChat
        projNameCamel: 'myCompanyChat', // Camel case: myCompanyChat
        projNameHuman: 'My Company Chat' // Human readable: My Company Chat
    }
};

Site Features Configuration

Location: pika-config.ts (root directory)

Purpose: Configure site-wide features that affect the behavior of your Pika chat application across all users and chat apps.

Home Page Configuration

Configure the home page experience including title, welcome message, and chat app links visibility.

Configuration Example:

export const pikaConfig: PikaConfig = {
    pika: {
        // ... project names configuration
    },
    pikaChat: {
        // ... project names configuration
    },
    siteFeatures: {
        homePage: {
            // Optional: Custom title for the home page
            homePageTitle: 'Welcome to My Company Chat',

                // Optional: Custom welcome message
                welcomeMessage: 'Get started by selecting a chat app below or asking me anything!',

                // Optional: Configure which users see links to which chat apps
                linksToChatApps: {
                    userChatAppRules: [
                        // External users can only see links to external chat apps
                        {
                            userTypes: ['external-user'],
                            chatAppUserTypes: ['external-user']
                        },
                        // Internal users can see links to internal and external chat apps
                        {
                            userTypes: ['internal-user'],
                            chatAppUserTypes: ['internal-user', 'external-user']
                        }
                    ]
                }
            }
        }
    };
    ```

**Key Configuration Options:**

- **`homePageTitle`** (optional): Custom title for the home page. If not provided, a default title will be used.
- **`welcomeMessage`** (optional): Custom welcome message displayed on the home page. If not provided, a default message will be used.
- **`linksToChatApps`** (optional): Configuration for showing chat app links to users
    - **`userChatAppRules`**: Array of rules that define which users can see which chat apps
        - **`userTypes`**: Array of user types that this rule applies to
        - **`chatAppUserTypes`**: Array of chat app user types that users matching this rule can see

**How It Works:**

1. When a user visits the chat app home page, the system checks their user type
2. The system finds all rules where the user's type matches the `userTypes` array
3. For matching rules, the user will see links to chat apps whose user types are listed in `chatAppUserTypes`
4. If no rules match the user, they won't see any chat app links on the home page

**Example Scenarios:**

```js
// Scenario 1: Simple home page customization with basic chat app links
siteFeatures: {
    homePage: {
        homePageTitle: "Customer Support Portal",
        welcomeMessage: "Welcome! How can we help you today?",
        linksToChatApps: {
            userChatAppRules: [
                {
                    userTypes: ['external-user'],
                    chatAppUserTypes: ['external-user']
                },
                {
                    userTypes: ['internal-user'],
                    chatAppUserTypes: ['internal-user', 'external-user']
                }
            ]
        }
    }
}

// Scenario 2: Just custom title and message without chat app links
siteFeatures: {
    homePage: {
        homePageTitle: "AI Assistant",
        welcomeMessage: "Ask me anything to get started!"
    }
}

Notes:

• All home page configuration options are optional
• If homePageTitle is not provided, a default title will be used
• If welcomeMessage is not provided, a default welcome message will be used
• For chat app links feature: You must have at least one rule to enable showing chat app links :::

Chat App Features Configuration

Configuration Example:

export const pikaConfig: PikaConfig = {
    // ... project names configuration
    siteFeatures: {
        // ... home page configuration

        // Show AI reasoning traces to users
        traces: {
            featureId: 'traces',
            enabled: true,
            userTypes: ['internal-user'], // Only show to internal users
            detailedTraces: {
                enabled: true,
                userTypes: ['internal-user'],
                userRoles: ['pika:content-admin'] // Only admins see detailed traces
            }
        },

        // Verify and improve AI response quality
        verifyResponse: {
            featureId: 'verifyResponse',
            enabled: true,
            autoRepromptThreshold: 'C', // Automatically improve responses graded C or lower
            userTypes: ['internal-user', 'external-user'] // REQUIRED: Must specify access
        },

        // Display disclaimer notices to users
        chatDisclaimerNotice: {
            featureId: 'chatDisclaimerNotice',
            enabled: true,
            notice: 'This AI-powered chat is here to help, but it may not always be accurate. For urgent or complex issues, please contact customer support.'
        },

  </TabPanel>
  <TabPanel name="UI Features">
    ```js
    siteFeatures: {
        // Enable logout functionality
        logout: {
            featureId: 'logout',
            enabled: true,
            userTypes: ['internal-user', 'external-user'] // REQUIRED: Must specify access
        },

        // Enable file upload capabilities
        fileUpload: {
            featureId: 'fileUpload',
            enabled: true,
            mimeTypesAllowed: ['image/*', 'application/pdf', 'text/plain', '.docx', '.xlsx']
        },

        // Enable chat suggestions
        suggestions: {
            featureId: 'suggestions',
            enabled: true,
            suggestions: [], // Empty means chat apps define their own
            maxToShow: 5,
            randomize: false,
            randomizeAfter: 0
        },

        // Enable input field labels
        promptInputFieldLabel: {
            featureId: 'promptInputFieldLabel',
            enabled: true,
            promptInputFieldLabel: 'Ready to chat'
        },

        // Enable UI customizations
        uiCustomization: {
            featureId: 'uiCustomization',
            enabled: true,
            showUserRegionInLeftNav: false,
            showChatHistoryInStandaloneMode: true
        },

        // Enable AI-driven UI tags for dynamic widget rendering
        tags: {
            enabled: true,
            tagsEnabled: [
                { tag: 'chart', scope: 'builtin' },
                { tag: 'table', scope: 'builtin' }
            ],
            tagsProhibited: [
                // Define tags that should never be used
            ]
        }
    }
};

Feature Overview:

Key Principles:

• Site-Level Enablement: Features disabled here cannot be enabled by chat apps or admin overrides
• Chat App Restrictions: Chat apps can only make features more restrictive than site level and override feature settings
• Admin Override Power: Admin overrides can completely replace chat app settings (but not enable site-disabled features)
• Feature Hierarchy: Site → Chat App → Admin Override → User access control flow

Access Control:

• User Types: internal-user (employees) vs external-user (customers)
• User Roles: Fine-grained permissions like pika:content-admin, pika:site-admin
• Access Rules: Use userTypes, userRoles, and applyRulesAs for precise control

Advanced Features Configuration

export const pikaConfig: PikaConfig = {
    // ... other configuration
    siteFeatures: {
        userDataOverrides: {
            enabled: true,

            // Optional: Specify which user types can use this feature (defaults to ['internal-user'])
            userTypesAllowed: ['internal-user', 'admin'],

            // Optional: Customize UI text
            menuItemTitle: 'Switch Account Context',
            dialogTitle: 'Account Override',
            dialogDescription: 'Select the account context to use for this chat app.',

            // Optional: Force users to provide overrides if missing required data
            promptUserIfAnyOfTheseCustomUserDataAttributesAreMissing: ['accountId', 'accountType']
        }
    }
};

// In the chat app definition
features: {
    userDataOverride: {
        featureId: 'userDataOverride',
        enabled: false // Disable for this chat app
    }
}

export const pikaConfig: PikaConfig = {
    // ... other configuration
    siteFeatures: {
        contentAdmin: {
            enabled: true
        }
    }
};

export const pikaConfig: PikaConfig = {
    // ... other configuration
    siteFeatures: {
        siteAdmin: {
            websiteEnabled: true
        }
    }
};

// First, enable the entity feature in pika-config.ts
siteFeatures: {
    entity: {
        enabled: true,
        attributeName: "accountId",
        searchPlaceholderText: "Search for an account...",
        displayNameSingular: "Account",
        displayNamePlural: "Accounts",
        tableColumnHeaderTitle: "Account ID"
    }
}

// Example: Restrict a chat app to specific customer accounts
const customerSupportOverride = {
    enabled: true,
    exclusiveExternalAccessControl: ['account_enterprise_1', 'account_enterprise_2', 'account_premium_gold'],
    exclusiveInternalAccessControl: ['support_department', 'customer_success']
};

Customization Areas

1. Custom Message Tag Renderers

Location: apps/pika-chat/src/lib/client/features/chat/message-segments/custom-components/

Purpose: Add custom renderers for XML tags in LLM responses for inline visual components and metadata handlers for processing non-visual tags.

What to put here:

• Custom Svelte components for rendering XML tags (e.g., <order>, <dialog>, <code>)
• Metadata handlers for processing XML tags that don't render visually (e.g., <some-command>)
• TypeScript files with supporting logic
• Custom UI components for displaying structured data from LLMs

Example use cases:

• Custom data visualization components (charts, graphs, tables)
• Interactive widgets (forms, buttons, controls)
• File display components (PDFs, documents, media)
• Business-specific data renderers (customer cards, product displays, interactive elements)
• Analytics and telemetry handlers

2. Authentication

Location: apps/pika-chat/src/lib/server/auth-provider/

Purpose: Implement custom authentication flows for your specific SSO or auth provider.

What to put here:

• Authentication provider implementation
• OAuth flow handlers
• SSO integration logic
• Custom user data types

Example use cases:

• Company SSO integration
• Custom OAuth providers
• Multi-tenant authentication
• Role-based access control

3. Custom Web Applications

Location: apps/custom/

Purpose: Add entirely new web applications to your Pika project.

What to put here:

• Complete SvelteKit applications
• Admin dashboards
• Customer portals
• Any additional web interfaces

Example use cases:

• Admin panel for managing users and settings
• Customer dashboard for viewing analytics
• Internal tools and utilities
• Separate applications for different user types

4. Custom Services

Location: services/custom/

Purpose: Add new backend services and API endpoints.

What to put here:

• New API services
• Background job processors
• Data processing pipelines
• Integration services

Example use cases:

• Payment processing services
• Email notification services
• Data analytics services
• Third-party integrations (CRM, marketing tools, etc.)

5. Stack Definition Files

Locations:

• apps/pika-chat/infra/bin/pika-chat.ts - Chat application AWS CDK stack
• services/pika/bin/pika.ts - Service infrastructure AWS CDK stack

Purpose: Define your AWS infrastructure and deployment configuration.

What to customize here:

• VPC configurations
• Account IDs and regions
• Custom AWS resources
• Environment-specific settings

Advanced Features

Configuration Files

Environment Configuration

Files: .env, .env.local, .env.*

Purpose: Store environment-specific configuration like API keys, database URLs, and feature flags.

Pika Configuration

File: pika-config.ts

Purpose: Central configuration for project names and settings used across all stacks and resources.

Key Features:

• Type-safe configuration with TypeScript
• Centralized project naming for consistent resource naming
• Automatically imported by all stack definition files
• Single source of truth for project identity

Sync Configuration

.pika-sync.json

This file tracks your sync status and allows you to customize which files are protected from updates.

Key sections:

• protectedAreas: Framework-managed list of protected files (don't edit this)
• userProtectedAreas: Additional files you want to protect
• userUnprotectedAreas: Default protected files you want to allow updates for

Example configuration:

{
    "userProtectedAreas": ["my-custom-config.ts", "apps/my-custom-app/"],
    "userUnprotectedAreas": ["apps/pika-chat/infra/bin/pika-chat.ts", "services/pika/bin/pika.ts"]
}

Best Practices

1. Use Designated Areas

Always place your custom code in the designated customization areas. Files outside these areas may be overwritten during framework updates.

2. Configure Project Names First

Before customizing anything else, update the project names in pika-config.ts to match your organization and project requirements. This ensures consistent naming across all AWS resources.

3. Keep Customizations Focused

Each customization area has a specific purpose. Use the appropriate area for your custom code:

• Project names and settings → pika-config.ts
• UI components → Custom Components
• Authentication logic → Custom Authentication
• New applications → Custom Web Applications
• Backend services → Custom Services
• Infrastructure changes → Stack Definition Files

4. Version Control

Initialize git in your project and commit your customizations regularly:

git init
git add .
git commit -m "Initial commit with customizations"

5. Test After Updates

After running pika sync, always test your customizations to ensure they still work correctly.

6. Document Your Changes

Keep documentation of your customizations, especially for complex changes to stack definitions or custom services.

Framework Updates

When you run pika sync, the framework will:

1. Update framework files with the latest changes
2. Preserve all files in protected areas (including pika-config.ts)
3. Merge your userProtectedAreas with the default protected areas
4. Remove files in userUnprotectedAreas from protection

This ensures your customizations are preserved while you receive the latest framework improvements.

Getting Help

• Framework Documentation: https://github.com/rithum/pika
• AWS CDK Documentation: https://docs.aws.amazon.com/cdk/
• SvelteKit Documentation: https://kit.svelte.dev/
• Svelte Documentation: https://svelte.dev/docs

Next Steps

1. Update project names in pika-config.ts to match your organization
2. Explore the sample code in each customization area to understand the patterns
3. Start with small customizations like adding a custom component
4. Gradually build up to more complex customizations
5. Test your changes thoroughly before deploying to production
6. Keep your framework updated with regular sync operations