Documentation Home »Architecture Guide
current version

Architecture Guide

What is Oro Application

Oro application is a PHP web application that is using Symfony as a framework. It provides the following benefits:

  • Runs on any OS, though Linux is recommended. See system requirements for more info.
  • Scalable – Oro application may be easily scaled up and down to meet your company needs (message queue, indexes, search).
  • Extendable – Oro application may be extended via the packages from the marketplace designed by Oro, Oro partners, or Oro community. Also, you may design your own packages to implement the missing functionality.
  • Customizable – Oro application inherits most of the development techniques enabled by the Symfony framework and extends them. It helps easily customize Oro app for any business needs.

With these out-of-the-box benefits, developers can focus on implementing their unique business logic and build Oro-based applications in less time.

Oro Licensing

All Oro applications are distributed under OSL v3 license, however, every Oro application is available as an Enterprise Edition under the EULA license. Enterprise Editions come with support and better scalability.

Architecture Overview

Technology Stack

As any web application, Oro application generally follows a client – server architecture to deliver the web content prepared by the server-side stack to the client-side and deliver response. Oro application rely on the number of embedded, integrated, and distributed technologies explained below.

Client Side

A client, whether it is a web-browser or a third-party application connected via the API, makes requests to the Oro application server-side to get the application content or JSON response. Information received in response from the server-side may be used:

  • By the web browser – to render or update the web page shown to the end user.
  • By the third party application – to launch data synchronization, trigger actions in Oro applications or other integrated systems.
Web Browser

Oro applications supports the following web browsers:

Out of the box, Oro Applications are mobile friendly due to the responsive and adaptive UI.

In addition to the HTTP connections, Oro applications establish websocket connections between web browsers and server side for the real-time communication (e.g. status notifications, alerts, etc.)

API Client

The architecture of the third-party application that connects to Oro application via the API is not limited by the Oro application architecture. The API client may be implemented as a separate custom web application, custom mobile application, ERP system, ETL service, etc.

Server Side

On the server-side, the Oro application is composed of the multiple systems and elements that interact to deliver a reliable, scalable, and responsive Oro solution. They are detailed in the following sections.

Oro PHP Application

The core component, let us call it Oro PHP Application, is a modular PHP web application that leverage the Symfony framework and Doctrine ORM strengths. It interacts with the following system components:

  • Database and RDBMS
  • Web Server and PHP
  • Message Queue
  • Search Engine
Database and RDBMS

Oro application uses the database to store application data and uses Doctrine database abstraction layer (DBAL) and object-relational mapper (ORM) to interact with the database. That enables out of the box support of various databases enabled by Doctrine. On top of that, in Oro application, Doctrine capabilities are extended with additional database functions in the Oro Doctrine Extensions library. Currently the extended functions are supported for MySQL and PostgreSQL databases only.

Supported RDBMs:

  • MySQL in CE and EE
  • PostgreSQL in EE only (for scalability)


For implementation details, see Database System Component topic for more information about the database component.

Web Server and PHP

A web server is an HTTP server that manages client requests and proxies them to the Oro PHP Application. Web server may rely on the PHP-FPM to process requests to Oro PHP Application and prepare the response.

Supported web servers: Apache and Nginx

Message Queue

Oro application uses Message Queue to enable asynchronous processing for the heavy jobs that, when executed immediately, may cause performance degradation. For example, reindexation of a large volume of data, creation of large bulks of items, etc. is usually handled via MQ consumers. To process the queued messages, Oro application uses a proprietary consumer service. It is running as a daemon and handles all the asynchronous jobs (messages) registered within a Message Queue. Consumer service is scalable and can run as a parallel processes and/or on multiple servers to handle a large volume of asynchronous processes. Number of processes required depends on the server capacity. To guarantee the acceptable response time and address spikes in the server-side workload, you can scale the message processing by adding more consumer services on demand.

Supported MQ solutions:

  • Proprietary DB-based MQ in CE and EE
  • RabbitMQ in EE only (for scalability)


For implementation details, see Message Queue topic for more information about the message queue component.

Search Engine

Oro application uses Search Index to enable full-text search and speed up the run-time access to the large amounts of application data.

Supported search index providers:


For implementation details, see Search Index topic for more information about the search index component.

Notes on Deployment Options

For a compact and resource-efficient deployment, all systems and elements of the Oro application may be hosted on a single physical or virtual server instance. For scalable high-load deployments: Multiple instances of Oro application may be hosted on their dedicated web servers, where the load balancer directs client requests to the necessary web server. All systems and elements of the Oro application may be hosted on their own dedicated server and could be scaled separately.

Oro PHP Application Structure

Source Code Repositories

Source code of the Community Editions of OroPlatform, OroCRM, and OroCommerce applications is open and is available for download, contribution and collaboration on GitHub, in the OroInc organization.

The repositories in OroInc organization may vary by type and contain the source code of the projects of various scale:

  • Applications
  • Packages
  • Components

Any Oro application and packages may be used in the following modes:

  • Oro application may by installed and immediately used in the production environment
  • Oro application or Oro package source code may be used as a base for a custom application. Clone the Oro application repository, fork it, or download the source code as an archive and customize and extend the code as necessary.
  • Oro packages may be embedded as ready-to-use features into any application. Create your own application from scratch and add Oro packages as composer dependencies. Read more about composer dependency manager in the Distribution Model section below.

