---
schema: rendered-html/v1
title: "YouTrack App Architecture | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/app-architecture.html
generated_at: 2026-06-11T15:01:33.622980+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- Get Started with Apps
- App Quick Start Guide
- Apps FAQ
- Enhanced DX for TypeScript Apps
- [YouTrack App Architecture](app-architecture.html)
- App Package Overview
- App Manifest
- Widgets
- App Settings
- Extension Properties
- App Permissions
- Authentication for Apps
- App Visibility
- Global and Project Scopes
- [Launch Checklist](jetbrains__com__help__youtrack__devportal__app-launch-checklist.md)
- App Use Cases
- App Reference
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. Apps
2. Get Started with Apps
3. [YouTrack App Architecture](#0)

# YouTrack App Architecture﻿

Last modified: 07 May 2026

The runtime environment for YouTrack apps facilitates seamless integration and extension of YouTrack’s capabilities using modern JavaScript. Apps run in a sandboxed environment to ensure security and stability while allowing interaction with YouTrack entities such as issues, users, and projects through well-defined APIs.

[![A diagram that represents the environment for running apps in YouTrack.](https://crawler.prototype.prolicht.digital/l/DNm8ux)](https://resources.jetbrains.com/help/img/youtrack/apps-runtime-environment.png)

The environment for running apps in YouTrack consists of several components that are described here.

## Frontend Sandbox Environment﻿

The YouTrack frontend contains a sandboxed environment for running app widgets. This sandbox is implemented as an IFrame with a `sandbox` attribute, which isolates its internal code from the host environment. YouTrack supplies this sandbox IFrame with a limited set of APIs to facilitate communication with the rest of the frontend as well as with the backend application.

These IFrames let you embed another HTML document into the YouTrack UI for presenting customized content. The content inside the IFrame is isolated from the frontend. This means the CSS and JavaScript used to display information in YouTrack's frontend do not affect the IFrame content directly and vice versa.

This isolation comes with both advantages and disadvantages. On the positive side, it enhances security and prevents interference between different web components. However, it also means that the information displayed by apps might not always be visually synchronized with the rest of the user interface. To ensure that your custom views have a similar look and feel to the parent app, we strongly recommend that you build your widgets using components from JetBrains' open-source [RING UI library](https://github.com/JetBrains/ring-ui).

This environment allows for extensive customization of the YouTrack UI, letting you add custom panels, controls, and views that enhance the user experience. These customizations can be accessed through predefined extension points. For a complete list and a description of each available extension point, see Extension Points for Widgets.

> ### warning
>
> Local Storage
>
> To minimize security risk and potential data loss, the frontend sandbox is not allowed access to client-side browser APIs. Specifically, this means apps are unable to access the `localStorage`, `sessionStorage`, web cookies, and other data stored in the local environment.
>
> Apps are allowed to store and access data by:
>
> - Using the YouTrack REST or Workflow APIs to retrieve and update properties of core entities, like issues and articles.
> - Declaring app-specific extension properties to store custom values for core YouTrack entities. For details, see Extension Properties.
> - Provisioning global storage in the database. For details, see Extension Properties.

## API Layer﻿

YouTrack uses a RESTful API to facilitate communication between the frontend and the backend application using standard HTTP methods. A subset of the HTTP methods used by the application are also exposed for use by apps. The Host API lets apps send HTTP requests to YouTrack or communicate with it using YouTrack APIs. It also lets apps communicate with custom HTTP handlers stored in the backend.

The sandboxed code is also capable of making HTTP requests to third-party services.

## Backend Sandbox Environment﻿

Like the frontend application, the YouTrack backend application also contains a sandbox. Here, the sandbox operates as a GraalVM engine, enabling the execution of JavaScript code in an isolated environment. This backend sandbox is responsible for running workflow rules and HTTP handlers.

The backend is equipped with an API that allows these components to access the database. This gives an app access to read and store data in core entities, like issues and articles. It also lets an app read and store data in its own global storage.

### Workflow Rules﻿

The backend sandbox contains a dedicated runtime environment for workflows. This lets you extend and automate YouTrack functionality and behaviors using JavaScript. Workflow rules are an internal extension point for apps that allow interaction with YouTrack entities in response to specific events or conditions.

> ### note
>
> Workflows Versus Apps
>
> Workflows are event-driven triggers that let you implement custom business logic in YouTrack. This means you can automate updates in response to changes in field values, states, or on a set schedule. You can also extend the user interface by adding custom actions that are triggered manually by users but run logic on the backend. There's even a module that lets you establish connections and send requests to external sites.
>
> If you're looking to build a solution that only relies on workflow rules, these can be written and stored directly in YouTrack. If you don't plan to use any of the frontend extension points to customize the user interface, you can save yourself a lot of time and effort by working exclusively with the workflow engine.
>
> You can always package a group of workflow rules and publish them as an app or include a set of workflows in an app package alongside widgets for other extension points. When this happens, these workflows are identified by the app that provides their functionality in the workflow list.
>
> To learn more about workflows in YouTrack, see JavaScript Workflow Quick Start Guide.

- To learn how to add a workflow rule to your app, see JavaScript Modules.
- For help writing workflows in JavaScript, read our JavaScript Workflow Quick Start Guide.

### HTTP Handlers﻿

YouTrack's backend sandbox environment provides support for custom HTTP handlers. This lets you expose additional endpoints to interact with external systems or custom apps. These handlers allow you to define server-side logic that responds to specific HTTP requests and operates within YouTrack's sandboxed environment. This functionality is a key extension point for integrating other tools or creating custom interactions with the REST API.

For further information, see HTTP Handlers.

## Data Storage﻿

Apps are able to provision global storage in the YouTrack database. This lets apps dynamically store and retrieve app-specific data in isolation from other entities defined by YouTrack.

To learn how to set up dedicated data storage for your app, see How to Use Extension Properties.

- [YouTrack App Architecture](/help/youtrack/devportal/app-architecture.html)
- [Frontend Sandbox Environment](/help/youtrack/devportal/app-architecture.html#front-end-sandbox)
- [API Layer](/help/youtrack/devportal/app-architecture.html#app-api-layer)
- [Backend Sandbox Environment](/help/youtrack/devportal/app-architecture.html#backend-sandbox-environment)
- [Data Storage](/help/youtrack/devportal/app-architecture.html#app-data-storage)

Enhanced DX for TypeScript AppsApp Package Overview

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
