High-Level Architecture of the Main Framework Used in the Application
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.
{% embed url="https://miro.com/app/embed/uXjVKiE9qtw=/?embedId=366443778390&frameId=3458764605680580664&pres=1" %} the MEDomics platform detailed architecture {% endembed %}
Before contributing to MEDomics, we highly recommend you take a look at our coding standards.
{% hint style="info" %} Contributing to MEDomics is done through our GitHub development branch! {% endhint %}
Follow the installation instructions depending on your OS for MongoDB Installation.
{% tabs %} {% tab title="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. {% endtab %}
{% tab title="Linux" %} Install MongoDB on Linux (Ubuntu) - Install the latest version of MongoD. {% endtab %}
{% tab title="MacOS" %} Install MongoDB Database Tools on Mac - Install with Homebrew. {% endtab %} {% endtabs %}
Follow the instructions depending on your OS for MongoDB Database Tools Installation.
{% tabs %} {% tab title="Windows" %} Install with the MSI Installer. {% endtab %}
{% tab title="Linux" %} Install with the DEB package. {% endtab %}
{% tab title="MacOS" %} Install with Homebrew. {% endtab %} {% endtabs %}
nvm install lts
nvm use lts
{% hint style="warning" %} Be careful, the next steps are different depending on the user's privileges. {% endhint %}
For members of the MEDomicsLab GitHub organization
Using HTTPS:
git clone -b develop https://github.com/MEDomicsLab/MEDomics.gitUsing SSH:
git clone -b develop git@github.com:MEDomicsLab/MEDomics.git- Download the latest stable release of Go from the official website: https://golang.org/dl/
- Follow the installation instructions for your operating system.
Execute these commands in the terminal:
| Windows | Linux and MacOS |
|---|---|
| |
After, close all your terminals because these commands will take effect on the initialization of any terminal
In a new terminal, run:
go versionIf Go is installed correctly, you should see the version number printed to the console.
cd <repo-path>/go_server
go run main.go # initial run installs dependencies
Next, build the executable:
go build main.go
{% hint style="warning" %}
Rebuild after any .go file modification.
{% endhint %}
cd <.../MEDomicsLab/>
git checkout dev_lab
cd ../MEDprofiles
git checkout fusion_MEDomicsLab
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- Follow the project structure
- Keep commits small and descriptive
git add .
git commit -m "feat: add new feature X"Commit naming conventions:
feat:new featurefix:bug fixdocs:documentation changesrefactor:code restructuringtest:tests added/updated
git push- Go to the MEDomics GitHub Pull Requests page
- Click New Pull Request
- Target branch:
develop - Compare branch:
your-branch-name
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)
- Address reviewer comments
- Push updates to the same branch
- Keep discussion professional and concise
git checkout develop
git pull
git branch -d feature/your-feature-name # Time for a new featureFor external users
This workflow is recommended for external contributors.
- Go to the official repo
- Click Fork
- Clone your fork:
git clone https://github.com/<your-username>/MEDomicsLab.git
cd MEDomicsLabgit remote add upstream https://github.com/MEDomicsLab/MEDomicsLab.gitVerify:
git remote -vAlways branch from develop:
git fetch upstream
git checkout develop
git pull upstream develop
git checkout -b feature/your-feature-name- Download the latest stable release of Go from the official website: https://golang.org/dl/
- Follow the installation instructions for your operating system.
Execute these commands in the terminal:
| Windows | Linux and MacOS |
|---|---|
| |
After, close all your terminals because these commands will take effect on the initialization of any terminal
In a new terminal, run:
go versionIf Go is installed correctly, you should see the version number printed to the console.
cd <repo-path>/go_server
go run main.go # initial run installs dependencies
Next, build the executable:
go build main.go
{% hint style="warning" %}
Rebuild after any .go file modification.
{% endhint %}
- Follow the project structure
- Keep commits small and descriptive
git add .
git commit -m "feat: add new feature X"Commit naming conventions:
feat:new featurefix:bug fixdocs:documentation changesrefactor:code restructuringtest:tests added/updated
Before pushing:
git fetch upstream
git rebase upstream/developgit push origin feature/your-feature-name- Go to your fork on GitHub
- Click Compare & Pull Request
- Target branch:
develop(base repo)
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)
- Address reviewer comments
- Push updates to the same branch
- Keep discussion professional and concise
git checkout develop
git pull upstream develop
git branch -d feature/your-feature-name{% code fullWidth="false" %}
cd <repo_path/MEDomics>
npm install
npm run dev
{% endcode %}
{% hint style="warning" %}
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{% endhint %}
{% hint style="info" %} 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/{% endhint %}
{% hint style="info" %}
- Go to file
medomics.dev.js - 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;{% endhint %}
{% tabs %} {% tab title="Windows" %}
npm run build:win # build and package the application
.\build\dist\win-unpacked\MEDomics.exe # Run the executable of the built version{% endtab %}
{% tab title="Linux" %}
npm run build:linux # build and package the application
bash build/dist/linux-unpacked/medomics-platform # Run the executable of the built version{% endtab %}
{% tab title="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 {% endtab %} {% endtabs %}
The built app will be located in the build/dist folder.