# aircall/aircall-everywhere architecture

> Architecture diagram of the GitHub repository aircall/aircall-everywhere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aircall/aircall-everywhere
- Repository: https://github.com/aircall/aircall-everywhere

## Overview

This project is a JavaScript library intended to enable the integration of an Aircall phone interface into any CRM via an npm dependency. Its main purpose is to provide a simple API to embed and control an Aircall phone (loaded via an iframe) by letting end users instantiate the phone, listen for call-related events, and communicate with it—thus enabling rich telephony features in a CRM environment.

##### Main Components
- Library Core: The heart of the project is the library code in src/javascripts/aircallPhone.js. This module encapsulates the constructor, event handling (e.g., on, send, removeListener), and methods like isLoggedIn.
- Embedded Phone Component: The library generates an iframe (pointing to https://phone.aircall.io with certain query parameters) that displays the Aircall phone interface. This is an external component with defined allow attributes.
- Demo Application: The demo directory (with index.html, demo.css, demo.js, and demo.scss) serves as an example integration for immediate testing and illustration of how the library works.
- Build and Deployment Infrastructure: The scripts directory contains various shell scripts for publishing and CI tasks, along with a webpack folder that holds configuration files (webpack.build.js, webpack.dev.js, webpack.publish.js) used to bundle the source code.
- Testing Suite: The spec directory contains JavaScript test files (e.g., aircallPhone.spec.js) and support files that ensure proper functioning through unit/integration tests.
- CI/CD Setup: Configuration files in .circleci, .github, and associated workflow definitions indicate continuous integration and automated testing before publishing new versions.

##### Relationships and Interactions
- The consuming application (CRM or any project that installs the library via npm) instantiates the AircallPhone class and passes configuration options such as callbacks (onLogin, onLogout), integration settings (e.g., ‘zendesk’, ‘hubspot’), DOM element selector (domToLoadPhone), and sizing parameters.
- When instantiated, the library creates an iframe that embeds the Aircall phone interface. This iframe is responsible for the UI and handling the call events.
- The library listens for events originating from the iframe (incoming_call, outgoing_call, etc.) and provides a mechanism (the on method) for registering custom callbacks.
- The library has a communication channel to send commands to the phone (using the send method) and react based on responses and errors.
- The build process (using Babel and webpack) transforms the source code in src into a distributable package. The demo and tests use this built version to validate behavior.

##### Architectural Patterns and Design Principles
- Modular and Component-Based Design: Different concerns are clearly separated (core logic, UI via iframe, build tooling, tests, CI configurations).
- Event-Driven Architecture: The library is structured around event registration and messaging between the embedded iframe and the host environment.
- Encapsulation and Abstraction: The library abstracts the complexity of integrating Aircall’s telephony features into any CRM by providing simple methods and callbacks.
- CI/CD and Automated Testing: The inclusion of CI configuration and comprehensive test suites ensures reliability during integration and development.

##### Relevant Technologies & Libraries
- JavaScript (ES6+), Babel (for transpilation), and Webpack (for module bundling).
- NPM for package management.
- Testing tools (as suggested by spec folder tests).
- Integration with CI/CD platforms via CircleCI and GitHub Actions.
- External integration (iframe loading content from Aircall’s server and potentially working with Zendesk or HubSpot APIs for CRM integrations).

##### Final Advice
- Be very detailed and capture each essential element (from client integration to build processes and test infrastructure).
- The goal is to visually map out how the library encapsulates telephony features, how communication is handled via events, and how modules and CI processes support development, testing, and deployment.
- Since the system is a library rather than a complete full-stack app, focus on the integration flow and modular build process rather than server-side or database interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level components
    Client["Client/CRM App"]:::client
    DemoApp["Demo Application"]:::demo
    AircallCore["Aircall Phone Library (Core Logic)"]:::core
    EmbeddedPhone["Embedded Phone UI (iframe)"]:::ui

    %% Build Pipeline Subgraph
    subgraph "Build Pipeline"
        BabelConfig["Babel Config (.babelrc)"]:::build
        WebpackBuild["Webpack Build (scripts/webpack/webpack.build.js)"]:::build
        WebpackDev["Webpack Dev (scripts/webpack/webpack.dev.js)"]:::build
        WebpackPublish["Webpack Publish (scripts/webpack/webpack.publish.js)"]:::build
        NpmDist["npm Package Distribution"]:::build
        BabelConfig -->|"transpile"| WebpackBuild
        WebpackBuild -->|"bundle"| WebpackDev
        WebpackDev -->|"prepare"| WebpackPublish
        WebpackPublish -->|"output"| NpmDist
    end

    %% CI/CD Subgraph
    subgraph "CI/CD Infrastructure"
        CircleCI["CircleCI (.circleci/config.yml)"]:::ci
        Github["GitHub Actions (.github/workflows/test-build.yml)"]:::ci
        CircleCI ---|"automated triggers"| Github
    end

    %% Testing Suite
    TestingSuite["Testing Suite (spec)"]:::test

    %% Relationships and Data Flow
    Client -->|"instantiates"| AircallCore
    DemoApp -->|"demonstrates usage"| AircallCore
    AircallCore -->|"creates"| EmbeddedPhone
    AircallCore <-->|"events&commands"| EmbeddedPhone
    AircallCore -->|"validated_by"| TestingSuite
    CircleCI ---|"runs tests"| TestingSuite
    Github ---|"runs tests"| TestingSuite
    CircleCI ---|"triggers build"| BabelConfig
    Github ---|"triggers build"| BabelConfig

    %% Styles for visual differentiation
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef ui fill:#ccddff,stroke:#333,stroke-width:2px;
    classDef demo fill:#ffdddd,stroke:#333,stroke-width:2px;
    classDef test fill:#ddddff,stroke:#333,stroke-width:2px;
    classDef build fill:#ffeecc,stroke:#333,stroke-width:2px;
    classDef ci fill:#e0e0e0,stroke:#333,stroke-width:2px;

    %% Click Events
    click AircallCore "https://github.com/aircall/aircall-everywhere/blob/master/src/javascripts/aircallPhone.js"
    click EmbeddedPhone "https://github.com/aircall/aircall-everywhere/blob/master/src/javascripts/aircallPhone.js"
    click DemoApp "https://github.com/aircall/aircall-everywhere/tree/master/demo"
    click BabelConfig "https://github.com/aircall/aircall-everywhere/blob/master/.babelrc"
    click WebpackBuild "https://github.com/aircall/aircall-everywhere/blob/master/scripts/webpack/webpack.build.js"
    click WebpackDev "https://github.com/aircall/aircall-everywhere/blob/master/scripts/webpack/webpack.dev.js"
    click WebpackPublish "https://github.com/aircall/aircall-everywhere/blob/master/scripts/webpack/webpack.publish.js"
    click TestingSuite "https://github.com/aircall/aircall-everywhere/blob/master/spec/javascripts/aircallPhone.spec.js"
    click CircleCI "https://github.com/aircall/aircall-everywhere/blob/master/.circleci/config.yml"
    click Github "https://github.com/aircall/aircall-everywhere/blob/master/.github/workflows/test-build.yml"
```
