⚙️Toucan stack
Introduction
This documentation aims to guide our partners through Toucan Toco architecture, introducing design choices and the security norms it respects.
Specific emphasized blocks like this one provide a high-level view in order to keep things simple and quick while the rest covers topics in depth.
For business owners and administrative users, this will show you an overview of our architecture and answer some of your questions about how Toucan works. You can forward it to your IT department if they need more information.
For IT departments & architects, this gives you a complete overview of the architecture of our apps, and will help you identify how Toucan can be integrated easily with your information system. It also describes the prerequisites needed to install our components as self-hosted software.
For security experts, this aims to transparently let you assess our security level and answer questions and address possible concerns you have regarding our authentication and authorization processes. It also shares the practices and processes we implement in our own information system to ensure that the data you transmit to us stays in good hands.
Definitions
Toucan is a web application that allows you to display your data for your customers through data storytelling. Web applications are served through an HTTP server and an HTTP client, which is often the web browser.
The HTTP client / the Web Browser / the user
Communication
The HTTP client, often named the Web Browser, or simply the user in our diagrams, is the end user.
The end user is the one who interacts with the web application and is the one who sees the web page. The end user is the one who create values to the application, and therefore, our business logic is developped around the expected demands of the end user.
Technically speaking, the client doesn't simply fetch data from the server, but uses the HyperText Transfer Protocol (HTTP), which is a TCP protocol used to download HTML (HyperText Markup Language) files and many other files like CSS and JS files to display the web page.
To communicate securely with the server, the client uses TLS/SSL (Transport Layer Security), which is a additional protocol that is added on top of TCP and encrypts the communication between the client and the server.
Application (HTTP)
TLS
Transport (TCP)
Network (IP)
Data Link (Ethernet)
Physical Layer
Any application data is encrypted before it is sent over the network. This is also known as "implicit" TLS because both client and server doesn't require to explicitly say that they want to use TLS.
The reasons why the client trust the server is thanks to the common source of authority that is used between the client and the server. This is often the Certificate Authority (CA) that is used to sign the server's TLS certificate. These sources of authority are installed directly in the user's operating system.
Behavior
Since the client is a web browser, it requires specific files to display a page:
HTML files, which are the main content of the page like text and layouts.
CSS files, which are the style of the page.
JavaScript (JS) files, which are the "client-side" logic of the page, often used for animation and user interaction.
As you can see, after the files are downloaded and the page loaded, no further data is sent to the server and everything is happening on the client side. JS files may trigger further HTTP requests to the server, but only to fetch data, or trigger some actions on the server.
Since the files doesn't handle any business logic, these files collectively form the front end, which is responsible for everything the user sees and interacts with. In a way, these files are safe to share to the public (like embedding a dashboard in to a website) because they don't handle any sensitive data.
Our front end itself is evolving into a collection of independent, reusable components called Micro Front Ends (MFEs). Each MFE is designed to render a specific part of the application based on configuration files and Toucan data.
The HTTP server(s) / the back-end / Toucan
Serving data
The HTTP server(s), also known as the back-end, or simply Toucan in our diagrams, is the services that provides the processed and formatted data to the client.
These servers communicate with the database to fetch the data, which is then processed based on business rules to provide appropriate data to clients or other services.
Toucan's value resides in the way we transform the data into a beautiful and presentable format for the end users.
Micro services
Similarly to the front-end, the back-end is splitted into multiple services. Each service is responsible for a specific part of the application and provides their own value to the whole application.
This often contrasts with the monolithic architecture, where the business logic is handled by a single service.
The choice of a microservice architecture is often done for several reasons:
Single Responsibility Principle: Each service is responsible for a specific part of the application, making it easier to maintain and scale.
Maintainability: Each service can be independently tested and deployed, making it easier to identify and fix issues.
Scalability: Each service can be scaled independently, making it easier to handle high traffic loads.
In large teams, it is often recommended to use a microservice architecture, as it allows for better maintainability and scalability.
Roles
Our services are split into the following roles:
The "front-end" service (or reverse proxy), which serve the front-end files.
The authorization service, which store permissions rules and authorization policies.
The authentication and identity service, which permit users to access the Toucan application.
The workspace service, which handles various workspace management tasks like authorization and user session. It often communicates with the authorization service and authentication service.
The dataset service, which store dataset configurations.
The layout service, which store the configuration of the layouts of the dashboards.
The data execution service, which executes the queries to fetch and transform the data from data sources based on the dataset configurations.
The databases and stores, which store the user data.
And various utility services like the notification service, etc.
All these services exchange between them with various standard protocol on top of HTTP, such as REST or GraphQL APIs.
Technical Stack Details
This section provides a detailed insight into the architecture and components of Toucan, with a focus on the underlying technologies and services used to build the application.
We use the C4 model, a visual representation of Toucan software system.
Detailed Workflow
System Context Diagram
The system context diagram explains the external communication between Toucan and its surrounding environment.
This is a way to expose all the interfaces (APIs) of each services of Toucan. Knowing these services do internal-external communication, they are all encrypted and secured with TLS.
This diagram provides an overview of Toucan software system and its surrounding environment showing the main components and how they interact each other.
In general, the user communicate with Toucan on two entrypoints:
The reverse proxy, which serves the front-end files, but also handles the authentication of requests.
The authentication service, which is use to initiate the authentication process.
Container Diagram
The container diagram provides a detailed view of the software system, illustrating its high-level components and their interactions.
For clarity, some components have been hidden from the diagram. Two of the most important are the cache and the flag manager. The cache is connected to nearly every service, and the flag manager, which controls the activation and deactivation of features, is also connected to most services.
This diagram shows that the embed doesn't communicate with the host website; instead, users communicate directly with the services. The external website simply inserts a script from Toucan used to trigger the client to actually load the dashboard from the Toucan services.
The diagram makes it easy to distinguish the different types of services and their roles, as discussed previously. You can clearly see which business components are closer to the presentation layer and which are closer to the data layer. For example, the data execution service is closer to the data layer because it is responsible to transform the customer's data, which is stored in external data sources, or our Cloud Object Storage.
To describe furthermore the diagram:
Black bold arrows describe the main business flow of Toucan.
Black thin arrows describe the communication between services to achieve a business rule.
Purple arrows permits to distiguish authorization calls, which are simple calls to the authorization service.
Red arrows shows the connections with the storage.
We make sure that:
Red arrows (storage) are never exposed directly to the user.
Black bold arrows (internal-external communication) are secured with TLS and are encrypted.
Black thin arrows (internal-internal communication) are secured internally through private networks.
Purple arrows (authorization) secures most of the business rules.
Open Source
We also contribute by publishing some of our work in the open source community.
Feel free to look at our public repositories on GitHub.
Last updated
Was this helpful?