Architecting a Phoenix Monolith for Multiple Teams: Contexts vs. Umbrella?

Phoenix Forum Questions / Help
, , ,
1

Hello everyone,
I’m currently the sole developer on a Phoenix/Elixir application (a cybersecurity platform). It’s a standard monolith with a core authentication system and a shared root layout.

We are now scaling the team by adding two new, separate teams to build two new, distinct modules.

My goal is to structure the project so that these teams can work autonomously on their modules, but still leverage the existing authentication (Plug) and the root.html.heex layout seamlessly.

I’m considering two main approaches:

  1. Stricter Bounded Contexts: Keep the single monolith structure but enforce very strong boundaries between Phoenix contexts. Each team would own their context (/lib/my_app/module_a, /lib/my_app/module_b).

  2. Umbrella Project: Migrate to an umbrella structure with a core app (for the Repo, Accounts), a web app (for Phoenix endpoints, router, layout), and a separate app for each new module (/apps/module_a, /apps/module_b).

My questions are:

  • What are the main pros and cons of each approach for this specific scenario (2 new teams, shared core)?

  • Is the upfront complexity of an Umbrella project justified for this scale, or is it overkill?

  • Are there best practices for Git workflows (e.g., code ownership, PRs) that pair well with either structure to minimize team conflicts?

Thanks for any advice!

2

I’d stick with 1, mostly because of the drawbacks of 2 (link).

As the project evolves, I bet that you’ll have some overlap. And when (and if) that comes, I’d rather that barrier be a small one rather than a larger one. I’m not great at seeing the future though, but I’m also transparent that I don’t know it… :slight_smile: . With these decisions, it’s usually good to defer the decision by choosing something trivial to reverse. Options 1 allows you to do option 2 or 3 or 4 later on, while option 2 and above don’t allow you do go back to option 1 trivially.

I’ve yet to see a better approach than using contexts with discipline (in short, everything goes through a context module). There are some tools that make it a tech barrier rather than an administrative one, but I have found that if leaning on the administrative one (discipline, having good conversations/discussions, sharing approaches) yields better returns later on, not just in code, but everything on the team.

Please report back when this is done, I’m sure you will have lots of takeaways and we can all learn from it. Congrats on the success! :heart:

4 Likes
3

pdgonzalez872 Thanks for your attention, Now it s clear in my mind.

Thanks a lot!!

1 Like