An application repository stores a complete solution created to automate activities for the business domain (e.g. customer relationship management, B2B commerce, marketing automation, etc.) Oro application provides a set of features and delivers number of benefits to the end user. Apart from the source code that implements business logics for the application features, Oro application repositories contain minimal set of configuration and initialization scripts for installing and running Oro application in dev, test, or prod environment.

Sample applications: OroCRM, OroCommerce, OroPlatform

A package repository contains a module that groups a set of ready-to-use features, usually those related to a particular business subdomain, and may be included into any Oro application. To enable Oro package in the Oro application, add it as a dependency/prerequisite before you start Oro application installation. As long as Oro application uses Symfony framework, packages may contain Bundles.

For example, Marketing package is enabled out of the box in OroCRM and OroCommerce applications.

A component repository contains a source code of the reusable development module that enables a set of commonly used functions that may be used as third party libraries, without Oro application. Rather than a complete business feature, Oro component may handle generic functionality that is not bound to the business domain. Component repositories are typically published as read-only subtree distributions of independent package bundles or components.

Sample component: OroMessageQueueBundle

You can find a complete list of OroInc public repositories at


Any Oro application and packages may be used in the following modes:

  • Oro application may by installed and immediately used in the production environment
  • Oro application or Oro package source code may be used as a base for a custom application. Clone the Oro application repository, fork it, or download the source code as an archive and customize and extend the code as necessary.
  • Any PHP application may use Oro component(s) as a third party library. In a similar way, Oro packages may be embedded into any PHP application as ready-to-use features. Create your own application from scratch and add Oro packages as composer dependencies. Keep reading for more information about composer dependency manager.

Distribution Model

Oro application uses composer as an application-level dependency manager. It was selected for being massively used and highly popular with the PHP development community.

With composer, you can manage dependencies by editing the composer.json file (see composer.json sample and composer documentation for more information).

Every Oro application contains a composer.json file in the application root directory.


Note that installation requires composer.json file to define the package dependencies and the minimal required version for every package. However, with a composer.lock which is a file that is created as an artifact after the installation, the package dependencies may be additionally locked to the exact package version per package. This is used to avoid unexpected behaviour that may occur whenever the newer version of the package diverges from the older version and introduces changes to the critical features.

The required packages (dependencies) are listed in the following way:


"require": {
     "oro/crm": "2.x-dev",
     "oro/platform-serialised-fields": "2.x-dev",
     "oro/crm-hangouts-call-bundle": "2.x-dev",
     "oro/crm-abandoned-cart": "2.x-dev",
     "oro/crm-magento-embedded-contact-us": "2.x-dev",
     "oro/crm-mail-chimp": "2.x-dev",
     "oro/crm-dotmailer": "2.x-dev",
     "oro/crm-zendesk": "2.x-dev"


Oro packages are registered in the Packagist and OroPackagist which enables their installation (in CLI or IDE) via composer.

These packages may be registered at:

For registration, Oro application or package submits the metadata to the composer using composer.json file located in the root directory of the application/package source code in the github repository:

"name": "oro/commerce-crm-application",
"description": "OroCommerce - an open-source Business to Business Commerce application.\\This package contains a sample application.",
"license": "OSL-3.0",
"authors": [
    "name": "Oro, Inc",
    "homepage": ""

After registration, the package is listed in the Packagist and OroPackagist. You can browse registered OroInc packages at

Note: The package links to the package source code repository and may also contain information about the package required dependencies, configuration, scripts that should be executed during the package installation (e.g. post-install and post-update scripts), etc. You may use the package as a dependency in your custom application, like Oro applications use Oro packages.

See sample composer.json .

File System Structure

Oro PHP Application File System Structure

From a file system perspective, Oro PHP application contains a structured combination of configuration and initialization files used to build application source code. Typically, Oro application folders are organized in the following way:

  • app folder – application initialization and requirements validation files

    • attachment – files uploaded to the application as attachments
    • bin – scripts for application maintenance
    • cache – framework and application cache files
    • config – configuration files
    • import_export – files generated during data import and export
    • logs – application logs
    • Resources – base application templates and translations
  • src folder – application customizations source code

  • vendor folder – code of 3rd party vendors installed based on dependencies definition in composer.json.

  • web folder – web server root directory

    • bundles – static assets created based on packages assets dependencies and bundles public resources
    • css – CSS files generated based on bundles Resources/config/oro/assets.yml definitions
    • images – images pre-processed by Symfony Assetic and optimized for web
    • js – javascript files generated based on application packages source code: routes, translations, minified files etc.
    • media – folder for application media (images) cache generation
    • uploads – writable folder for user’s files upload
  • composer.json file – applications dependencies definition

  • composer.lock file – initialized dependencies list for dependencies installation

  • file

Oro Package File System Structure

A package contains a reusable code for Oro applications. During the Oro application installation, the package code is installed in the vendor folder of the application and should not be modified by customization as it is overwritten with the original version upon the system upgrade. The source code of the package includes:

  • composer.json file with package metadata that includes package definition and dependencies.
  • LICENSE – license information
  • file with detail description of the package
  • Folders with the source code organized into implementing package functionality. Package source code can be organized in a different ways and typically defines one or more Bundle, Bridge and/or Component.

It is recommended to include additional files, like:

  • – information about upgrading from old version of the package to new one
  • – list of changes made in the package since previous version
  • phpunit.xml.dist – template of phpunit.xml which can be used to run package tests
Browse maintained versions: