Monorepo vs Submodules: Linking Frontend and Backend Repositories - JU-DEV-Bootcamps/ERAS GitHub Wiki

This report outlines two approaches to linking frontend and backend repositories for the ERAS project. Each method is detailed with its steps, pros, cons, and implications for the team.

Approach 1: Monorepo (Unified Repository)

In the Monorepo approach, the frontend and backend codebases are combined into a single repository, with separate directories for each component.

Implementation Steps

Create a New Repository:
- Create a GitHub repository called eras-project.

Merge Repositories:

Clone the new repository:

git clone https://github.com/username/eras-project.git
cd eras-project

Add the frontend repository:

git clone https://github.com/username/frontend-repo.git frontend

Add the backend repository:

git clone https://github.com/username/backend-repo.git backend

Push Changes:

Commit and push the merged repositories:

git add .
git commit -m "Added frontend and backend repositories"
git push origin main

Pros

Simplified Management: Single repository simplifies version control and tracking.
Streamlined CI/CD: Easier to create unified CI/CD pipelines for both frontend and backend.
Team Collaboration: Developers can see and work on the full project stack in one place.

Cons

Shared History: All commits are part of a single commit history, which can become cluttered.
Potential Conflicts: Increased likelihood of merge conflicts due to all changes in one repository.

Approach 2: Submodules (Linked Repositories)

In the Submodule approach, the frontend and backend repositories are kept separate but linked as submodules within a parent repository.

Implementation Steps

Create a New Repository:
- Create a GitHub repository called eras-project.

Link Submodules:

Clone the new repository:

git clone https://github.com/username/eras-project.git
cd eras-project

Add the frontend as a submodule:

git submodule add https://github.com/username/frontend-repo.git frontend

Add the backend as a submodule:

git submodule add https://github.com/username/backend-repo.git backend

Push Changes:

Commit and push the submodules:

git add .
git commit -m "Added frontend and backend as submodules"
git push origin main

Update Submodules:
- Initialize and update submodules whenever needed:
```
git submodule update --init --recursive
```

Pros

Independent Histories: Frontend and backend retain their own commit histories, reducing clutter.
Flexibility: Teams can work independently on each repository.
Specific Deployment Pipelines: Separate CI/CD pipelines can be maintained for frontend and backend.

Cons

Complex Setup: Developers need to handle submodules with extra commands (git clone --recurse-submodules).
Synchronization Overhead: Updating or initializing submodules requires additional effort.

Comparison

Criteria	Monorepo	Submodules
Ease of Use	Simple for most workflows	Requires knowledge of submodules
Commit Management	Unified history	Separate histories
Collaboration	All developers work together	Teams work in silos
Conflict Resolution	Increased conflicts	Less frequent conflicts
Setup Complexity	Minimal	Moderate
CI/CD Flexibility	Unified pipeline	Separate pipelines

Recommendation for the ERAS Team

Monorepo: Best suited if the team prefers simplicity, unified workflows, and minimal setup effort.
Submodules: Ideal if the team values separation of concerns, flexibility, and independent deployment pipelines.

Sure, here is the content rewritten in proper Markdown format:

Example scenario: Updating an API and the Front-End

Imagine you’re tasked with updating the back-end API to include a new endpoint (/user/profile) and then updating the front-end to use that endpoint. Here's how the process looks in each approach.

1. Using a Monorepo

Setup

Both front-end and back-end are in the same repository under different directories:

/monorepo
  /frontend
  /backend

Workflow:

Create a New Branch:
```
git checkout -b feature/update-user-profile
```
This branch contains both front-end and back-end changes.
Make Changes:
- Back-End: Add the new /user/profile endpoint in /backend.
- Front-End: Update the API call in /frontend.

Stage Changes:

git add frontend/src/api/userProfile.js backend/routes/user.js

Commit and Push:

git commit -m "Add user profile endpoint and update front-end call"
git push origin feature/update-user-profile

Pull Request: Submit a single pull request (PR) for the feature. Both back-end and front-end changes are reviewed together.

Advantages:

Single branch for the ticket simplifies tracking.
CI/CD tests both parts of the system in the same pipeline.
Easy to ensure the front-end and back-end changes are compatible.

2. Using Git Submodules

Setup

The front-end and back-end are in separate repositories:

/frontend-repo
/backend-repo

You add them as submodules in a parent repository or work with them directly.

Workflow:

Clone and Set Up Submodules (if needed):

git clone <parent-repo>
git submodule update --init --recursive

Switch to the Back-End Repository:

cd backend-repo
git checkout -b feature/update-user-profile

Make Back-End Changes:

Add the /user/profile endpoint.

git add routes/user.js
git commit -m "Add user profile endpoint"
git push origin feature/update-user-profile

Switch to the Front-End Repository:

cd ../frontend-repo
git checkout -b feature/update-user-profile

Make Front-End Changes:

Update the API call.

git add src/api/userProfile.js
git commit -m "Update front-end call for user profile"
git push origin feature/update-user-profile

Pull Requests:
- Submit separate pull requests: one for the back-end and another for the front-end.
- Ensure both PRs are reviewed and merged simultaneously to avoid inconsistencies.

Advantages:

The repositories remain independent, making it easier to version and deploy them separately.
Allows working on only the part of the project you need (e.g., just the back-end).

Key Differences in Workflow

Aspect	Monorepo	Submodules
Branching	Single branch for both parts of the change.	Separate branches in different repositories.
Staging Changes	One `git add` for both front-end and back-end.	Multiple `git add` commands in separate repos.
Commits	One commit contains both front-end and back-end changes.	Separate commits for front-end and back-end changes.
Pull Requests	Single PR for the entire feature.	Separate PRs for each repository.
Code Review	Reviewers see changes in one place.	Reviewers need to coordinate across repos.
Testing	Unified CI/CD pipeline runs all tests.	Separate pipelines for each repository.

When to Choose Each Approach

Monorepo

Best if the front-end and back-end are tightly coupled.
Simplifies ticket tracking and ensures atomic changes.

Submodules

Better if the front-end and back-end are managed independently.
Suitable for teams with distinct areas of responsibility or separate lifecycles.

Resources and Documentation

Below are the resources used to gather information and examples about Monorepos and Git Submodules:

What is a Monorepo and Why Use One? - Aviator - This article explains what a Monorepo is, the benefits of using one, and its impact on development teams.
Monorepos - Atlassian - A detailed guide on Monorepos, how to set them up, and best practices for managing them.
Git Submodule Tutorial - Atlassian - A tutorial on using Git submodules with practical examples and common scenarios.
Using Git Submodules - Gist by Gitaarik - A practical and simplified example of how to work with submodules in projects.
Git Tools: Submodules - Official Git Documentation - The official Git documentation offers an in-depth explanation of submodules, their purpose, and advanced usage scenarios.
Monorepo.tools - A comprehensive resource for learning about Monorepos, including comparisons, tools, and implementation guides.