> 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.         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.toucanai.cloud/embed/embedding-overview/typical-architectures.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.