This past February, ßingen (an Aragon colleague) and I attended the Ethereum Dev Barcelona meetup. After the presentations, we had the opportunity to meet with the other attendees and share our ideas. As part of the conversation, we were introduced to Jose Luis Muñoz and found out he is the director for the Master's degree in blockchain technologies at the Polytechnic University of Catalonia. We shared with him some of our day-to-day activities, and he thought it would be fun for us to showcase Aragon by proposing a lecture & workshop about it for their students. We were excited. What a thrilling opportunity!

One month later, we met up at the designated classroom and started talking about Aragon's mission. I was tasked with describing the frontend architecture that powers and runs the Aragon client, this post shares what I spoke of that day.

Aragon client

We officially call the Aragon graphical user interface the Aragon client. It is the main JavaScript app that gets downloaded when your browser requests Similar to an OS, it wraps the context where the Aragon apps get executed by offering a limited set of APIs.

The Aragon client holds the path to the Web3 provider/signer so that apps do not need to take responsibility for it (nor the pressure of doing so). It is via the client that apps can request messages to be signed, transactions to be sent, votes to be cast, and organizations to be distributed.

It has been built using React, and it is open source–in fact, everything we do at Aragon is open source.

Why did we choose React over insert-name-of-your-favorite-framework-here?

Let me quote Pierre (another Aragon colleague) here with some of the reasons why we chose React (specifically over Vue)

  1. Popularity. React is the most popular framework among developers. As a platform, we obviously want to reach as many users as possible.
  2. Nothing like react-motion existed for Vue, and having a solid animation library is an absolute necessity for the UI quality we are aiming for (we have since moved to react-spring).
  3. styled-components. At the time, there was a Vue version, but it wasn't working as well as we needed.

Yet, React is not a requirement to build Aragon apps, our bare-bones-boilerplate repo can be used as a starting point to develop Aragon apps without any framework.

Fun fact for trivia night: aragonUI was implemented in Vue up until version 0.3.0.

The Aragon client uses a sandboxed iframe to execute the apps running in an organization's context. We use this model to keep a clear distinction between what the apps can and cannot do. It is a trust-based model, and we want users to feel secure when they see apps running in the Aragon client context.

And most importantly, the client allows Aragon apps to interact with each other and be designed as composable pieces of that can execute an entire pipeline of processes. To explain how this works, let's say you are a member of an organization and want to add another member to it.

  1. You would need to mint some of the organization's tokens and give them to an Ethereum address belonging to the potential new member.
  2. Only the Token Manager app can mint the tokens, and organizations can configure who is allowed to mint new tokens. For example, it may be that the only way to mint tokens is via a new vote in an installed Voting app.
  3. The Aragon client would then show you a summary of the required actions in a panel for you to approve (by signing).
  4. The vote would start, your fellow members would vote yay, the vote would pass and,
  5. Voilà! A new member has been added thanks to the interactions of two Aragon apps via the Aragon client (and some extra sauce by aragonOS, but we will leave that for another blog post).


I've talked about Aragon Apps and named a couple of them, but before diving into that topic, let me describe the toolkit being used to build both the Aragon client and Aragon apps: aragonUI.

We use the components published in this toolkit to build the user interface that users interact with.

The toolkit has been built considering the needs of Web3 decentralized apps. That means that we've had to think of intuitive ways to solve common problems when interacting with Web3 providers and signers.

It provides out-of-the-box components such that when you need to

  • Render an address, the component includes a link to a list of transactions for that address depending on the connected network.
  • Render a balance, the component can fetch directly from a distributed ledger/blockchain using the connected Web3 provider.
  • Render the result of an asynchronous operation (like signing a transaction or casting a vote) without knowing how long it will take, then the component shows a spinner with an estimated time to finish that updates to an indefinite spinner if it takes longer than expected.
  • Make sense of an Ethereum address, then the component renders a human-readable label associated with that address.

Plus a lot more!

These components have been implemented using fantastic libraries to adhere to a very strict quality standard (for example, react-spring and styled-components). This is important for us because it allows developers to focus their time and resources on their core needs instead of having to worry about the inner performance of their components.


aragonAPI is the glue that ties everything together; like ketchup to fries–although I don't really put ketchup on fries since I'm a wine enthusiast, let me just say it provides the perfect pairing.

It is a JavaScript library that provides a controlled interface that is used by Aragon apps to

  • Communicate directly with their accompanying smart contracts (built on aragonOS).
  • Get information about the user account (like the address and the network).
  • Access/update local labels for addresses.
  • Request to sign messages.
  • Interact with the Aragon client side menu (in smaller screens it becomes hidden by default).
  • And provides the state and store for the rendered frontend.

It also provides a mechanism for Aragon apps to execute background scripts that update the app state even when the app is not being rendered. This makes for better user experience as apps maintain up to date state even if users don’t have a particular app opened.

The Aragon client uses this library too, but it uses a different interface of methods and properties. The reason for this is because the security level is different when interacting with apps inside the client.

Aragon apps

Finally, let’s dive into the Aragon apps. There are two types of Aragon apps: apps that are executed in the sandboxed iframe model mentioned earlier, and apps that are executed directly within the JavaScript context of the Aragon client (i.e., not in a sandboxed iframe context). To differentiate between them, I'll use the term External apps for the former type and System apps for the latter.

System apps

These apps are included with the Aragon client and implemented directly within the same codebase. Let’s list these apps and provide a quick description of what they do.

  • Permissions: a general mechanism to define permissions for installed apps and their interoperability–we refer to this as an organization’s ACL (Access Control List).
  • App Center: similar to an app store, a way to list and upgrade the installed apps for an organization. In the near future, an install/remove apps feature will be included.
  • Settings: displays general information about the organization and a way to configure and customize the node endpoints for IPFS and/or Ethereum.

Even though these apps are executed within the same JavaScript context as the Aragon client the way we maintain interoperability is via aragonAPI and we do so to keep a concise distinction between the layers of interaction between the client and its apps.

External Apps

These are modular apps that can be individually installed to solve real-world problems for decentralized organizations. As mentioned earlier, they are executed within the context of a sandboxed iframe.

When creating an organization using the Aragon client's Onboarding app, the organization will include four External apps by default

  • Token Manager app: allows to mint/burn an organization's token and to assign/remove them to addresses.
  • Voting app: allows members in an organization to vote on a question–which may then lead to the execution of an action based on the outcome.
  • Finance app: allows members to manage the organization's financial capital.
  • Vault app: holds the organization's resources. This app’s UI is bundled together with the Finance app.

These apps follow the model described below:

  • They are executed within a restricted context that limits the interactions these can have with the aragonOS contracts and other apps–this is done via aragonAPI.
  • They make use of the components published in aragonUI to a) interact with the Web3 world and b) to align and adhere to the same visual designs for all Aragon Apps.
  • Each app can interact with their own smart contracts, and if/when the app needs interoperability with other apps, it does so via aragonAPI.

Developing Aragon apps

This has been an initial walkthrough on our Frontend architecture. I’ll gladly dive into topics specifically in future posts, but the intention here was to open a path to understanding how and why we've taken some decisions and what developers can do with the available tools and frameworks.

Lastly, I’d like to share two more tools to help developers joining the movement towards a distributed future with decentralized autonomous organizations:


A command line tool intended to make life easier for anyone willing to test out, play around, or work on developing apps for the Aragon ecosystem.

Our developer documentation for building on Aragon. It includes a “Your first app” tutorial that guides the reader with a step by step tour on how to start developing Aragon apps.