alezmad/whyrating
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: whyrating - initial project from turbostarter boilerplate

Browse Source
This commit is contained in:
Alejandro Gutiérrez
2026-02-04 01:54:52 +01:00
commit 5cdc07cd39
1618 changed files with 338230 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
.context/turbostarter-framework-context/sections/ai/docs/agents.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: Agents
description: Build powerful, autonomous AI agents capable of performing complex tasks within your web and mobile applications.
url: /ai/docs/agents
---
# Agents
<Callout title="Agents are coming soon!">
This feature is currently under development and will be
available in a future release.
[See roadmap](https://github.com/orgs/turbostarter/projects/1)
</Callout>
The AI Agents demo will showcase how to create intelligent, autonomous agents capable of executing complex tasks within your web and mobile applications.
These agents will leverage advanced AI techniques to interact with users, tools, and data sources.
## Features
<Cards>
<Card title="Cross-platform">
Design agents once and deploy them seamlessly across multiple platforms
including React, React Native, Expo, and Next.js through a unified
architecture.
</Card>
<Card title="Memory">
Implement sophisticated context retention that allows agents to maintain
state and recall critical information across conversations and devices with
perfect continuity.
</Card>
<Card title="Function calling">
Enable agents to take meaningful actions by integrating with external tools,
accessing APIs, and executing functions dynamically within secure,
controlled environments.
</Card>
<Card title="MCP integration">
Leverage the [Model Context
Protocol](https://modelcontextprotocol.io/introduction) to standardize
context delivery between agents and Large Language Models (LLMs). This
enables frictionless connections to diverse data sources and tools,
dramatically enhancing agent capabilities.
</Card>
<Card title="Agentic workflows">
Orchestrate complex workflows combining Retrieval-Augmented Generation
(RAG), tool utilization, and MCP server interactions to solve sophisticated
tasks that previously required human intervention.
</Card>
</Cards>
Stay tuned for the release of this exciting functionality!

104
.context/turbostarter-framework-context/sections/ai/docs/anthropic.md Normal file
View File

@@ -0,0 +1,104 @@
---
title: Anthropic
description: Setup Anthropic provider and learn how to use it in the starter kit.
url: /ai/docs/anthropic
---
# Anthropic
The [Anthropic](https://www.anthropic.com) provider integrates Anthropic's powerful Claude models into your application through the AI SDK, with an emphasis on safety, helpfulness, and natural interactions.
![Anthropic](/images/docs/ai/providers/anthropic.png)
## Setup
<Steps>
<Step>
### Generate API Key
Visit the [Anthropic Console](https://console.anthropic.com/) to create an account and generate a new API key for your project.
</Step>
<Step>
### Add API Key to Environment
Add your generated API key to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
ANTHROPIC_API_KEY=your-api-key
```
</Step>
<Step>
### Configure Provider (Optional)
The starter kit automatically uses the `ANTHROPIC_API_KEY` environment variable. For advanced configurations (such as proxies or custom headers), refer to the [AI SDK Anthropic documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#provider-instance).
</Step>
</Steps>
## Features
<Cards>
<Card title="Language Models" href="https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#language-models">
Leverage Anthropic's state-of-the-art Claude models for sophisticated
conversational AI, creative text generation, in-depth analysis, and more
through the intuitive Messages API.
</Card>
<Card title="Image Input / Vision" href="https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#image-input">
Enable models to understand and process image inputs alongside text for
multimodal applications.
</Card>
<Card title="Tool Usage / Function Calling" href="https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#tool-usage">
Allow models to interact with external tools and APIs to perform actions and
retrieve real-time information.
</Card>
<Card title="Object Generation" href="https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#object-generation">
Create structured data outputs (like JSON) from natural language prompts,
streamlining the integration of AI capabilities with your existing systems.
</Card>
<Card title="Reasoning" href="https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#reasoning">
Access detailed insights into the model's thought process, enhancing
transparency, debuggability, and trust in AI-generated responses.
</Card>
<Card title="Computer Use" href="https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic#computer-use">
(Experimental) Allow models to directly interact with computer desktop
environments to complete complex, multi-step tasks autonomously.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="AI Chatbot">
Craft intelligent, context-aware chatbots capable of nuanced conversations
and sophisticated task completion. Experience this capability in our [Chat
Demo](/ai/docs/chat).
</Card>
<Card title="Content Generation & Summarization">
Generate high-quality text for various purposes, or summarize long documents
and conversations accurately.
</Card>
<Card title="Data Extraction & Analysis">
Extract structured information from unstructured text or analyze complex
data sets combined with visual inputs for comprehensive insights.
</Card>
<Card title="Automated Workflows">
Seamlessly integrate Claude models with your existing tools via function
calling to automate complex business processes and tasks. Explore
[Agents](/ai/docs/agents) for advanced implementation options.
</Card>
</Cards>
## Links
* [Anthropic Website](https://www.anthropic.com)
* [Anthropic Documentation](https://docs.anthropic.com)
* [AI SDK - Anthropic Provider Docs](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic)

52
.context/turbostarter-framework-context/sections/ai/docs/api.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: API
description: Overview of the API service in TurboStarter AI, including its architecture, technology stack, and core functionalities.
url: /ai/docs/api
---
# API
The API service acts as the central hub for all backend logic within TurboStarter AI. It handles interactions with AI models, data processing, and communication between the frontend and backend systems.
## Technology
We use [Hono](https://hono.dev), a lightning-fast web framework optimized for edge computing. This ensures efficient handling of API requests—particularly critical for real-time AI interactions like streaming responses.
**Importantly, this single API layer serves both web and mobile applications, guaranteeing consistent business logic and data handling across all platforms.**
## AI integration
While the API package (`@turbostarter/api`) exposes the endpoints, the core AI logic lives in a dedicated package: `@turbostarter/ai`. This package is strictly responsible for:
* Communicating with various AI providers and models ([OpenAI](/ai/docs/openai), [Anthropic](/ai/docs/anthropic), [Google AI](/ai/docs/google), etc.)
* Processing and formatting data specifically for AI interactions
* Parsing responses from AI models
* Handling AI-specific data storage or retrieval when necessary
The `@turbostarter/api` package utilizes `@turbostarter/ai` to perform these AI tasks. The API layer itself focuses on registering Hono routes, applying middlewares (like authentication and validation), and exposing AI functionalities to the frontend applications.
This separation ensures AI-specific logic remains modular and reusable, while the API package stays focused on request handling and routing.
<Callout>
API keys for AI services are managed securely on the backend within these packages, ensuring they never appear client-side.
</Callout>
## Middlewares
Hono middlewares streamline request handling by tackling common tasks before the main logic runs. In TurboStarter AI, they handle:
* **Authentication:** verifying user sessions to protect routes, ensuring only logged-in users access certain features
* **Validation:** using schemas to check if incoming request data (like query parameters or JSON bodies) matches expected formats, preventing invalid data from reaching route handlers
* **Rate limiting:** shielding the API from abuse by restricting the number of requests a user or IP address can make within a given timeframe
* **Credits management:** automatically checking if a user has enough credits for an AI operation and deducting the cost before proceeding
* **Localization:** detecting the user's preferred language to deliver localized responses and error messages
These middlewares keep core route logic clean and focused, while consistently enforcing security, usage limits, and data integrity across the API.
## Core API documentation
For general information about the API setup, architecture, authentication integration, and how to add new endpoints, please refer to the [Core API documentation](/docs/web/api/overview).
<Card title="API documentation" href="/docs/web/api/overview" description="Learn about the general API setup, structure, and best practices in the core TurboStarter documentation." />
Specific configurations related to AI providers or demo apps can be found in their respective documentation sections.

121
.context/turbostarter-framework-context/sections/ai/docs/architecture.md Normal file
View File

@@ -0,0 +1,121 @@
---
title: Architecture
description: A quick overview of the different parts of the TurboStarter AI.
url: /ai/docs/architecture
---
# Architecture
TurboStarter AI integrates several best-in-class open source libraries to power its diverse functionalities, including authentication, data persistence, text generation, and more. Here's a concise overview of the architecture that makes everything work together.
<ThemedImage alt="AI Architecture diagram" light="/images/docs/ai/architecture/light.png" dark="/images/docs/ai/architecture/dark.png" width={2526} height={1561} zoomable />
## Application framework
The project leverages a [monorepo structure](https://turbo.build/repo) powered by [Turborepo](https://turbo.build/) to enable efficient code sharing and consistent tooling across the entire application ecosystem. This approach creates a single source of truth for shared code and dramatically simplifies dependency management.
<Files>
<Folder name="apps" defaultOpen>
<Folder name="web - Web app (Next.js)" />
<Folder name="mobile - Mobile app (React Native - Expo)" />
</Folder>
<Folder name="packages" defaultOpen>
<Folder name="ai - AI features" />
<Folder name="api - API server (including all features logic)" />
<Folder name="auth - Authentication setup" />
<Folder name="db - Database setup" />
<Folder name="i18n - Internationalization setup" />
<Folder name="shared - Shared utilities and helpers" />
<Folder name="storage - Storage setup" />
<Folder name="ui - Atomic UI components">
<Folder name="shared" />
<Folder name="web" />
<Folder name="mobile" />
</Folder>
</Folder>
</Files>
### Web
Built with [Next.js](https://nextjs.org) and [React](https://react.dev), the web application leverages server-side rendering and static site generation for optimal performance and SEO. The UI is styled with [Tailwind CSS](https://tailwindcss.com) and [shadcn/ui](https://ui.shadcn.com) components for rapid development and consistent design. API routes are handled by [Hono](https://hono.dev) for edge computing, chosen for its minimal overhead and excellent TypeScript support.
<Card title="Web | TurboStarter" href="/docs/web" description="Learn more about the core web application and its features." />
### Mobile
The mobile application uses [React Native](https://reactnative.dev) with [Expo](https://expo.dev) for cross-platform development. This combination was selected for its ability to share up to 90% of code between platforms while maintaining native performance. The integration with the monorepo allows seamless sharing of business logic and types with the web application.
<Card title="Mobile | TurboStarter" href="/docs/mobile" description="Learn more about the mobile application and its features." />
## API
The API is implemented as a dedicated package using [Hono](https://hono.dev), a lightweight framework optimized for edge computing. This architectural decision creates a clear separation between frontend and backend logic, enhancing maintainability and testability.
Hono's exceptional TypeScript support ensures type safety across all endpoints, while its minimal footprint and edge-first design deliver outstanding performance.
<Card title="API" href="/ai/docs/api" description="Discover API service in AI starter and demo apps." />
## Model providers
TurboStarter AI seamlessly integrates with leading AI model providers including [OpenAI](/ai/docs/openai), [Anthropic](/ai/docs/anthropic), [Google AI](/ai/docs/google), [xAI](/ai/docs/xai), and more. The architecture employs [AI SDK](https://sdk.vercel.ai/) to create a unified interface across diverse providers, simplifying experimentation with different models.
The platform strategically utilizes specialized models for distinct AI tasks:
* **Text generation** models for conversational AI and content creation
* **Structured output** models for precise data extraction and formatting
* **Image generation** models for visual content creation
* **Voice synthesis** models for natural audio production
* **Embedding** models for semantic search and information retrieval
Switching models requires just a **one-line code change**, allowing you to rapidly adapt to emerging models or change providers based on your specific requirements. This flexibility ensures your application can leverage the latest AI advancements without extensive refactoring.
## Authentication
The applications use [Better Auth](https://www.better-auth.com/) for authentication, providing a secure and flexible authentication system. By default, the AI implementation creates an anonymous user session at startup, which is then used for all subsequent queries and interactions with the AI models. This approach maintains user context across sessions while minimizing friction.
For more sophisticated authentication requirements, you can easily extend the flow by leveraging the [Core implementation](/docs/web/auth/overview), which supports email/password authentication, magic links, OAuth providers, and more. This modular design lets you implement precisely the level of security your application demands.
<Card title="Authentication" href="/ai/docs/auth" description="Learn more about the authentication system in TurboStarter AI." />
## Persistence
Persistence in TurboStarter AI refers to the system's ability to store and retrieve data from a database. The application uses [PostgreSQL](https://www.postgresql.org/) as its primary database to store critical information such as:
* Chat history and conversation context
* User accounts and preference settings
* Vector embeddings for retrieval-augmented generation
To interact with the database from route handlers and server actions, TurboStarter AI leverages [Drizzle ORM](https://orm.drizzle.team/), a high-performance TypeScript ORM that provides type-safe database operations. This ensures robust data integrity and simplified query construction throughout the application.
A key advantage of Drizzle is its compatibility with multiple database providers including [Neon](https://neon.tech/), [Supabase](https://supabase.com/), and [PlanetScale](https://planetscale.com/). This flexibility allows seamless switching between providers based on your specific requirements without modifying queries or schema definitions — making your application highly adaptable to evolving infrastructure needs.
<Card title="Database" href="/ai/docs/database" description="Explore the database architecture and persistence layer in TurboStarter AI." />
## Blob storage
File storage is managed through S3-compatible services, providing scalable, reliable storage for diverse file types. The system efficiently handles user-uploaded images, AI-generated content, and document files. This approach ensures optimal file management and straightforward integration with various storage providers including [AWS S3](https://aws.amazon.com/s3/), [Cloudflare R2](https://www.cloudflare.com/products/r2/), or [MinIO](https://min.io/).
<Card title="Storage" href="/ai/docs/storage" description="Learn more about the storage system in TurboStarter AI." />
## Security
Security is implemented comprehensively to protect both the application and its users. All API endpoints incorporate **rate limiting** to prevent abuse and ensure fair resource allocation.
The system uses a **credits-based access** control system, where each user has a limited number of credits for AI operations, preventing resource exhaustion and enabling monetization options.
All external API interactions, including those with AI model providers, occur exclusively server-side. This ensures that sensitive API keys are **never exposed** to client-side code, significantly reducing vulnerability to unauthorized access or credential theft.
Additionally, the system implements industry-standard security practices including thorough input validation, proper authentication enforcement, and regular dependency security audits.
<Card title="Security" href="/ai/docs/security" description="Explore the security measures in place for TurboStarter AI." />

41
.context/turbostarter-framework-context/sections/ai/docs/auth.md Normal file
View File

@@ -0,0 +1,41 @@
---
title: Authentication
description: Learn about the authentication flow in TurboStarter AI.
url: /ai/docs/auth
---
# Authentication
TurboStarter AI implements a streamlined authentication approach powered by [Better Auth](https://www.better-auth.com/). Since the primary focus is showcasing AI capabilities, we've kept the initial authentication simple, allowing you to quickly integrate and experiment with AI features.
## Anonymous sessions
When someone first visits the AI application, an **anonymous session** is automatically created. This establishes a unique user identity without requiring login credentials.
These anonymous sessions serve two critical purposes:
1. **Persistence:** links data like chat history or generated content to specific users in your database
2. **Usage control:** enables tracking for rate limiting and the credits system, ensuring fair AI resource usage even for anonymous visitors
## Extending authentication
While the default anonymous setup provides a frictionless initial experience, TurboStarter is built for growth. The authentication logic uses Better Auth in the shared `packages/auth` package, ensuring consistency between web and mobile applications.
When your project needs more sophisticated authentication features like:
* Email/Password login
* Magic links
* Social logins (OAuth)
* Multi-factor authentication
You can easily integrate these by leveraging the comprehensive authentication system in the [TurboStarter Core kit](/docs/web). The underlying structure is already in place, making this transition straightforward.
For detailed implementation guides, check out the core documentation:
<Cards>
<Card title="Web authentication" href="/docs/web/auth/overview" description="Explore the full authentication capabilities for the web application." />
<Card title="Mobile authentication" href="/docs/mobile/auth/overview" description="Learn how authentication works within the mobile application." />
</Cards>
By starting with anonymous sessions, the AI kit lets you focus on building compelling AI features first, while providing a clear path to implement advanced user management and security as your application evolves.

42
.context/turbostarter-framework-context/sections/ai/docs/billing.md Normal file
View File

@@ -0,0 +1,42 @@
---
title: Billing
description: Discover how to manage billing and payment methods for AI features.
url: /ai/docs/billing
---
# Billing
TurboStarter AI includes a straightforward middleware setup to manage user credits for AI features. This lets you control access based on available credits without complex payment integrations.
## Credit-based access
A focused middleware verifies if users have enough credits before allowing them to access specific AI-powered routes or actions.
```ts title="ai.router.ts"
export const aiRouter = new Hono().post(
"/chat",
rateLimiter,
validate("json", chatMessageSchema),
deductCredits({
amount: 10, // [!code highlight]
}),
streamChat,
);
```
This example shows how the `deductCredits` middleware subtracts a specific amount (10 credits) for each request to the `/chat` endpoint.
## Coming soon
We're actively expanding the billing capabilities for AI services, including:
* **Usage-based billing:** implementing a system where users pay based on their actual consumption of AI resources (tokens used, API calls made, etc.)
* **Payment provider integration:** connecting with popular services like [Stripe](/docs/web/billing/stripe), [Lemon Squeezy](/docs/web/billing/lemon-squeezy), and more for hassle-free payment processing
## Extending billing
For more advanced billing scenarios or immediate needs, you can tap into the core TurboStarter billing features. The main documentation provides detailed guidance on setting up and managing billing with third-party providers.
<Card href="/docs/web/billing/overview" title="Billing documentation" description="Learn more about the comprehensive billing features in TurboStarter." />
Stay tuned for updates as we enhance the AI-specific billing functionalities!

168
.context/turbostarter-framework-context/sections/ai/docs/chat.md Normal file
View File

@@ -0,0 +1,168 @@
---
title: Chatbot
description: Build a powerful AI assistant with multiple LLMs, generative UI, web browsing, and image analysis.
url: /ai/docs/chat
---
# Chatbot
The [Chatbot](https://ai.turbostarter.dev/chat) demo application showcases an advanced AI assistant capable of engaging in complex conversations, performing web searches, and understanding context. It integrates multiple large language models (LLMs) and allows users to attach files to the chat window.
<AIAppShowcase id="chat" />
## Features
The chatbot offers a variety of capabilities for an enhanced conversational experience:
<Cards>
<Card title="Multi-model integration">
Switch effortlessly between leading AI providers like
[OpenAI](/ai/docs/openai) and [Anthropic](/ai/docs/anthropic) within a
single, consistent chat interface.
</Card>
<Card title="Deep reasoning">
Experience an AI that truly understands complex questions and delivers
thoughtful, nuanced responses based on comprehensive reasoning.
</Card>
<Card title="Live web information">
Access up-to-the-minute information directly from the web through the
integrated search capability powered by [Tavily AI](https://tavily.com/).
</Card>
<Card title="File sharing">
Enrich conversations by sharing and analyzing files, images, or web links
directly within the chat interface for contextual discussion.
</Card>
<Card title="Instant response delivery">
Enjoy natural, fluid conversations with responses that stream in real-time,
eliminating waiting periods.
</Card>
<Card title="Conversation history">
Seamlessly manage your conversation history with features to save, organize,
and revisit previous discussions.
</Card>
</Cards>
## Setup
To implement your advanced AI assistant, you'll need several services configured. If you haven't set these up yet, start with:
<Cards>
<Card href="/ai/docs/database" title="Database" description="Configure a PostgreSQL database to store conversation history and metadata." />
<Card href="/ai/docs/storage" title="Storage" description="Set up S3-compatible storage for handling file attachments." />
</Cards>
### AI models
<Callout>
Different models offer varying capabilities for tool calling, reasoning, and file processing. Consider these differences when selecting the optimal model for your specific use case.
</Callout>
The Chatbot leverages the AI SDK to support various language and vision models. You can easily switch between models based on your needs. Explore the documentation for the most popular models:
<Cards className="grid-cols-1 sm:grid-cols-2">
<Card href="/ai/docs/openai" title="OpenAI" description="Implement GPT and o-series models for powerful text generation." icon={<OpenAI />} />
<Card href="/ai/docs/anthropic" title="Anthropic" description="Integrate Claude models renowned for nuanced reasoning." icon={<Anthropic />} />
<Card href="/ai/docs/google" title="Google AI" description="Incorporate Gemini models for versatile AI capabilities." icon={<Google />} />
<Card href="/ai/docs/xai" title="xAI Grok" description="Leverage xAI's innovative Grok models for advanced interactions." icon={<XAI />} />
</Cards>
For detailed configuration of specific providers and other supported models, refer to the [AI SDK documentation](https://sdk.vercel.ai/providers/ai-sdk-providers).
### Web browsing
The chatbot utilizes [Tavily AI](https://tavily.com/) to provide real-time web search capabilities. Tavily is a specialized search engine optimized for LLMs and AI agents, designed to deliver highly relevant search results by automatically handling the complexities of web scraping, filtering, and extracting relevant information.
We selected Tavily because it dramatically simplifies the integration of current web data into AI applications through a single API call that returns comprehensive, AI-ready search results.
<Callout title="Free tier available">
Tavily offers a generous free tier with [1,000 API credits per
month](https://docs.tavily.com/documentation/api-credits) without requiring
credit card information. A basic search consumes 1 credit, while an advanced
search uses 2 credits. Paid plans are available for higher volume usage.
</Callout>
To enable web browsing, follow these steps:
<Steps>
<Step>
#### Get Tavily API Key
Sign up or log in at the [Tavily Platform](https://app.tavily.com/sign-in) to obtain your API key from the dashboard.
</Step>
<Step>
#### Add API Key to Environment
Add your API key to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
TAVILY_API_KEY=tvly-your-api-key
```
</Step>
</Steps>
With the API key properly configured, the chatbot will automatically utilize Tavily for searches when contextually appropriate.
## Data persistence
User interactions and chat history are persisted to ensure a continuous experience across sessions.
<Card href="/ai/docs/database" title="Database" description="Learn more about database service in TurboStarter AI." />
Conversation data is organized within a dedicated PostgreSQL schema named `chat`
to maintain clear separation from other application data.
* `chats`: stores records for each conversation session, including essential metadata like user ID and creation timestamp.
* `messages`: maintains the content of individual messages exchanged within conversations, linked to their parent chat session.
* `parts`: handles complex message structures by breaking down content into smaller components, particularly useful for generative UI elements or multi-modal content.
<Card href="/ai/docs/storage" title="Storage" description="Learn more about cloud storage service in TurboStarter AI." />
Files shared within conversations (such as images or documents) are uploaded to [cloud storage](/ai/docs/storage) (S3-compatible), with references to these attachments stored within the message content or parts.
## Structure
The Chatbot functionality is thoughtfully distributed across shared packages and platform-specific code for web and mobile, ensuring optimal code reuse and consistency.
### Core
The `@turbostarter/ai` package, located in `packages/ai`, contains the central chat functionality in the `src/chat` directory. It includes:
* Essential constants, types, and validation schemas for chat interactions
* Core API logic for managing conversations and messages
* Comprehensive chat history persistence and retrieval functionality
* AI model provider configuration and initialization
* Integrations for external tools like web search
### API
Built with Hono, the `packages/api` package defines all API endpoints. Chat-specific routes are organized under `src/modules/ai/chat`:
* `chat.router.ts`: establishes Hono RPC routes, handles input validation, and connects frontend requests to the core AI logic in `packages/ai`
* Manages authentication, request processing, and database interactions through the core package
### Web
The Next.js web application in `apps/web` implements the user-facing chat interface:
* `src/app/[locale]/(apps)/chat/**`: contains the Next.js App Router pages and layouts dedicated to the chat experience
* `src/components/chat/**`: houses reusable React components for the chat interface (message bubbles, input area, model selector, etc.)
### Mobile
The Expo/React Native mobile application in `apps/mobile` delivers a native chat experience:
* `src/app/chat/**`: defines the primary screens for the mobile chat interface
* `src/components/chat/**`: contains React Native components styled to match the web version, optimized for mobile interaction
* **API interaction**: utilizes the same Hono RPC client (`packages/api`) as the web app for consistent backend communication
This modular structure promotes separation of concerns and facilitates independent development and scaling of different parts of the application.

44
.context/turbostarter-framework-context/sections/ai/docs/database.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: Database
description: Overview of the database service in TurboStarter AI.
url: /ai/docs/database
---
# Database
The database service, managed within the `packages/db` directory (as `@turbostarter/db`), stores data essential for both core application functions and AI features. It ensures that information like user profiles, conversation history, and AI-generated content is reliably preserved and efficiently accessed.
## Technology
We've chosen [PostgreSQL](https://www.postgresql.org) as our primary relational database for its exceptional reliability, extensibility (including powerful tools like `pgvector` for similarity searches), and proven track record in production environments.
Database interactions are handled through [Drizzle ORM](https://orm.drizzle.team/), a cutting-edge TypeScript ORM that offers outstanding type safety (generating types directly from your schema), high performance, and a developer-friendly API.
For detailed guidance on setup, configuration, schema management (including migrations), and general usage patterns of Drizzle and PostgreSQL in the TurboStarter ecosystem, check out our core documentation:
<Cards>
<Card title="Overview" description="Get started with the database in the core web application." href="/docs/web/database/overview" />
<Card title="Schema" description="Learn about the core database schema definitions." href="/docs/web/database/schema" />
<Card title="Migrations" description="Understand how to manage database schema changes over time." href="/docs/web/database/migrations" />
<Card title="Client" description="Learn how to interact with the database using the type-safe Drizzle client." href="/docs/web/database/client" />
</Cards>
## What is stored in the database?
Beyond standard application data (like users and accounts), the database plays a crucial role in storing AI-specific information:
* **Chat history**: saves conversations between users and AI models (including reasoning and usage details), enabling continuous conversations and history features
* **Vector embeddings**: stores numerical representations (vectors) of text data (like document chunks) that power Retrieval-Augmented Generation (RAG) techniques, allowing features like [Chat with PDF](/ai/docs/pdf) to quickly find relevant context from large document collections
* **Document references**: tracks metadata and storage identifiers (paths in [Blob Storage](/ai/docs/storage)) for files like uploaded PDFs or AI-generated images, connecting them to relevant user interactions
* **Tool calls & results**: records actions (such as [web searches](/ai/docs/chat) or calculations) that AI models ([Agents](/ai/docs/agents)) perform, along with their outcomes—valuable for debugging, auditing, and improving agent capabilities
## Schema
The core database schema, defined in `packages/db/src/schema`, contains essential tables for the overall application (users, accounts, sessions, etc.).
To maintain clarity as AI features grow, tables specifically related to AI demo applications (like chat history for the [PDF app](/ai/docs/pdf)) are often placed in dedicated [PostgreSQL schemas](https://www.postgresql.org/docs/current/ddl-schemas.html) (e.g. a schema named `pdf`).
This logical separation helps manage complexity and isolates feature-specific data structures. You'll typically find AI-specific schema definitions either alongside the relevant demo app code or within the main `packages/db/src/schema` directory, clearly labeled and organized.

85
.context/turbostarter-framework-context/sections/ai/docs/deepseek.md Normal file
View File

@@ -0,0 +1,85 @@
---
title: DeepSeek
description: Integrate DeepSeek's powerful AI models into your applications with minimal setup.
url: /ai/docs/deepseek
---
# DeepSeek
The [DeepSeek](https://www.deepseek.com/) provider delivers access to DeepSeek's advanced AI models through the AI SDK, bringing reasoning capabilities to your applications.
![DeepSeek](/images/docs/ai/providers/deepseek.webp)
## Setup
<Steps>
<Step>
### Generate API Key
Visit the [DeepSeek Platform](https://platform.deepseek.com/) and navigate to the API keys section to create your personal secret key.
</Step>
<Step>
### Add API Key to Environment
Add your generated API key to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
DEEPSEEK_API_KEY=your-api-key
```
</Step>
<Step>
### Configure Provider (Optional)
The starter kit automatically utilizes the `DEEPSEEK_API_KEY` environment variable. For advanced configurations, consult the comprehensive [AI SDK DeepSeek documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/deepseek#provider-instance).
</Step>
</Steps>
## Features
<Cards>
<Card title="Chat Models" href="https://sdk.vercel.ai/providers/ai-sdk-providers/deepseek#language-models">
Utilize DeepSeek's language models, known for their deep reasoning
capabilities, for tasks like text generation, translation, and
conversational AI applications.
</Card>
<Card title="Reasoning" href="https://platform.deepseek.com/">
Tap into models with reasoning abilities designed specifically for complex
problem-solving, logical deduction, and analytical tasks that require deep
understanding.
</Card>
<Card title="Tool Usage / Function Calling" href="https://sdk.vercel.ai/providers/ai-sdk-providers/deepseek#tool-usage--function-calling">
Enable language models to interact with external tools and functions,
allowing for more complex and automated task execution.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="AI Chatbot">
Create intelligent chatbots that engage in natural, meaningful conversations
and assist users with a wide range of tasks. Experience this capability in
our [Chat Demo](/ai/docs/chat).
</Card>
<Card title="Content Generation">
Produce diverse, high-quality creative text content including articles,
summaries, code explanations, and marketing copy with language
understanding.
</Card>
<Card title="Automated Workflows">
Integrate language models with other tools via function calling to automate
processes like data analysis or report generation.
</Card>
</Cards>
## Links
* [DeepSeek Website](https://www.deepseek.com/)
* [DeepSeek Platform](https://platform.deepseek.com/)
* [AI SDK - DeepSeek Provider Docs](https://sdk.vercel.ai/providers/ai-sdk-providers/deepseek)

143
.context/turbostarter-framework-context/sections/ai/docs/eleven-labs.md Normal file
View File

@@ -0,0 +1,143 @@
---
title: Eleven Labs
description: Setup ElevenLabs and learn how to integrate its AI audio capabilities into the starter kit.
url: /ai/docs/eleven-labs
---
# Eleven Labs
[ElevenLabs](https://elevenlabs.io/) stands at the forefront of AI audio innovation, specializing in ultra-realistic Text-to-Speech (TTS), voice cloning, and advanced audio generation. While not a native provider within the AI SDK core, ElevenLabs' powerful services integrate seamlessly with AI applications to deliver exceptional voice experiences.
![ElevenLabs](/images/docs/ai/providers/elevenlabs.jpg)
## Setup
Integrating ElevenLabs involves using their purpose-built SDKs (Python, TypeScript/JavaScript) alongside your application logic:
<Steps>
<Step>
### Generate API Key
Visit the [ElevenLabs website](https://elevenlabs.io/), create an account or sign in, then navigate to your profile settings to generate your unique API key.
</Step>
<Step>
### Add API Key to Environment
Add your API key to your project's `.env` file (e.g., in `apps/web` or the appropriate package):
```bash title=".env"
ELEVENLABS_API_KEY=your-api-key
```
</Step>
<Step>
### Configure SDK
Initialize the ElevenLabs client with your API key:
```typescript title="client.ts"
import { ElevenLabsClient } from "elevenlabs";
import { env } from "../../env";
export const client = new ElevenLabsClient({
apiKey: env.ELEVENLABS_API_KEY,
});
// Now use the client object...
```
For comprehensive implementation details, refer to the [ElevenLabs Quickstart Guide](https://elevenlabs.io/docs/quickstart).
</Step>
</Steps>
## Features
ElevenLabs offers a comprehensive suite of AI audio technologies:
<Cards>
<Card title="Text to Speech (TTS)" href="https://elevenlabs.io/docs/capabilities/text-to-speech">
Transform written text into remarkably natural speech across numerous
languages, voices, and styles, with flexible options for quality or
low-latency delivery.
</Card>
<Card title="Speech to Text (STT)" href="https://elevenlabs.io/docs/capabilities/speech-to-text">
Transcribe spoken audio into text accurately, supporting multiple languages
and providing features like speaker diarization.
</Card>
<Card title="Voice Cloning" href="https://elevenlabs.io/docs/capabilities/voice-cloning">
Create stunningly accurate digital replicas of voices from audio samples,
with both instant and professional-grade options to suit your needs.
</Card>
<Card title="Voice Design" href="https://elevenlabs.io/docs/capabilities/voice-design">
Craft entirely new, unique synthetic voices based on descriptive parameters,
enabling custom voice creation without requiring sample recordings.
</Card>
<Card title="Conversational AI Platform" href="https://elevenlabs.io/docs/conversational-ai/overview">
Build and deploy end-to-end conversational voice agents, integrating STT,
LLMs (like GPT, Claude, Gemini), TTS, and turn-taking logic.
</Card>
<Card title="Dubbing" href="https://elevenlabs.io/docs/capabilities/dubbing">
Automatically dub audio or video content into different languages while
preserving the original voice characteristics.
</Card>
<Card title="Sound Effects" href="https://elevenlabs.io/docs/capabilities/sound-effects">
Create custom sound effects and ambient audio from simple text descriptions,
adding rich audio elements to your applications.
</Card>
<Card title="Voice Library" href="https://elevenlabs.io/voice-library">
Access an extensive collection of pre-made, ready-to-use voices contributed
by the ElevenLabs community.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="Real-time Voice Agents">
Power conversational AI applications like customer service bots, virtual
assistants, or interactive characters with low-latency TTS.
</Card>
<Card title="Audiobook & Narration">
Create professional-quality narration for audiobooks, articles, videos, and
e-learning content in multiple languages and voices. Experience this in the
[TTS Demo](/ai/docs/tts).
</Card>
<Card title="Accessibility">
Enhance digital accessibility by converting text content into natural
speech, making your applications more inclusive for users with visual
impairments or reading difficulties.
</Card>
<Card title="Personalized Content">
Deliver dynamic, personalized audio experiences with custom-designed or
cloned voices, creating unique and engaging user interactions.
</Card>
<Card title="Global Content Creation">
Utilize dubbing and multilingual TTS to easily adapt content for
international audiences.
</Card>
<Card title="Gaming & Entertainment">
Generate character voices, ambient sounds, and dynamic audio for immersive
experiences.
</Card>
</Cards>
## Links
* [ElevenLabs Website](https://elevenlabs.io/)
* [ElevenLabs Documentation](https://elevenlabs.io/docs)
* [Developer Quickstart](https://elevenlabs.io/docs/quickstart)
* [API Reference](https://elevenlabs.io/docs/api-reference/introduction)
* [Pricing](https://elevenlabs.io/pricing)

121
.context/turbostarter-framework-context/sections/ai/docs/google.md Normal file
View File

@@ -0,0 +1,121 @@
---
title: Google AI
description: Setup Google Generative AI provider and learn how to use its models like Gemini in the starter kit.
url: /ai/docs/google
---
# Google AI
The [Google Generative AI](https://ai.google/) provider integrates Google's state-of-the-art models, including the versatile Gemini family, into your applications through the AI SDK.
![Google Generative AI](/images/docs/ai/providers/google.webp)
## Setup
<Steps>
<Step>
### Generate API Key
Visit the [Google AI Studio](https://aistudio.google.com/app/apikey) to create your API key. For enterprise applications using Google Cloud, you can alternatively configure authentication via Application Default Credentials or service accounts.
</Step>
<Step>
### Add API Key to Environment
Add your API key to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key
```
If using Google Cloud credentials instead, ensure they're properly configured in your environment.
</Step>
<Step>
### Configure Provider (Optional)
The starter kit automatically uses the `GOOGLE_GENERATIVE_AI_API_KEY` environment variable. For advanced configurations (such as proxies, custom API versions, or specific headers), you can create a tailored provider instance using `createGoogleGenerativeAI`. See the [AI SDK Google documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#provider-instance) for comprehensive details.
</Step>
</Steps>
## Features
<Cards>
<Card title="Language Models (Gemini)" href="https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#language-models">
Leverage Google's advanced Gemini models for chat, text generation,
reasoning, and complex instruction following.
</Card>
<Card title="Embedding Models" href="https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#embedding-models">
Utilize text embedding models to convert text into numerical representations
for tasks like semantic search, clustering, and RAG.
</Card>
<Card title="Vision / File Input" href="https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#file-inputs">
Analyze and understand various file types (including images and PDFs)
alongside text prompts, enabling rich multimodal applications with
comprehensive content understanding.
</Card>
<Card title="Tool Usage / Function Calling" href="https://sdk.vercel.ai/docs/concepts/tools">
Empower models to interact seamlessly with external tools and APIs, allowing
them to perform real-world actions and retrieve up-to-date information for
more capable applications.
</Card>
<Card title="Safety Settings" href="https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#safety-ratings">
Configure safety thresholds to control model responses regarding harmful
content categories. Access safety ratings in the response metadata.
</Card>
<Card title="Cached Content" href="https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#cached-content">
Cache content to optimize context reuse and potentially reduce latency and
costs for repeated queries with similar context.
</Card>
<Card title="Search Grounding" href="https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai#search-grounding">
(With compatible models) Ground responses in real-time search results,
dramatically enhancing factual accuracy and providing up-to-date information
on current topics.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="AI Chatbot">
Create sophisticated conversational agents powered by Gemini models that can
engage in natural dialogue and handle complex, multi-step tasks. Experience
this in our [Chat Demo](/ai/docs/chat).
</Card>
<Card title="Content Generation">
Generate diverse text formats, from creative writing and marketing copy to
code explanations and summaries.
</Card>
<Card title="Multimodal Applications">
Build applications that seamlessly analyze and understand images, documents,
and other file types alongside text, creating richer, more contextual user
experiences.
</Card>
<Card title="Semantic Search & RAG">
Implement powerful search capabilities or sophisticated Retrieval-Augmented
Generation systems using Google's high-performance embedding models for more
accurate information retrieval.
</Card>
<Card title="Automated Workflows">
Streamline operations by connecting language models to external tools and
APIs through function calling, automating complex business processes and
repetitive tasks with minimal human intervention.
</Card>
</Cards>
## Links
* [Google AI](https://ai.google/)
* [Google AI Studio](https://aistudio.google.com/)
* [Google Generative AI Documentation](https://ai.google.dev/docs)
* [AI SDK - Google Provider Docs](https://sdk.vercel.ai/providers/ai-sdk-providers/google-generative-ai)

116
.context/turbostarter-framework-context/sections/ai/docs/image.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: Image Generation
description: Learn how to generate images using AI models within the TurboStarter AI demo application.
url: /ai/docs/image
---
# Image Generation
The [Image Generation](https://ai.turbostarter.dev/image) demo application allows users to create unique visuals from textual descriptions using various AI models. It provides a simple interface to input prompts, select models, and view generated images.
<AIAppShowcase id="image" />
## Features
Explore the capabilities of the AI-powered image generation tool:
<Cards>
<Card title="Prompt-based generation">
Create images simply by describing what you want to see in text.
</Card>
<Card title="Multi-model support">
Choose from different AI image generation models offered by various
providers.
</Card>
<Card title="Aspect ratio control">
Select the desired aspect ratio for your generated images (e.g. square,
landscape, portrait).
</Card>
<Card title="Batch generation">
Create multiple design variations from a single prompt simultaneously,
accelerating your creative workflow.
</Card>
<Card title="Generation history">
Access and reference your complete generation history, including all prompts
and resulting images for continued iteration.
</Card>
</Cards>
## Setup
To implement image generation in your application, you'll need to configure the necessary backend services.
<Cards>
<Card href="/ai/docs/database" title="Database" description="Configure a PostgreSQL database to store generation history and image metadata." />
<Card href="/ai/docs/storage" title="Storage" description="Set up S3-compatible storage to securely manage generated image assets." />
</Cards>
You'll also need API keys for your preferred AI models. Follow the detailed setup instructions in the provider documentation linked below.
## AI models
The Image Generation app leverages the AI SDK to support various models capable of creating images from text. Configure the providers for the models you wish to use:
<Cards>
<Card href="/ai/docs/openai" title="OpenAI" description="Implement DALL·E models for exceptional image quality and creative fidelity." icon={<OpenAI />} />
<Card href="/ai/docs/replicate" title="Replicate" description="Access a diverse ecosystem of open-source models including Stable Diffusion variants." icon={<Replicate />} />
</Cards>
For detailed implementation guidance, refer to the [AI SDK documentation](https://sdk.vercel.ai/docs/ai-sdk-core/image-generation) covering the `generateImage` function and supported providers.
## Data persistence
Details about image generation requests and the resulting images are stored to maintain user history.
<Card href="/ai/docs/database" title="Database" description="Learn more about database services in TurboStarter AI." />
Data is organized within a dedicated PostgreSQL schema named `image`:
* `generations`: captures detailed information about each generation request, including the `prompt`, selected `model`, `aspectRatio`, requested image `count`, `userId`, and precise timestamps.
* `images`: stores complete metadata for each generated image, linked to its parent `generation` record via `generationId` and maintaining the `url` reference to the stored image file.
<Card href="/ai/docs/storage" title="Storage" description="Learn more about cloud storage services in TurboStarter AI." />
The generated image files are securely stored in [cloud storage](/ai/docs/storage) (S3-compatible). Each image's location is tracked via the `url` field in the `images` table for reliable retrieval.
## Structure
The Image Generation feature is architected across the monorepo for optimal code organization and reusability.
### Core
The `@turbostarter/ai` package (`packages/ai`) contains the essential logic under `modules/image`:
* Comprehensive types, validation schemas (for prompts, aspect ratios, etc.), and constants
* Core API logic for processing image generation requests and interfacing with AI models
* Database operations for recording generation details and image metadata
* Utilities for uploading generated images to cloud storage
### API
The `packages/api` package defines the backend API endpoints using Hono:
* `src/modules/ai/image/image.router.ts`: implements Hono RPC routes for image generation, handles input validation, applies necessary middleware (authentication, credit management), and invokes the core logic from `@turbostarter/ai`.
### Web
The Next.js application (`apps/web`) delivers an intuitive user interface:
* `src/app/[locale]/(apps)/image/**`: contains the Next.js App Router pages and layouts for the image generation experience
* `src/components/image/**`: houses reusable React components tailored to the image generation UI (prompt input, model selector, image gallery, etc.)
### Mobile
The Expo/React Native application (`apps/mobile`) provides a native mobile experience:
* `src/app/image/**`: defines the screens for the mobile image generation interface
* `src/components/image/**`: contains React Native components optimized for mobile interaction
* **API integration**: utilizes the same Hono RPC client (`packages/api`) as the web app for consistent backend communication
This architecture ensures perfect consistency across platforms while enabling tailored UI implementations optimized for each environment.

39
.context/turbostarter-framework-context/sections/ai/docs/internationalization.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: Internationalization
description: Learn how we manage internationalization in TurboStarter AI.
url: /ai/docs/internationalization
---
# Internationalization
TurboStarter AI builds on the core internationalization (i18n) setup from the main TurboStarter framework. The shared `@turbostarter/i18n` package in `packages/i18n` handles translation management across platforms.
This gives you the benefit of a proven system using [i18next](https://www.i18next.com/) for managing translations on both web and mobile apps. Plus, the AI models and LLMs integrated within TurboStarter AI generally support multiple languages, enabling interactions beyond what's covered by UI translations alone.
For detailed information on configuring languages, adding translations, or using the `useTranslation` hook, check out the core documentation:
<Cards>
<Card title="Web internationalization" description="Learn about i18n setup for the Next.js web app." href="/docs/web/internationalization/overview" />
<Card title="Mobile internationalization" description="Learn about i18n setup for the React Native (Expo) mobile app." href="/docs/mobile/internationalization" />
</Cards>
## AI-specific translations
While most translations are shared across the platform, TurboStarter AI introduces a dedicated `ai` namespace within translation files. This namespace contains strings specifically for AI features, demo applications, and UI elements unique to the AI starter kit.
```json title="packages/i18n/locales/en/ai.json"
{
"chat": {
"title": "AI Chatbot",
"description": "Engage in intelligent conversations."
},
"image": {
"title": "Image Generation",
"description": "Create stunning visuals with AI."
}
// ... other AI-specific translations
}
```
When adding translations for new AI features or modifying existing ones, place them within the `ai` namespace in the appropriate language files (e.g., `en/ai.json`, `es/ai.json`). This keeps AI-related text organized and separate from core application translations.

125
.context/turbostarter-framework-context/sections/ai/docs/meta.md Normal file
View File

@@ -0,0 +1,125 @@
---
title: Meta
description: Setup Meta's Llama models and learn how to use them in the starter kit via various hosting providers.
url: /ai/docs/meta
---
# Meta
The [Meta](https://ai.meta.com/) provider integration brings Meta's cutting-edge Llama family of open-weight models to your applications through the AI SDK. Renowned for their exceptional performance across diverse tasks, these models deliver state-of-the-art capabilities for your AI solutions.
![Meta Llama](/images/docs/ai/providers/meta.jpg)
## Setup
Deploying Llama models in your applications involves leveraging a third-party hosting provider that integrates seamlessly with the AI SDK, such as DeepInfra, Fireworks AI, Amazon Bedrock, Baseten, and others.
<Steps>
<Step>
### Choose a hosting provider & get API Key
Select a trusted provider that hosts Llama models (e.g., [DeepInfra](https://deepinfra.com/), [Fireworks AI](https://fireworks.ai/), or [Amazon Bedrock](https://aws.amazon.com/bedrock/)). Register with your preferred provider and generate a secure API key through their platform console.
</Step>
<Step>
### Add API Key to environment
Add your provider-specific API key to your project's `.env` file (e.g., in `apps/web`). Use the appropriate environment variable for your chosen provider:
```bash title=".env"
# Example for DeepInfra
DEEPINFRA_API_KEY=your-deepinfra-api-key
# Example for Fireworks AI
FIREWORKS_API_KEY=your-fireworks-api-key
# Example for Amazon Bedrock (requires AWS credentials)
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# AWS_REGION=...
```
</Step>
<Step>
### Configure provider
When implementing AI SDK functions (`generateText`, `streamText`, etc.), initialize the client for your selected provider and specify the appropriate Llama model identifier:
```ts
import { generateText } from "ai";
import { deepinfra } from "@ai-sdk/deepinfra";
// Or: import { fireworks } from '@ai-sdk/fireworks';
// Or: import { bedrock } from '@ai-sdk/amazon-bedrock';
const { text } = await generateText({
// Example using DeepInfra
model: deepinfra("meta-llama/Meta-Llama-3.1-8B-Instruct"),
// Example using Fireworks AI
// model: fireworks('accounts/fireworks/models/llama-v3p1-8b-instruct'),
// Example using Amazon Bedrock
// model: bedrock('meta.llama3-1-8b-instruct-v1:0'),
prompt: "Why is the sky blue?",
});
```
For comprehensive implementation details, consult the AI SDK documentation for your specific provider: [DeepInfra](https://sdk.vercel.ai/providers/ai-sdk-providers/deepinfra), [Fireworks AI](https://sdk.vercel.ai/providers/ai-sdk-providers/fireworks), [Amazon Bedrock](https://sdk.vercel.ai/providers/ai-sdk-providers/amazon-bedrock), etc.
</Step>
</Steps>
## Features
Llama models accessible through the AI SDK offer a range of powerful capabilities, with specific features varying based on model version and hosting provider implementation.
<Cards>
<Card title="Chat Models" href="https://sdk.vercel.ai/docs/guides/llama-3_1">
Utilize Llama's instruction-tuned models for dialogue generation,
translation, reasoning, and other conversational tasks. Available in various
sizes (e.g., 8B, 70B, 405B).
</Card>
<Card title="Tool Usage / Function Calling" href="https://sdk.vercel.ai/docs/guides/llama-3_1#using-tools-with-the-ai-sdk">
Empower Llama models to interact with external tools and functions, enabling
complex, multi-step task execution and real-world system integration.
(Capabilities may vary depending on your selected provider).
</Card>
<Card title="Reasoning & Code Generation" href="https://ai.meta.com/blog/meta-llama-3-1/">
Leverage Llama's capabilities for complex reasoning problems and generating
code snippets in various programming languages.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="AI Chatbot">
Create intelligent, responsive chatbots capable of natural conversations,
accurate information retrieval, and efficient task execution. Experience
this capability in our [Chat Demo](/ai/docs/chat).
</Card>
<Card title="Content Generation">
Produce diverse, high-quality text content spanning articles, summaries,
creative narratives, marketing copy, and more—tailored to your specific
requirements.
</Card>
<Card title="Code Assistance">
Boost developer productivity with AI-powered code generation, insightful
code explanations, effective debugging assistance, and programming guidance
across multiple languages.
</Card>
<Card title="Automated Workflows">
Streamline operations by combining Llama models with tool usage capabilities
to automate complex business processes and seamlessly interact with your
existing systems.
</Card>
</Cards>
## Links
* [Meta AI](https://ai.meta.com/)
* [Meta Llama Models](https://ai.meta.com/llama/)
* [AI SDK - Llama 3.1 Guide](https://sdk.vercel.ai/docs/guides/llama-3_1)
* [AI SDK - Providers](https://sdk.vercel.ai/providers) (Find hosting provider docs here)

122
.context/turbostarter-framework-context/sections/ai/docs/openai.md Normal file
View File

@@ -0,0 +1,122 @@
---
title: OpenAI
description: Setup OpenAI provider and learn how to use it in the starter kit.
url: /ai/docs/openai
---
# OpenAI
The [OpenAI](https://openai.com) provider integrates OpenAI's powerful suite of language models, image generation capabilities, and embedding technologies into your application through the AI SDK.
![OpenAI](/images/docs/ai/providers/openai.png)
## Setup
<Steps>
<Step>
### Generate API Key
Visit the [OpenAI API keys page](https://platform.openai.com/api-keys) to create your personal secret key for API access.
</Step>
<Step>
### Add API Key to Environment
Add your API key to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
OPENAI_API_KEY=your-api-key
```
</Step>
<Step>
### Configure Provider (Optional)
By default, the starter kit automatically uses the `OPENAI_API_KEY` environment variable. For advanced configurations (such as using a proxy or specific organization ID), you can customize the provider instance. For detailed options, refer to the [AI SDK OpenAI documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/openai#provider-instance).
</Step>
</Steps>
## Features
<Cards>
<Card title="Chat Models" href="https://sdk.vercel.ai/providers/ai-sdk-providers/openai#language-models">
Leverage state-of-the-art models for building sophisticated conversational
AI, generating creative text formats, and answering complex questions.
</Card>
<Card title="Embedding Models" href="https://sdk.vercel.ai/providers/ai-sdk-providers/openai#embedding-models">
Transform text into rich numerical representations with powerful models like
`text-embedding-3-large`, enabling advanced semantic search, intelligent
text clustering, and highly personalized recommendation systems.
</Card>
<Card title="Image Generation (DALL·E)" href="https://sdk.vercel.ai/providers/ai-sdk-providers/openai#image-generation-models">
Generate unique images from textual descriptions using OpenAI's DALL·E
models, enabling creative applications and content generation.
</Card>
<Card title="Speech Generation (TTS)" href="https://sdk.vercel.ai/providers/ai-sdk-providers/openai#speech-generation-models">
Convert written text into natural-sounding human speech with various voices
using Text-to-Speech (TTS) models, ideal for accessibility features or voice
interfaces.
</Card>
<Card title="Vision / Image Input" href="https://sdk.vercel.ai/providers/ai-sdk-providers/openai#vision--image-input">
Empower models like GPT-4o or GPT-4 Turbo with Vision capabilities to
understand, analyze, and describe the content of images provided in prompts.
</Card>
<Card title="Tool Usage / Function Calling" href="https://sdk.vercel.ai/providers/ai-sdk-providers/openai#tool-usage--function-calling">
Allow language models to intelligently interact with your external tools,
APIs, and custom functions, orchestrating complex multi-step tasks and
creating powerful AI agents that can take actions in the real world.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="AI Chatbot">
Create intelligent, context-aware conversational agents that engage in
natural dialogue, answer complex questions, and complete sophisticated tasks
based on user needs. Experience this capability in our [Chat
Demo](/ai/docs/chat).
</Card>
<Card title="Content Generation">
Automate the creation of diverse text-based content, including blog posts,
marketing copy, emails, code snippets, and creative writing pieces.
</Card>
<Card title="Semantic Search & RAG">
Build advanced search systems that truly understand the meaning behind user
queries, enhanced with Retrieval-Augmented Generation (RAG) for delivering
exceptionally accurate, contextually relevant answers from your data.
</Card>
<Card title="Image Generation & Analysis">
Develop applications that can generate images from text prompts or analyze
and interpret the content of existing images for tagging, description, or
moderation. Check out the [Image Generation Demo](/ai/docs/image).
</Card>
<Card title="Text-to-Speech Applications">
Design engaging voice-enabled experiences, including lifelike virtual
assistants, expressive audiobook narration, real-time translation services,
and accessibility tools that convert text to natural speech for visually
impaired users.
</Card>
<Card title="Automated Workflows">
Transform business processes by connecting powerful language models to your
existing tools and systems through function calling, automating complex
workflows for data processing, report generation, customer support, and
more.
</Card>
</Cards>
## Links
* [OpenAI Website](https://openai.com/)
* [OpenAI API Documentation](https://platform.openai.com/docs)
* [AI SDK - OpenAI Provider Docs](https://sdk.vercel.ai/providers/ai-sdk-providers/openai)

135
.context/turbostarter-framework-context/sections/ai/docs/pdf.md Normal file
View File

@@ -0,0 +1,135 @@
---
title: Chat with PDF
description: Engage in conversations with your PDF documents using AI to extract insights and answer questions.
url: /ai/docs/pdf
---
# Chat with PDF
The [Chat with PDF](https://ai.turbostarter.dev/pdf) demo application enables intelligent interaction with document content through a conversational AI interface. Upload PDF files and instantly engage in natural dialogue about their contents, asking questions, requesting summaries, and extracting key information with remarkable accuracy.
<AIAppShowcase id="pdf" />
## Features
Transform how you interact with document content through these powerful capabilities:
<Cards>
<Card title="PDF upload">
Easily upload PDF files directly into the application for analysis.
</Card>
<Card title="Contextual conversation">
Chat with an AI that understands the content of your uploaded PDF, providing
relevant answers based on the text.
</Card>
<Card title="Information extraction">
Quickly find specific information, key points, or summaries within the
document through natural language queries.
</Card>
<Card title="Source highlighting (coming soon)">
Visualize exactly which document sections informed the AI's responses with
precise source highlighting.
</Card>
<Card title="Multi-document intelligence (coming soon)">
Conduct sophisticated conversations spanning multiple uploaded documents,
enabling cross-document analysis and comparison.
</Card>
</Cards>
## Setup
To implement the "Chat with PDF" application in your project, configure these essential backend services:
<Cards>
<Card href="/ai/docs/database" title="Database">
Set up PostgreSQL with the `pgvector` extension to efficiently store
conversation history, document metadata, and vector embeddings for semantic
search.
</Card>
<Card href="/ai/docs/storage" title="Storage">
Configure S3-compatible cloud storage for secure management of uploaded PDF
documents.
</Card>
</Cards>
You'll also need to obtain API keys for both the conversational AI models and the embedding models used for text processing.
## AI models
This application leverages two complementary AI model types working together:
1. **Large Language Models (LLMs):** Provide sophisticated natural language understanding to interpret your questions and generate contextually appropriate responses based on document content.
2. **Embedding Models:** Convert document text segments into numerical vector representations that enable efficient semantic similarity search and [Retrieval-Augmented Generation (RAG)](https://en.wikipedia.org/wiki/Retrieval-augmented_generation).
Configure the providers for the models you wish to use:
<Cards>
<Card href="/ai/docs/openai" title="OpenAI" description="Utilize GPT models for conversational AI and advanced embedding models for vector representation." icon={<OpenAI />} />
<Card href="/ai/docs/anthropic" title="Anthropic" description="Implement Claude models for sophisticated reasoning and nuanced document understanding." icon={<Anthropic />} />
<Card href="/ai/docs/google" title="Google AI" description="Leverage Gemini models for powerful conversational capabilities with document content." icon={<Google />} />
<Card href="/ai/docs/replicate" title="Replicate" description="Access diverse open-source embedding models for flexible implementation options." icon={<Replicate />} />
</Cards>
For comprehensive configuration details, consult the [AI SDK documentation](https://sdk.vercel.ai/docs) covering provider setup and model selection.
## Data persistence
The application stores data related to chats, documents, and embeddings to provide a persistent experience.
<Card href="/ai/docs/database" title="Database" description="Learn more about database services in TurboStarter AI." />
Application data is organized within a dedicated PostgreSQL schema named `pdf`:
* `chats`: captures essential metadata for each document-specific conversation session.
* `messages`: stores all user queries and AI responses within conversation threads.
* `documents`: maintains comprehensive tracking of uploaded PDF files, including filenames and storage locations.
* `embeddings`: contains text segments extracted from PDFs along with their vector representations (using [`pgvector`](https://github.com/pgvector/pgvector)'s `vector` data type). To optimize similarity searches critical for RAG processing, the system creates an index (`embeddingIndex` using [HNSW](https://github.com/pgvector/pgvector#hnsw)) on the `embedding` column.
<Card href="/ai/docs/storage" title="Storage" description="Learn more about cloud storage services in TurboStarter AI." />
The PDF files uploaded by users are securely stored in your configured [cloud storage](/ai/docs/storage) bucket. The `path` field in the `documents` table maintains the precise reference to each file's location.
## Structure
The "Chat with PDF" feature is architected across the monorepo for optimal organization and code reuse:
### Core
The `@turbostarter/ai` package (`packages/ai`) contains the essential logic under `modules/pdf`:
* Comprehensive types, validation schemas, and constants specific to PDF processing
* Advanced document parsing, text segmentation, and embedding generation utilities
* Core API logic for managing conversations, performing RAG-based lookups, and interacting with LLMs
* Database operations for storing and retrieving conversations, documents, and embeddings
* Shared utilities for managing PDF file uploads and downloads
### API
The `packages/api` package defines the backend API endpoints using [Hono](https://hono.dev/):
* `src/modules/ai/pdf/pdf.router.ts`: implements Hono RPC routes for document upload and conversation management, handles input validation, applies middleware (authentication, credit management), and invokes the core functionality from `@turbostarter/ai`.
### Web
The [Next.js](https://nextjs.org/) application (`apps/web`) delivers an intuitive user interface:
* `src/app/[locale]/(apps)/pdf/**`: contains the Next.js App Router pages and layouts for the document conversation experience
* `src/components/pdf/**`: houses reusable React components specific to the PDF interaction UI (document upload, conversation interface, message display)
### Mobile
The [Expo](https://expo.dev/)/[React Native](https://reactnative.dev/) application (`apps/mobile`) provides a native mobile experience:
* `src/app/pdf/**`: defines the screens for the mobile document conversation interface
* `src/components/pdf/**`: contains React Native components optimized for mobile document interaction
* **API integration**: utilizes the same Hono RPC client (`packages/api`) as the web app for consistent backend communication
This architecture ensures that core AI processing and data handling logic is shared across platforms, while enabling optimized UI implementations tailored to each environment.

85
.context/turbostarter-framework-context/sections/ai/docs/replicate.md Normal file
View File

@@ -0,0 +1,85 @@
---
title: Replicate
description: Setup Replicate provider and learn how to use it in the starter kit.
url: /ai/docs/replicate
---
# Replicate
The [Replicate](https://replicate.com) provider unlocks access to an extensive library of open-source AI models through a streamlined cloud API, seamlessly integrated with the AI SDK. It's particularly well-known for image generation capabilities.
![Replicate](/images/docs/ai/providers/replicate.png)
## Setup
<Steps>
<Step>
### Generate API Key
Visit the [Replicate website](https://replicate.com/), create an account or sign in, then navigate to your account settings to generate your personal API token.
</Step>
<Step>
### Add API Key to Environment
Add your API token to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
REPLICATE_API_TOKEN=your-api-key
```
</Step>
<Step>
### Configure Provider (Optional)
The starter kit automatically uses the `REPLICATE_API_TOKEN` environment variable. For advanced configurations (such as proxies or custom headers), you can create a tailored provider instance. For comprehensive details, refer to the [AI SDK Replicate documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/replicate#provider-instance).
</Step>
</Steps>
## Features
<Cards>
<Card title="Run Open-Source Models" href="https://replicate.com/explore">
Gain instant access to a diverse ecosystem of community-contributed models
spanning text generation, image creation, audio processing, video synthesis,
and numerous other AI capabilities.
</Card>
<Card title="Image Generation" href="https://sdk.vercel.ai/providers/ai-sdk-providers/replicate#image-models">
Create stunning visuals using various state-of-the-art open-source models
directly through the AI SDK's intuitive `generateImage` function, with
support for specific model versions and custom parameters.
</Card>
<Card title="Model-Specific Options" href="https://sdk.vercel.ai/providers/ai-sdk-providers/replicate#model-specific-options">
Fine-tune model behavior by passing specific parameters via
`providerOptions.replicate`, allowing precise control over generation
settings according to each model's unique capabilities.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="Image Generation">
Create unique visuals, artwork, or variations based on text prompts using a
diverse set of image models. Check out the [Image Generation
Demo](/ai/docs/image).
</Card>
<Card title="Access Niche Models">
Utilize specialized open-source models for specific tasks that might not be
available through other major providers.
</Card>
<Card title="AI Experimentation">
Quickly experiment with different community-published models for various AI
tasks without managing infrastructure.
</Card>
</Cards>
## Links
* [Replicate Website](https://replicate.com)
* [Replicate Documentation](https://replicate.com/docs)
* [AI SDK - Replicate Provider Docs](https://sdk.vercel.ai/providers/ai-sdk-providers/replicate)

57
.context/turbostarter-framework-context/sections/ai/docs/security.md Normal file
View File

@@ -0,0 +1,57 @@
---
title: Security
description: Learn about the security measures implemented in TurboStarter AI.
url: /ai/docs/security
---
# Security
<Callout>
Remember to regularly review your security implementations and update them as needed.
</Callout>
The starter kit incorporates several security measures to protect your application and users when interacting with AI services.
## Authenticated endpoints
All AI operation endpoints require user authentication. This is enforced through middleware that verifies the user's session before granting access to any AI features.
<Card title="Authentication" href="/ai/docs/auth" description="Learn more about the authentication setup in TurboStarter AI." />
The system creates anonymous sessions by default, but you can implement stronger authentication using the core framework's capabilities or the dedicated [authentication setup](/docs/web/auth/overview).
## Credit-based access
To prevent AI resource abuse, TurboStarter AI includes a credit-based system. Users receive a limited number of credits that are consumed when using AI features.
<Card title="Billing" href="/ai/docs/billing" description="Learn more about the billing and credits system." />
This approach avoids misuse while enabling potential monetization. Learn about the implementation details in the [Core billing documentation](/docs/web/billing/overview).
## Rate limiting
API endpoints are guarded by rate limiting to prevent abuse and ensure fair usage. This protects your application from potential denial-of-service attacks and excessive request volumes.
<Card title="API" href="/ai/docs/api" description="Learn more about the API layer and services in TurboStarter AI." />
We use [`hono-rate-limiter`](https://github.com/rhinobase/hono-rate-limiter), which supports various storage options including [Redis](https://redis.io/), [Cloudflare KV](https://developers.cloudflare.com/workers/runtime-apis/kv/), and [Memcached](https://memcached.org/) for distributed rate limiting.
## Secure API key handling
Sensitive API keys for AI providers ([OpenAI](/ai/docs/openai), [Anthropic](/ai/docs/anthropic), [Google AI](/ai/docs/google), etc.) are managed exclusively on the backend.
They are **NEVER** exposed to client-side code, dramatically reducing the risk of key leakage or unauthorized usage.
## AI service abuse protection
While TurboStarter AI provides application-level safeguards like credit limits and rate limiting, it's essential to implement additional protection directly with your AI providers.
<Callout type="warn" title="Set limits and alerts">
Always configure spending limits, usage quotas, and monitoring alerts in your
AI provider dashboards (e.g., [OpenAI](/ai/docs/openai),
[Anthropic](/ai/docs/anthropic), [Google AI](/ai/docs/google)). These serve as
critical safety nets against unexpected costs or potential abuse that might
bypass your application-level controls.
</Callout>
By combining application-level security with provider-level controls, you'll build truly robust and secure AI applications.

77
.context/turbostarter-framework-context/sections/ai/docs/stack.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Tech stack
description: Learn which tools and libraries power TurboStarter AI.
url: /ai/docs/stack
---
# Tech stack
## Turborepo
[Turborepo](https://turbo.build/) is a high-performance monorepo tool that optimizes dependency management and script execution across your project. We chose this monorepo setup to simplify feature management and enable seamless code sharing between packages.
<Card href="https://turbo.build/" title="Turborepo - Make Ship Happen" description="turbo.build" icon={<Turborepo />} />
## Next.js
[Next.js](https://nextjs.org) is a powerful [React](https://react.dev) framework that delivers server-side rendering, static site generation, and more. We selected Next.js for its exceptional flexibility and developer experience. It also serves as the foundation for our serverless API.
<Cards>
<Card href="https://react.dev" title="React" description="react.dev" icon={<React />} />
<Card href="https://nextjs.org" title="Next.js" description="nextjs.org" icon={<Next />} />
</Cards>
## React Native + Expo
[React Native](https://reactnative.dev/) is a leading open-source framework created by Facebook that enables building native mobile applications using [React](https://react.dev). It provides access to native platform capabilities while maintaining the development efficiency of React.
[Expo](https://expo.dev/) extends React Native with a comprehensive toolkit that streamlines development, building, and deployment of iOS, Android, and web apps from a single codebase.
<Cards className="grid-cols-2">
<Card href="https://reactnative.dev/" title="React Native" description="reactnative.dev" icon={<React />} />
<Card href="https://expo.dev/" title="Expo" description="expo.dev" icon={<Expo />} />
</Cards>
## AI SDK
[Vercel AI SDK](https://sdk.vercel.ai/) provides a robust toolkit for building AI-powered applications. It offers essential utilities and components for integrating advanced AI features, including streaming responses, interactive chat interfaces, and more.
<Card href="https://sdk.vercel.ai/" title="Vercel AI SDK" description="sdk.vercel.ai" icon={<AISDK />} />
## LangChain
[LangChain](https://js.langchain.com/) is a sophisticated framework designed for language model-powered applications. It delivers critical abstractions and tools for building complex AI systems, including prompt management, memory systems, and agent architectures.
<Card href="https://js.langchain.com/" title="LangChain" description="js.langchain.com" icon={<Langchain />} />
## Hono
[Hono](https://hono.dev) is an ultrafast, lightweight web framework optimized for edge computing. It includes a type-safe RPC client for secure function calls from the frontend. We leverage Hono to create efficient serverless API endpoints.
<Card href="https://hono.dev" title="Hono" description="hono.dev" icon={<Hono />} />
## Tailwind CSS
[Tailwind CSS](https://tailwindcss.com) is a utility-first CSS framework that accelerates UI development without writing custom CSS. We complement it with [Radix UI](https://radix-ui.com), a collection of accessible headless components, and [shadcn/ui](https://ui.shadcn.com), which lets you generate beautifully designed components with a single command.
<Cards className="grid-cols-2 sm:grid-cols-3">
<Card href="https://tailwindcss.com" title="Tailwind CSS" description="tailwindcss.com" icon={<Tailwind />} />
<Card href="https://radix-ui.com" title="Radix UI" description="radix-ui.com" icon={<Radix />} />
<Card href="https://ui.shadcn.com" title="shadcn/ui" description="ui.shadcn.com" icon={<Shadcn />} />
</Cards>
## Drizzle
[Drizzle](https://orm.drizzle.team/) is a type-safe, high-performance [ORM](https://orm.drizzle.team/docs/overview) (Object-Relational Mapping) for modern database management. It generates TypeScript types from your schema and enables fully type-safe queries.
We use [PostgreSQL](https://www.postgresql.org) as our default database, but Drizzle's flexibility allows you to easily switch to MySQL, SQLite, or any [other supported database](https://orm.drizzle.team/docs/connect-overview) by updating a few configuration lines.
<Cards>
<Card href="https://orm.drizzle.team/" title="Drizzle" description="orm.drizzle.team" icon={<Drizzle />} />
<Card href="https://www.postgresql.org" title="PostgreSQL" description="postgresql.org" icon={<Postgres />} />
</Cards>

34
.context/turbostarter-framework-context/sections/ai/docs/storage.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: Storage
description: Explore cloud storage services for AI applications.
url: /ai/docs/storage
---
# Storage
Blob storage in TurboStarter AI offers a scalable solution for handling the diverse file types essential to modern AI applications. It works seamlessly with S3-compatible services including [AWS S3](https://aws.amazon.com/s3/), [Cloudflare R2](https://www.cloudflare.com/products/r2/), and [MinIO](https://min.io/).
## Use cases
Blob storage powers several key AI functions:
* **Managing user uploads:** safely storing files like PDFs or images that users upload for AI processing, as seen in the ["Chat with PDF" demo](/ai/docs/pdf) and image analysis features
* **Preserving AI-generated content:** storing outputs from AI models, such as images from the [Image Generation demo](/ai/docs/image) or audio files from the [Text-to-Speech demo](/ai/docs/tts)
* **Powering RAG systems:** housing documents and files that serve as knowledge sources for Retrieval-Augmented Generation, used in demos like [Chat with PDF](/ai/docs/pdf) and intelligent [Agents](/ai/docs/agents)
## Security
Properly configuring bucket permissions for your storage provider is critical. Always restrict access based on the principle of least privilege:
* Buckets containing user uploads or sensitive RAG documents should typically **not** be publicly accessible
* Set precise permissions that allow your application server (API) to read/write as needed while blocking unauthorized access
Refer to your provider's documentation ([AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html), [Cloudflare R2](https://developers.cloudflare.com/security-center/security-insights/roles-and-permissions/), [MinIO](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html)) for specific guidance on securing your storage buckets.
## Storage documentation
For detailed setup instructions, configuration options for different storage providers, and implementation best practices, check out the core storage documentation:
<Card title="Storage documentation" href="/docs/web/storage/overview" description="Learn how to configure and manage blob storage providers in the core TurboStarter documentation." />
In summary, blob storage is essential for building sophisticated AI applications - enabling you to handle user uploads, store AI-generated files, and manage RAG document collections.

89
.context/turbostarter-framework-context/sections/ai/docs/tts.md Normal file
View File

@@ -0,0 +1,89 @@
---
title: Text to Speech
description: Convert text into natural-sounding speech using advanced AI voice synthesis models.
url: /ai/docs/tts
---
# Text to Speech
The [Text to Speech (TTS)](https://ai.turbostarter.dev/tts) demo application transforms written text into high-quality spoken audio. It leverages state-of-the-art AI models to generate lifelike voices in various languages and styles.
<AIAppShowcase id="tts" />
## Features
Discover the powerful capabilities of this AI-powered voice synthesis solution:
<Cards>
<Card title="5,000+ voices">
Access a wide range of voices from providers like [Eleven
Labs](https://elevenlabs.io/), including different accents, ages, and
emotional tones, to find the perfect match for your content.
</Card>
<Card title="Real-time audio streaming">
Experience near-instantaneous audio generation with streaming delivery,
providing immediate feedback as your content comes to life.
</Card>
<Card title="Integrated audio player">
Enjoy a full-featured playback interface with precise controls for playback
speed and convenient options to download generated audio files.
</Card>
<Card title="Voice customization">
Fine-tune your audio output with adjustable parameters for pitch, speed, and
pauses, creating the most natural and engaging delivery possible (available
options vary by provider).
</Card>
<Card title="Intuitive user experience">
Benefit from a thoughtfully designed interface that makes transforming text
to speech effortless and efficient, even for first-time users.
</Card>
</Cards>
## AI models
This application primarily utilizes specialized text-to-speech models from [Eleven Labs](https://elevenlabs.io/).
<Cards>
<Card href="/ai/docs/eleven-labs" title="Eleven Labs" description="Integrate Eleven Labs' state-of-the-art voice synthesis technology for stunningly realistic and expressive speech generation." icon={<ElevenLabs />} />
</Cards>
For comprehensive information about available voices and advanced customization techniques, consult the [ElevenLabs SDK documentation](https://elevenlabs.io/docs/overview).
## Structure
The Text-to-Speech feature is organized across the monorepo for maximum flexibility and maintainability:
### Core
The `@turbostarter/ai` package (`packages/ai`) contains the essential logic under `modules/tts`:
* Comprehensive types, validation schemas, and constants specific to TTS functionality
* Core API logic for processing text-to-speech requests and interfacing with AI models
* Robust handling of generated audio file uploads to cloud storage
### API
The `packages/api` package defines the backend API endpoints using [Hono](https://hono.dev/):
* `src/modules/ai/tts/tts.router.ts`: implements Hono RPC routes for TTS generation, handles input validation, applies critical middleware (authentication, credit management), and invokes the core functionality from `@turbostarter/ai`.
### Web
The [Next.js](https://nextjs.org/) application (`apps/web`) provides the user interface:
* `src/app/[locale]/(apps)/tts/**`: contains the Next.js App Router pages and layouts for the TTS experience
* `src/components/tts/**`: houses reusable React components specific to the TTS interface (text input area, voice selector, audio player, etc.)
### Mobile
The [Expo](https://expo.dev/)/[React Native](https://reactnative.dev/) application (`apps/mobile`) provides the native mobile experience:
* `src/app/tts/**`: defines the screens for the mobile TTS interface
* `src/components/tts/**`: contains React Native components optimized for the mobile experience
* **API interaction**: utilizes the same Hono RPC client (`packages/api`) as the web app for consistent communication with the backend
This architecture ensures perfect consistency between platforms while allowing for optimized UI implementations tailored to each environment.

85
.context/turbostarter-framework-context/sections/ai/docs/ui.md Normal file
View File

@@ -0,0 +1,85 @@
---
title: UI
description: Learn more about UI components and design system in AI starter kit.
url: /ai/docs/ui
---
# UI
TurboStarter AI builds on the core TurboStarter UI foundation to create engaging interfaces for all AI features.
The UI architecture uses shared components and styles with platform-specific implementations:
* **`@turbostarter/ui`**: includes shared assets, themes, and fundamental styles
* **`@turbostarter/ui-web`**: contains web components built with [Tailwind CSS](https://tailwindcss.com), [Radix UI](https://www.radix-ui.com/), and [shadcn/ui](https://ui.shadcn.com)
* **`@turbostarter/ui-mobile`**: delivers mobile components using [Uniwind](https://uniwind.dev/) and [react-native-reusables](https://reactnativereusables.com/)
This approach maximizes code reuse while optimizing for each platform's unique capabilities.
## UI in AI applications
The AI starter kit leverages this foundation to create intuitive interfaces for various features and demo apps:
<Cards>
<Card title="Chat interfaces" className="shadow-none">
Components for displaying conversations, user input, and streaming responses
(used in [Chatbot](/ai/docs/chat) and [Chat with PDF](/ai/docs/pdf) demos).
</Card>
<Card title="Image galleries" className="shadow-none">
Displaying AI-generated images as masonry grids with options for interaction
(used in [Image Generation](/ai/docs/image) demo).
</Card>
<Card title="Input forms" className="shadow-none">
Structured forms for configuring AI tasks (e.g., selecting models, adjusting
parameters, modifying prompts).
</Card>
<Card title="Animations" className="shadow-none">
Visual feedback during AI processing, such as loading spinners or progress
indicators (e.g. [Text to Speech](/ai/docs/tts) voice avatar animation).
</Card>
<Card title="Feedback mechanisms" className="shadow-none">
UI elements for users to rate or provide feedback on AI outputs. This can
include thumbs up/down buttons or text input fields for comments.
</Card>
<Card title="Error handling" className="shadow-none">
Components for displaying error messages or alerts when AI tasks fail or
encounter issues.
</Card>
<Card title="Accessibility features" className="shadow-none">
Ensuring that all UI components are usable for individuals with
disabilities, including keyboard navigation and screen reader support.
</Card>
<Card title="Visualizations" className="shadow-none">
Components for displaying data or model outputs visually, such as charts,
graphs, or progress bars.
</Card>
</Cards>
## Generative UI
A standout aspect of AI applications is their ability to dynamically create or modify UI elements based on AI responses. TurboStarter AI enables this through:
* **AI SDK components**: libraries like the [AI SDK](https://sdk.vercel.ai/docs/introduction) provide specialized components and hooks (like `useActions` and `useUIState`) designed to render UI based on AI actions or structured data. This creates interactive elements—buttons, forms, or visualizations—that appear dynamically within conversations or workflows.
* **Structured output**: AI models can return data in specific formats (such as JSON) that your frontend parses to render appropriate components, display information, or trigger actions. For example, an AI might return product details that automatically render as interactive cards.
* **Conditional rendering**: the platform uses standard React patterns for showing, hiding, or transforming UI components based on AI interaction states. This creates smooth transitions between loading states, results displays, and follow-up options tailored to AI suggestions.
This approach delivers truly responsive user experiences where interfaces adapt intelligently to ongoing AI processes. The [Chat demo app](/ai/docs/chat) showcases these generative UI capabilities in action.
## Customization and further details
Customizing appearance (themes, styling) or adding new UI components follows the same process as core TurboStarter applications. For complete guides on styling, theme management, and component development, see our core documentation:
<Cards>
<Card title="Web UI customization" description="Learn how to customize styling and components for the web application." href="/docs/web/customization/styling" />
<Card title="Mobile UI customization" description="Learn how to customize styling and components for the mobile application." href="/docs/mobile/customization/styling" />
</Cards>
By leveraging the core UI system, TurboStarter AI ensures consistent user experiences across platforms while letting you focus on creating unique AI functionalities.

90
.context/turbostarter-framework-context/sections/ai/docs/xai.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: xAI Grok
description: Setup xAI provider and learn how to use it in the starter kit.
url: /ai/docs/xai
---
# xAI Grok
The [xAI](https://x.ai) provider integrates Grok models into your application using the AI SDK.
![xAI Grok](/images/docs/ai/providers/xai.webp)
## Setup
<Steps>
<Step>
### Generate API Key
Visit the [xAI website](https://x.ai) to create an account. After signing in, navigate to your account settings to generate an API key.
</Step>
<Step>
### Add API Key to Environment
Once you've acquired an API key, add it to your project's `.env` file (e.g., in `apps/web`):
```bash title=".env"
XAI_API_KEY=your-api-key
```
</Step>
<Step>
### Configure Provider (Optional)
The starter kit automatically uses the `XAI_API_KEY` environment variable. For advanced configurations and customization options, refer to the comprehensive [AI SDK xAI documentation](https://sdk.vercel.ai/providers/ai-sdk-providers/xai#provider-instance).
</Step>
</Steps>
## Features
<Cards>
<Card title="Chat Models" href="https://sdk.vercel.ai/providers/ai-sdk-providers/xai#language-models">
Utilize xAI's language models for conversational AI, text generation, and
other natural language processing tasks.
</Card>
<Card title="Tool Usage / Function Calling" href="https://sdk.vercel.ai/providers/ai-sdk-providers/xai#tool-usage--function-calling">
Enable language models to interact with external tools and functions,
allowing for more complex and automated task execution.
</Card>
<Card title="Image Generation" href="https://sdk.vercel.ai/providers/ai-sdk-providers/xai#image-models">
Generate images based on textual descriptions using xAI's models.
</Card>
</Cards>
## Use Cases
<Cards>
<Card title="AI Chatbot">
Create intelligent chatbots that engage users in natural, informative
conversations powered by xAI's Grok models, delivering responsive and
contextually relevant interactions. Experience this capability in our [Chat
Demo](/ai/docs/chat).
</Card>
<Card title="Content Generation">
Produce diverse, high-quality text content across various formats and
styles, harnessing the unique characteristics and capabilities of Grok
models for creative and informational outputs.
</Card>
<Card title="Automated Workflows">
Streamline operations by connecting xAI's language models with your existing
tools through function calling, enabling sophisticated automation of complex
business processes and repetitive tasks.
</Card>
<Card title="Image Generation">
Design striking visuals and artwork directly from text descriptions using
xAI's image generation capabilities, enabling creative applications and rich
visual content. Explore our [Image Generation Demo](/ai/docs/image) to see
these features in action.
</Card>
</Cards>
## Links
* [xAI Website](https://x.ai)
* [AI SDK - xAI Provider Docs](https://sdk.vercel.ai/providers/ai-sdk-providers/xai)