I’ve worked on a number of big Phoenix/Elixir applications. I led the development of a big one (200k+ lines) over 4 years. We did it both ways, the way phoenix boilerplate does it for about 2 years, and then we reorganized it. The main thing we learned was to organize your project around features, not functionality. Why? Because which is more common? working on all your tests at the same time? or all your controllers, views, or graphql code at the same time? Or, working on a particular feature? Sometimes you do refactor something across an entire category of functionality, but WAY more often you or someone maintaining your code is working within a feature/resource/group of resources. So here’s how we did it, and we never ever looked back. It it insanely amazing and other people who have worked on our project have commented on how much easier it is to work on a feature and find all the relevant modules they need.

lib/
  invoices/
    controller_tests/
      index_test.exs
      create_test.exs
      update_test.exs
      delete_test.exs
    controller.ex
    view.ex
    view_test.exs
    schema.ex
    schema_test.exs
    jobs/
     send_invoices.ex
     send_invoices_test.exs
  payments/
    controller_tests/…
    schema.ex
    …
  customers/
    …

We tore a page from golang and we put the tests right by the modules they test. This is so great. Why do we do all the work to build a mirror of our project dir in the test? Tests are code, they are part of our app. This also makes modules that are not tested stand out like a sore thumb. Need to update a module and the test? They are right by each other!

Anyway, I was stuck in analysis paralysis about this, asked the elixir community in slack if I should do this, they all advised against this, but this project has had this structure for 2 years now and I will be doing all projects like this in all languages/frameworks from now on. It is nonsense to organize your project by functionality (controller/view/etc) rather than feature/type/resource. I don’t know rails why ever sent us down that route.

Lastly, when you want to split it up into umbrella apps or microservices, this directly structure is exactly how you’ll want t do it, you’ll just copy the directory wholesale into another app/service/etc. This organization very very much helps facilitate a domain driven design mindset.

I highly highly recommend this

One question first, is this for fun or profit?

Fun
Just experiment, take a look at the source code from changelog.com and hex.pm (search on github) and build what you think works for you and post it here for others to look at and help you with. It’s very easy to refactor in Elixir and you’ll learn a ton in the process.

Profit
Just build it with the default settings and ship it. No matter how you structure your app, if you don’t ship it it does not matter.

ultimately, because of how elixir modules don’t care about file location, elixir projects are extremely easy to re-organize. took me 2 hours to totally reorganize our project. So, just do whatever you like and if you realize later you want to do it another way, its super easy to change.

we did start moving to contexts with phoenix 1.4 come out and put them in payments/context.ex

so we had a shared directory that had child resources that had no clear home. so maybe shared/cloud_files/schema.ex (and others like context.ex). Cloud files being an abstraction of files stored on s3 or something. A lot of places in the app may use uploaded files.

So with tests, it works better than you may assume. None of those concerns you pointed out end up being a concern. I really think you should give it a shot and see.

we do still have a test directory that holds all the test support stuff (like test/support and fixtures, factories, etc)

If you only include your tests in lib and modify your mix.exs like this: test_paths: ["test", "lib"], because they are _test.exs files, they are ignored and not compiled into builds or releases.

I wrote a post where I examined and discussed a few different Elixir project directory structures:

http://blog.brian-underwood.codes/elixir/2020/07/17/structuring-an-elixir+phoenix-app/

The main thing I learned (as has been discussed here) is that Elixir is pretty flexible, so you should do what makes sense. But it’s nice to see how different things are organized.

I’m definitely intrigued by @atomkirk’s project structure, as well!