💻Contributing

High-Level Architecture of the Main Framework Used in the Application

The MEDomics platform architecture

The map below illustrates the organization of files, modules, databases, and the Frontend-Backend connection within the MEDomics platform. This visual guide is designed to support new contributors in understanding the application’s structure, streamlining the integration of new features, and aiding efficient navigation through the codebase.

the MEDomics platform detailed architecture

Contribution Standards Summary

Before contributing to MEDomics, we highly recommend you take a look at our coding standards.

Contribute to MEDomics 🌱

Contributing to MEDomics is done through our GitHub development branch!

1. Prerequisites

1.1 Installation of MongoDB Community Edition

Follow the installation instructions depending on your OS for MongoDB Installation.

Windows

Install MongoDB on Windows

• Do not install MongoDB as a service.

• You do not have to install MongoDB compass.

• You do not have to install mongosh.

• Do not forget to add MongoDB binaries to the System PATH.

Linux

Install MongoDB on Linux (Ubuntu) - Install the latest version of MongoD.

MacOS

Install MongoDB Database Tools on Mac - Install with Homebrew.

1.2 Installation of MongoDB database tools

Follow the instructions depending on your OS for MongoDB Database Tools Installation.

Windows

Install with the MSI Installer.

Linux

Install with the DEB package.

MacOS

Install with Homebrew.

2. Node.js and NVM Setup

2.1 Installation of Nvm

• NVM for Windows

• NVM for Ubuntu/MacOS

2.2 Installation of npm/node.js

nvm install lts
nvm use lts

Be careful, the next steps are different depending on the user's privileges.

For members of the MEDomicsLab GitHub organization

3. Clone the Repository

Using HTTPS:

git clone -b develop https://github.com/MEDomicsLab/MEDomics.git

Using SSH:

git clone -b develop [e-mail]:MEDomicsLab/MEDomics.git

4. Backend Setup (Go)

4.1 Install Go

1. Download the latest stable release of Go from the official website: https://golang.org/dl/

2. Follow the installation instructions for your operating system.

4.2 Setup of environment

Execute these commands in the terminal:

Windows	Linux and MacOS
setx GOPATH %USERPROFILE%\go setx PATH "%PATH%;C:\Go\bin"	echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc echo 'export PATH=$PATH:$GOPATH/bin' >> $HOME/.bashrc

After, close all your terminals because these commands will take effect on the initialization of any terminal

4.3 Verify installation

In a new terminal, run:

go version

If Go is installed correctly, you should see the version number printed to the console.

4.4 Setup for the application

cd <repo-path>/go_server
go run main.go   # initial run installs dependencies

Next, build the executable:

go build main.go

Rebuild after any .go file modification.

5. Initialize submodules

cd <.../MEDomicsLab/>
git checkout dev_lab
cd ../MEDprofiles
git checkout fusion_MEDomicsLab

6. Create Your Own Branch

Always branch from develop, and ensure you have the latest changes:

git checkout develop
git pull origin develop
git checkout -b your-branch-name
# push your branch to MEDomics repository
git push --set-upstream origin your-branch-name

7. Make Changes

• Follow the project structure

• Keep commits small and descriptive

git add .
git commit -m "feat: add new feature X"

Commit naming conventions:

• feat: new feature

• fix: bug fix

• docs: documentation changes

• refactor: code restructuring

• test: tests added/updated

---

9. Push Changes

git push

---

10. Create a Pull Request

1. Go to the MEDomics GitHub Pull Requests page

2. Click New Pull Request

3. Target branch: develop

4. Compare branch: your-branch-name

---

11. Pull Request Guidelines

Ensure:

• ✅ Code compiles and runs

• ✅ No console errors

• ✅ Proper formatting

• ✅ Tests pass (if applicable)

• ✅ Clear PR description:

  • What was done

  • Why was it done

  • Screenshots (if UI changes)

---

12. Code Review Process

• Address reviewer comments

• Push updates to the same branch

• Keep discussion professional and concise

13. After Merge

git checkout develop
git pull
git branch -d feature/your-feature-name # Time for a new feature

For external users

🌱 Contributing via Fork (Common Practice)

This workflow is recommended for external contributors.

---

3. Fork the Repository

1. Go to the official repo

2. Click Fork

3. Clone your fork:

