Typical architectures

TL;DRCopy Anchor Link

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

---

When to use thisCopy Anchor Link

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

---

Integration PatternsCopy Anchor Link

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 ConsiderationsCopy Anchor Link

• 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 DiagramCopy Anchor Link

---

Summary TableCopy Anchor Link