Phoenix 1.3 generated folder structure

Firstly want to thank you all for the brilliant work you have done, really exciting!

I would like to ask a question about design decisions regarding the generators in Phoenix 1.3.

Generating a Phoenix project from scratch nests the web folder is in the lib folder beside any contexts we create, an umbrella project gives two folders - the main folder presumably to house contexts and the web folder which is a dependency.

My question is why does a standard phoenix project and a phoenix project generated as part of an umbrella differ in structure?

If I generate a phoenix umbrella project from scratch, should I generate additional phoenix umbrella projects outside of the original umbrella then move the second_app and second_app_web folders into the original umbrella project or generate a standard phoenix app from within the original umbrella project with the nested web folder?

Maybe it’s just a matter of preference and has no intended design purpose or functional difference?

I know the question sounds convoluted and I may well have missed something extremely obvious, so apologies in advance should the question turn out to be an inane one.


I’m not sure I follow the question entirely, but I think you are wondering why there is app/lib/web in a single app, and no app_web/lib/web in an umbrella app? In this case, the “web” namespace is redundant since the phoenix umbrella project is the web interface and nothing more. Does that answer your question?


Hello Chris,

No that wasn’t what I meant. I think I understand most of the conceptual reasoning behind Phoenix being a web interface for my larger app, what I’m asking is a few things really -

Why is an app generated as part of an umbrella two separate apps namely my_inner_app and my_inner_app_web, when a normal phoenix app is housed in a folder on it’s own with it’s web interface nested in lib - why do they differ in structure?

Should additional phoenix apps (with phoenix as the web interface) added to the app folder of an umbrella project be of the standard type (one folder nested web interface) or the same structure as a phoenix app generated as part of an umbrella project e.g. second_inner_app and second_inner_app_web?

Have included a screenshot with the standard app on the left and the umbrella app middle and right -

An example (pre phoenix 1.3) of a use case using two phoenix apps is Wojtek Mach’s which has two web interfaces backoffice and bank_web with a master_proxy to proxy requests to each of them.

I’m presuming that because we can structure the folders however we like it’s up to us to decide but was wondering if there is any particular difference trying to be portrayed? Or perhaps there should only be one web interface per project whether standard or umbrella?




@tomgosling88 Are you talking about this?


@zimt28 Yes pretty much, except I’m not suggesting that the web folder and contexts not be nested at the same level as per the standard app (although it may be a good idea) - I’m more wondering why there is a difference in structure between a phoenix app generated as part of an umbrella and a standard one.

I am under the impression that the generators are mainly to be used as a teaching tool hinting how to architect phoenix applications and screaming their intent, so I am wondering what the intention is behind splitting an app into two folders when generated as the basis of an umbrella and as a single folder when generated as a standard or additional app to be moved under an umbrella.

1 Like

I’m still having issues understanding the question, but they differ in structure because the umbrella app approach intentionally generates two isolated applications. One for your application domain, and one for the web interface. So in order to who have two different applications in apps/, we generate separate mix projects, and those follow the standard conventions of any other project generated with mix new foo_web. If your question is why isn’t the dir structure my_umbrella/apps/web, it’s because the folder name for umbrella apps is the otp app name, namely :my_app, and my_app_web.

1 Like

My question wasn’t why isn’t the dir structure my_umbrella/apps/web - that would mean there would be only one web interface per umbrella project.

I’ll try and put it another way - why does the umbrella approach generate two isolated applications and the standard approach differ by generating one? If I started with a standard app and then decided to move it under an umbrella should I divide it into two isolated applications and vice versa?

1 Like

Single applications and umbrellas both have their own merits and pros/cons. We don’t generate an umbrella by default for Phoenix because it may be overkill and it introduces more decisions and overhead for folks to know. Umbrellas exist to house multiple isolated applications under a single code repo, that can be started and stopped as a whole or independently. This is a great for a number of reasons, but also introduces complexity depending on your needs. For example, for the mix --umbrella case you now have three places to configure things, three places to add new deps, three mix.exs files, etc. Our goal w/ the new structure for single applications where you are focusing on boundaries and isolation is the moment you need to extract the web interface or other parts of your single app to a separate umbrella app, it’s just a matter of cd apps/ && mix new whatever then moving the code around. Little else should need refactored provided your boundaries are well established. Does that help?


Yes I get it now, the decision to keep the web folder at the same level as each context in a standard app is to keep things simple for that use case where the contexts share a data source and there is no need for separating them out into isolated apps, but in theory it would also be pretty easy for a context to become an independent app with it’s own interface under an umbrella should I need it to at a later date.

Cheers Chris :slight_smile:

1 Like

Also, if you want a regular phoenix structure in an umbrella you can do:

mix new my_umbrella --umbrella
cd my_umbrella/apps
mix web_app

to add on top of Michał’s answer, v1.3.0-rc.0 actually ships with two new tasks [1], so you can do the following:

mix new my_umbrella --umbrella
cd my_umbrella
mix myapp
mix myapp_web

and they’ll generate the child apps as if they were generated with mix --umbrella.

Please note these tasks are still private (no @shortdoc hence they don’t show up in mix help), I think they’re still under development so I wouldn’t count on them being present in the final release just yet.



Brilliant! I think I must have missed the task and it threw me why I couldn’t generate additional apps to match the structure of the inner app created by mix --umbrella.

1 Like