Project Structure

This guide explains the structure of your Pika application and what each component does.

Overview

Your Pika application follows a monorepo structure that separates concerns and enables easy customization. Here's the high-level structure:

my-pika-app/
├── apps/                   # Frontend web applications stacks
├── services/               # Backend service stacks
├── packages/               # Shared packages
├── docs/                   # Documentation
├── pika-config.ts          # Project configuration
├── .pika-sync.json         # Sync configuration
├── package.json            # Root package.json
└── pnpm-workspace.yaml     # Workspace configuration

Applications (/apps)

The apps directory contains all frontend application stacks in your Pika project.

Main Chat Application (/apps/pika-chat)

The core chat interface that can render any chat application in your platform.

Structure:

apps/pika-chat/
├── src/
│   ├── lib/
│   │   ├── client/         # Client-side code
│   │   │   └── features/
│   │   │       └── chat/
│   │   │           └── markdown-message-renderer/
│   │   │               └── custom-markdown-tag-components/  # Your custom components
│   │   └── server/         # Server-side code
│   │       └── auth-provider/  # Authentication system
│   ├── routes/             # SvelteKit routes
│   └── app.html            # Main HTML template
├── infra/                  # AWS CDK infrastructure
│   └── lib/
│       └── stacks/
│           └── custom-stack-defs.ts  # Your custom stack configuration
├── static/                 # Static assets
└── package.json

Customization Areas:

Sample Applications (/apps/samples)

Example applications that demonstrate Pika's capabilities.

Enterprise Site (/apps/samples/enterprise-site)

A sample web application that demonstrates embedded chat mode.

Purpose:

• Shows how to embed Pika chat in existing applications
• Demonstrates iframe integration
• Example of a complete web application

Services (/services)

The services directory contains all backend service stacks.

Core Pika Service (/services/pika)

The main backend service that provides chat app management, agent management, tool orchestration and agent invocation (called from front end).

Structure:

services/pika/
├── src/                    # Source code
├── lib/                    # Library code
│   └── stacks/
│       └── custom-stack-defs.ts  # Your custom stack configuration
├── bin/                    # CDK app entry points
└── package.json

Customization Areas:

• Infrastructure: lib/stacks/custom-stack-defs.ts; use if need to add resources to the stack (shouldn't be needed in default cases)

Custom Services (/services/custom)

Your custom backend services and API endpoints.

Example Use Cases:

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

Sample Services (/services/samples)

Example services that demonstrate how to build agents and tools.

Weather Service (/services/samples/weather)

A complete example of how to define a chat application and agent.

What it demonstrates:

• Agent definition with instructions
• Tool implementation (weather API integration)
• AWS CDK stack for deployment
• Complete chat application lifecycle

Structure:

services/samples/weather/
├── src/                    # Source code
├── lambda/                 # Lambda function code
├── lib/                    # Library code
├── bin/                    # CDK app entry points
└── package.json

Shared Packages (/packages)

The packages directory contains shared code and utilities used across multiple applications and services.

Common packages:

• Type definitions - Shared TypeScript interfaces
• Utility functions - Common helper functions
• Configuration - Shared configuration utilities
• Testing utilities - Common test helpers

Pika Shared Types Package

The core Pika types (such as ChatApp, ChatAgent, ChatUser, AuthenticatedUser, and others) are published to npm as a standalone package. This allows external applications and services to use Pika's type definitions without importing the entire framework.

pnpm add -d pika-shared

What's included:

• Core Types: ChatApp, ChatAgent, ChatUser, AuthenticatedUser
• Feature Types: Type definitions for all Pika features
• API Types: Request/response types for Pika API endpoints
• Utility Types: Helper types used throughout the framework

Configuration Files

Project Configuration (pika-config.ts)

The central configuration file for your entire Pika project.

Purpose:

• Define project names for all stacks and resources
• Centralized configuration management
• Type-safe configuration with TypeScript

Example:

export const pikaConfig: PikaConfig = {
    pika: {
        projNameL: 'mycompany',
        projNameKebabCase: 'mycompany',
        projNameTitleCase: 'MyCompany',
        projNameCamel: 'mycompany',
        projNameHuman: 'My Company'
    },
    pikaChat: {
        projNameL: 'mycompanychat',
        projNameKebabCase: 'mycompany-chat',
        projNameTitleCase: 'MyCompanyChat',
        projNameCamel: 'myCompanyChat',
        projNameHuman: 'My Company Chat'
    }
};

Sync Configuration (.pika-sync.json)

Tracks sync status and allows you to customize which files are protected from framework updates.

Key sections:

• protectedAreas - Framework-managed list of protected files
• userProtectedAreas - Additional files you want to protect
• userUnprotectedAreas - Default protected files you want to allow updates for

Example:

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

Workspace Configuration (pnpm-workspace.yaml)

Defines the monorepo workspace structure for pnpm.

Content:

packages:
    - 'apps/*'
    - 'services/*'
    - 'packages/*'

Protected Areas

Pika Framework automatically protects certain areas from being overwritten during sync operations:

Default Protected Areas

Custom Protection

You can add additional protected areas by editing .pika-sync.json:

{
    "userProtectedAreas": ["my-custom-file.ts", "apps/my-custom-app/", "services/my-custom-service/"]
}

Key Customization Points

Next Steps

Now that you understand the project structure:

1. Configure your project - Update pika-config.ts with your project names
2. Learn about customization - Read the Customization Guide
3. Set up authentication - Follow the Authentication Setup
4. Deploy your services - Check out Local Development or AWS Deployment

Ready to start customizing? Check out the Customization Guide to learn how to add your own features!