Just a note for both of you: these are called umbrella projects. It still consists of multiple apps, that are sorta separated.

In fact, umbrella project is just a shared configuration + some sugar to allow running mix teasks from the top directory.

For the guidelines, I would say that if you have a Phoenix project, you want to have at least 2 apps in it (wrapped in an umbrella project or manually connected). One app is for the web UI, another one is for business logic, all your services etc. You might have another app for administrator panel UI too, so you end up with 2 UI apps (Phoenix) + one pure Elixir app (that has Ecto). You might also want to extract the database access layer to own app and move ecto there, but I do not think it’s required in most cases.

Then, whenever you have a fairly stand-alone part of the system, for example a set of functionality that handles file uploads and processing: it makes sense to make it another app.

The rule of thumb when asking “if this should be an app or a module/namespace/context”, is this for me: “is it possible I will need to replace this thing as a whole in the future”? For UI front-end that might be “yes”, as the big re-design might happen. I might want to run 2 of UI interfaces in parallel in fact for some time, so it makes a lot of sense to make it an app. I might want to migrate from AWS to Google Cloud, so my file uploads app might also need to be replaced. I might have more than one admin panels, or replace it with something else like an API etc.

BTW, an API app might be a good idea to have too. It’s likely the API and UI will live their lives in parallel, and you might do very well with having an ui, core, admin, uploads and api apps, for example.

Umbrella apps is just a way to write OTP applications but in the same project. The alternative to umbrella apps is to have a regular OTP application but in a stand-alone repository. The other difference between a stand-alone OTP application and umbrella OTP application is that the umbrella applications are usually more coupled and depend on other applications in the umbrella. Therefore it is easier (according to some) from a project management point of view to have them all in the same project.

An OTP application is generally the same as a software library in another language, so they should have a clearly defined boundary to hide implementation. For erlang they also have their own supervision tree and can be started and stopped and upgraded as a unit (they don’t have to have a supervision tree, they can be a library as well).

Contexts are also a way to define clear boundaries between your code components. It is however orthogonal if they are in a separate OTP application or in the same.

Hence, a Context can be “moved” from one place or another if it makes sense from an OTP point of view. For example, initially you may have a module doing something like. Event.schedule_event(...). Event is a context. Then you grow your application and you add caching, notifications and other fancy stuff inside the Event context, so much that it warrants its own supervision tree. Then you can “move” this context to another OTP application, which can be an umbrella application.