git clone https://github.com/<your-username>/MEDomicsLab.git
cd MEDomicsLab

---

4. Add Upstream Remote

git remote add upstream https://github.com/MEDomicsLab/MEDomicsLab.git

Verify:

git remote -v

---

5. Create a Feature Branch

Always branch from develop:

git fetch upstream
git checkout develop
git pull upstream develop

git checkout -b feature/your-feature-name

---

6. Backend Setup (Go)

6.1 Install Go

1. Download the latest stable release of Go from the official website: https://golang.org/dl/

2. Follow the installation instructions for your operating system.

6.2 Setup of environment

Execute these commands in the terminal:

Windows	Linux and MacOS
setx GOPATH %USERPROFILE%\go setx PATH "%PATH%;C:\Go\bin"	echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc echo 'export PATH=$PATH:$GOPATH/bin' >> $HOME/.bashrc

After, close all your terminals because these commands will take effect on the initialization of any terminal

6.3 Verify installation

In a new terminal, run:

go version

If Go is installed correctly, you should see the version number printed to the console.

6.4 Setup for the application

cd <repo-path>/go_server
go run main.go   # initial run installs dependencies

Next, build the executable:

go build main.go

Rebuild after any .go file modification.

---

7. Make Changes

• Follow the project structure

• Keep commits small and descriptive

git add .
git commit -m "feat: add new feature X"

Commit naming conventions:

• feat: new feature

• fix: bug fix

• docs: documentation changes

• refactor: code restructuring

• test: tests added/updated

---

8. Sync with Upstream

Before pushing:

git fetch upstream
git rebase upstream/develop

---

9. Push Changes

git push origin feature/your-feature-name

---

10. Create a Pull Request

1. Go to your fork on GitHub

2. Click Compare & Pull Request

3. Target branch: develop (base repo)

---

11. Pull Request Guidelines

Ensure:

• ✅ Code compiles and runs

• ✅ No console errors

• ✅ Proper formatting

• ✅ Tests pass (if applicable)

• ✅ Clear PR description:

  • What was done

  • Why was it done

  • Screenshots (if UI changes)

---

12. Code Review Process

• Address reviewer comments

• Push updates to the same branch

• Keep discussion professional and concise

---

13. After Merge

git checkout develop
git pull upstream develop
git branch -d feature/your-feature-name

Run the Electron App

cd <repo_path/MEDomics>
npm install
npm run dev

On Windows, if you encounter error messages when running npm installrelated to tensorflow .dll files missing, revert your node version by following these steps:

• Download node v18.16.1

• Add to the PATH variable the path to your new node placing it higher than the old node.

• Test your node version using: node --version

MongoDB configuration

The MEDomicsLab platform uses port 54017 as the default MongoDB connection port. For database visualization and management, we recommend using MongoDB Compass, the official GUI client from MongoDB.

Key Details:

• Default Port: 54017

• Recommended Client: MongoDB Compass

• Connection String Format: mongodb://localhost:54017/

Modify startup settings

1. Go to file medomics.dev.js

2. Here is a description of the Object:

export const PORT_FINDING_METHOD = {
  FIX: 0,
  AVAILABLE: 1
};

const config = {
  // Automatically starts the backend server when the app launches
  runServerAutomatically: true,

  // Enables React Developer Tools (useful for debugging UI)
  useReactDevTools: false,

  // Default port used by the Electron/Go server
  defaultPort: 54288,

  // MongoDB connection port
  mongoPort: 54017,

  // Port allocation strategy:
  // FIX        -> Forces use of defaultPort (terminates conflicting processes if needed)
  // AVAILABLE  -> Finds the next available port if defaultPort is occupied
  portFindingMethod: PORT_FINDING_METHOD.FIX
};

export default config;

Testing Production Builds

Build & Run

Windows

npm run build:win                            # build and package the application 
.\build\dist\win-unpacked\MEDomics.exe    # Run the executable of the built version

Linux

npm run build:linux                    # build and package the application 
bash build/dist/linux-unpacked/medomics-platform  # Run the executable of the built version

Mac

npm run build:mac                                                    # build and package the application 
bash build/dist/mac-arm64/MEDomicsLab.app/Contents/MacOS/medomics-platform  # Run the executable of the built version     

The built app will be located in the build/dist folder.