> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/embed/embedding-overview/typical-architectures.md).

# Typical architectures

{% hint style="info" %}
**Target Audience**: Developers
{% endhint %}

### TL;DR

Toucan AI supports multiple integration patterns, ranging from direct client-side web components to backend-driven API workflows.

***

### When to use this

Use this page to select the integration model that aligns with your application's security requirements and existing infrastructure.

***

### Integration Patterns

**1. Client-Side Embedding (Web Components)**

This pattern involves loading Toucan AI components directly into the application's frontend.

* **Workflow**: The host application generates a secure token on its server and passes it to the `<tc-dashboard>` or `<tc-ai-assistant>` web components.
* **Best for**: SaaS products requiring fast deployment and high interactivity with minimal backend modifications.
* **Benefits**: Supports responsive design, full interactivity, and user-specific Row-Level Security (RLS).

**2. Backend-Driven Embedding (API Integration)**

In this model, the backend manages the communication with the Toucan AI API.

* **Workflow**: The application backend requests tokens and manages access permissions before the frontend renders the analytics components.
* **Best for**: Applications with complex multi-tenancy, advanced data governance, or legacy system requirements.
* **Benefits**: Provides maximum control over data flow and allows for custom business logic during the authentication phase.

**3. Hybrid Approach**

This architecture combines client-side components with backend API orchestration.

* **Workflow**: Uses web components for user interactivity while utilizing backend API calls for tasks like audit logging or dynamic token attribute generation.
* **Best for**: Enterprise products requiring deep integration with internal security and logging systems.

***

### Implementation Considerations

* **Token Generation**: Tokens must be generated on the server side to protect API keys and prevent unauthorized access.
* **Row-Level Security (RLS)**: Use token attributes to map user context to specific data rows, ensuring multi-tenant isolation.
* **Branding**: Apply custom CSS and themes to embedded components to match the host application's visual identity.
* **Deployment Options**: Toucan AI is available via SaaS or can be self-hosted using Docker and Helm charts.

***

### Example Architecture Diagram

<figure><img src="/files/uQzuUsu7WMvcQ6Kamu1u" alt="Architecture Diagram"><figcaption></figcaption></figure>

***

### Summary Table

| Architecture       | Primary Advantage                           | Typical Persona                |
| ------------------ | ------------------------------------------- | ------------------------------ |
| **Client-Side**    | Speed of implementation and responsiveness. | Frontend Developers.           |
| **Backend-Driven** | High security and data flow control.        | Full-Stack/Backend Developers. |
| **Hybrid**         | Flexibility and deep system integration.    | Enterprise Architects.         |