Typical architectures

Target Audience: Developers

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

---

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.