Skip to content
Antoine Boucher

Options

Profiles

Table of contents

Maestro: Sheet music through an external conversion pipeline

This Maestro fork connects a React upload interface to a Spring backend and external music-conversion tools. Turning a score image into MIDI passes through an optical-recognition stage and an intermediate score representation.

Application and services Fork
  • Updated
  • Java · 47.34%
  • AGPL-3.0
JVM (Gradle) Node.js unittestJest / Testing LibraryJUnit Upstream credited
View source README Markdown
Documented components
2Explore modules
Source documents
3Read the instructions
Repository languagesJava 47.34%6

Shares calculated from GitHub Linguist bytes.

Java47.34%
47.34%33,471 bytes
TypeScript32.3%
32.3%22,838 bytes
Python16.02%
16.02%11,324 bytes
Dockerfile3.14%
3.14%2,222 bytes
Language%Bytes
Java47.34%33,471
TypeScript32.3%22,838
Python16.02%11,324
Dockerfile3.14%2,222
HTML1%710
Shell0.2%138

GitHubREADMELanguage statistics

1. Overview

1.1. Why it exists

Optical Music Recognition (OMR) pipeline translating sheet music scans into MIDI score sequences.

1.2. Best fit

Digitization of physical sheet music for playback and editing.

2. Use cases

Web app that turns a scanned music sheet (PDF, PNG, JPG) into a MIDI file, with optional tempo overrides.

Use-case diagram for Maestro: Upload a music sheet; Set tempos per measure; Recognize notes with Audiveris; Convert MusicXML to MIDI; Download the MIDI file; Switch English or FrenchMaestroUpload a music sheetSet tempos per measureRecognize notes with AudiverisConvert MusicXML to MIDIDownload the MIDI fileSwitch English or FrenchMusician«system»Audiveris OMR engine«system»music21 (Python)
People on the left, external systems on the right; each oval is a use case backed by the files cited below.
Upload a music sheet
Musician

The React form in maestro-app/src/pages/MusicSheetUploadForm/MusicSheetUploadForm.tsx takes a dropped file and a MIDI file name, then useMaestroClient.ts checks GET /health before posting to /convert.

Set tempos per measure
Musician

The form keeps a list of tempo, measure and force entries (default 120 at measure 1) and sends it as the JSON field tempos.

Recognize notes with Audiveris
Audiveris OMR engine

POST /convert in ConvertController.java checks the file (10 MB limit, PDF/JPG/PNG signature) and AudiverisController.java runs Audiveris in batch mode to export a .mxl file.

Convert MusicXML to MIDI
music21 (Python)

backend/src/main/MxlToMidi.py loads the .mxl with music21, applies dynamics and the requested tempo marks, and writes the .mid file.

Download the MIDI file
Musician

The backend returns the .mid as an attachment and the frontend saves it with js-file-download; input and output folders are cleaned three seconds later.

Switch English or French
Musician

LanguageSwitcher.tsx toggles i18next between en-US and fr-CA, using the strings in maestro-app/public/locales/.

2.1. Scenario: Turn a PDF score into a MIDI file locally

  1. Copy the Audiveris bin and lib folders into backend/audiveris/dist as backend/README.md explains.
  2. Start both services with docker-compose up -d (backend on port 8080, frontend on port 3000).
  3. Open localhost:3000, drop a PDF score and enter a MIDI file name.
  4. Add a tempo row, for example 90 at measure 1, and submit the form.
  5. The backend runs Audiveris, then MxlToMidi.py, and the browser downloads the .mid file.

Files readREADME.mdbackend/README.mddocker-compose.ymlbackend/src/main/java/PFE008/backend/ConvertController.javabackend/src/main/java/PFE008/backend/AudiverisController.javabackend/src/main/MxlToMidi.pymaestro-app/src/hooks/useMaestroClient.tsmaestro-app/src/pages/MusicSheetUploadForm/MusicSheetUploadForm.tsxmaestro-app/src/components/languageSwitcher/LanguageSwitcher.tsx

3. Getting started

These commands come from the repository documentation. They were not run during this review.

README.md · Getting Started 
  git clone https://github.com/PrimePhil/PFE008
README.md · Frontend 
  cd maestro-app
README.md · Frontend 
  npm install
README.md · Frontend 
  npm run start
README.md · Tests 
gradle test
Tasks declared in manifests

3.1. maestro-app/package.json

start
react-scripts start
build
react-scripts build
test
react-scripts test

4. Repository references

Excerpts from the repository’s guides, in their original language. Links open the inspected source revision.

Prerequisites and first run

4.1. Requirements

README.md

  • Audiveris
  • Java 22.0.2
  • Python 3.12
  • npm 8.19.4
  • Nodejs 18.13.0
Read the full instructions ↗

4.2. Getting Started

README.md

Start by cloning the project
Read the full instructions ↗

4.3. Prerequisites

backend/README.md

  1. Java Installation:
  • Ensure you have Java installed. The version used for this project is:
  1. Gradle:
  • The project includes a Gradle wrapper, so you don’t need to install Gradle manually. If needed, you can download Gradle here. The project uses Gradle v8.8.
  1. OCR Language Data:
  • Audiveris relies on Tesseract for Optical Character Recognition (OCR). You’ll need to install language data files. Refer to the Audiveris guide for setup instructions.
  1. Audiveris Setup:
  • The Audiveris distribution is not included in the repository. You need to download it manually and place it in the backend/audiveris/dist directory.
  • Download the Audiveris distribution (Windows installer) from here.
  • After installation, copy the bin and lib directories from the Audiveris installation directory to backend/audiveris/dist/. Your project structure should look like this:
Read the full instructions ↗
API and integration

4.4. Endpoint Overview

backend/README.md

There is currently one main route in the API:
Read the full instructions ↗
Operations and troubleshooting

4.5. Deployment

README.md

To run locally a docker-compose To build docker’s image move to the root (where the Dockerfile is) and use : When you have a docker’s image, you can run it with the command : Note : To deploy the application, you must install Docker before hand. you can also used an image already build on the offical Docker repo with the command : if you want to update this image, you can use the commands : Note : You need to be a member of the organization to push a new images.
Read the full instructions ↗
Development and contributions

4.6. Tests

README.md

To run the tests suites go into the backend repository and run the command It is important to note that the python’s tests will be executed with the gradle command
Read the full instructions ↗

4.7. npm test

maestro-app/README.md

Launches the test runner in the interactive watch mode.
Read the full instructions ↗
Source documentation

3 documents read from 3 candidates.

5. Features and components 2

Upload boundary
ConvertController accepts multipart uploads at /convert. It rejects empty files, checks the 10 MiB size limit and calls a file-signature validator before saving the input. Optional tempo input travels with the conversion request.
External processes
AudiverisController builds an OS-dependent command and waits for the Audiveris process. The backend also includes MxlToMidi.py. Process startup, intermediate files and the returned download are separate failure points.

6. Architecture

Expand a component to follow its connections, or explore the full diagram.

System components Context
Mermaid Interactive diagram

System overview of the components and connections verified in the repository.

Static architecture view for Maestro
Static preview. The interactive diagram replaces it after Mermaid loads.
flowchart LR
  n0["React file upload"]
  n1["Spring validation"]
  n2["Audiveris recognition"]
  n3["MusicXML conversion stage"]
  n4["MIDI download"]
  n0 --> n1
  n1 --> n2
  n2 --> n3
  n3 --> n4
Text version of the diagram
  • React file upload → Spring validation
  • Spring validation → Audiveris recognition
  • Audiveris recognition → MusicXML conversion stage
  • MusicXML conversion stage → MIDI download
Follow one path through the code

Follow /convert into the file checks, then inspect how AudiverisController chooses its executable and output directory. A successful HTTP upload is only the start; conversion also depends on the external tool and generated files.

7. Technical dossier

Built from the source at commit 6dca488 (38 files). Each item comes from a pattern match in the code, so open the linked file before relying on it.

7.1. Layers and modules

Folders are sorted into layers by name, from the user interface down to data access. Because the sorting uses names only, the diagram says nothing about calls between layers.

Mermaid Layered view
flowchart TB
  subgraph L_presentation["Presentation"]
    direction TB
    presentation_0["maestro-app/components<br/>5 files"]
    presentation_1["maestro-app/pages<br/>3 files"]
    presentation_2["maestro-app/src<br/>2 files"]
    presentation_3["maestro-app/i18n<br/>1 file"]
    presentation_more["+2"]
  end
  subgraph L_domain["Domain and business rules"]
    direction TB
    domain_0["maestro-app/types<br/>1 file"]
  end
  subgraph L_infrastructure["Data and infrastructure"]
    direction TB
    infrastructure_0["maestro-app/hooks<br/>1 file"]
  end
  subgraph L_core["Core source"]
    direction TB
    core_0["backend/PFE008<br/>5 files"]
    core_1["backend<br/>2 files"]
    core_2["maestro-app/src<br/>2 files"]
    core_3["(root)<br/>1 file"]
    core_more["+1"]
  end
  subgraph L_tests["Tests"]
    direction TB
    tests_0["backend<br/>4 files"]
    tests_1["maestro-app<br/>1 file"]
  end
  subgraph L_hosting["Build, CI and hosting"]
    direction TB
    hosting_0["(root)<br/>4 files"]
    hosting_1[".github<br/>1 file"]
  end
  L_presentation ~~~ L_domain
  L_domain ~~~ L_infrastructure
  L_infrastructure ~~~ L_core
  L_core ~~~ L_tests
  L_core ~~~ L_hosting
Modules and their main layer
ModuleLayerFilesTypesExtensions
backend/PFE008Core source55.java
maestro-app/componentsPresentation51.tsx .ts
maestro-app/srcPresentation40.tsx .ts
maestro-app/pagesPresentation31.tsx
backendCore source20.gradle
(root)Core source10.sh
backend/mainCore source10.py
maestro-app/hooksData and infrastructure11.ts
maestro-app/i18nPresentation10.tsx
maestro-app/mocksPresentation10.tsx
maestro-app/publicPresentation10.html
maestro-app/typesDomain and business rules10.ts

7.2. C4 model

From system context to code declarations. Each level reflects the available source evidence.

UML 1 · System context
1 · System context

The widest C4 view: who uses the project and which outside systems and data stores it relies on. Rendered with uml-mcp.

PlantUML source
@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
Person(P_http, "HTTP client")
System(SYS, "Maestro", "This Maestro fork connects a React upload interface to a Spring backe…")
Rel(P_http, SYS, "Uses")
@enduml
UML 2 · Containers
2 · Containers

One level closer: the parts that run separately inside the project, their main language and how calls flow between them. Rendered with uml-mcp.

PlantUML source
@startuml
!include <C4/C4_Container>
LAYOUT_LEFT_RIGHT()
Person(P_http, "HTTP client")
System_Boundary(SYS, "Maestro") {
  Container(C0, "maestro-backend", "Docker")
  Container(C1, "maestro-frontend", "Docker")
}
Rel(P_http, C0, "Uses")
@enduml
UML 3 · Components and layers
3 · Components and layers

Modules grouped by source-layer classification. Boundaries show organization, not runtime isolation or call relationships. Rendered with uml-mcp.

PlantUML source
@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "Maestro") {
Boundary(L0, "Presentation", "layer") {
Component(M0_0, "maestro-app/components", "React, TypeScript", "5 files")
Component(M0_1, "maestro-app/pages", "React", "3 files")
Component(M0_2, "maestro-app/src", "React", "2 files")
Component(M0_3, "maestro-app/i18n", "React", "1 files")
Component(M0_4, "maestro-app/mocks", "React", "1 files")
Component(M0_5, "maestro-app/public", "HTML", "1 files")
}
Boundary(L1, "Domain and business rules", "layer") {
Component(M1_0, "maestro-app/types", "TypeScript", "1 files")
}
Boundary(L2, "Data and infrastructure", "layer") {
Component(M2_0, "maestro-app/hooks", "TypeScript", "1 files")
}
Boundary(L3, "Core source", "layer") {
Component(M3_0, "backend/PFE008", "Java", "5 files")
Component(M3_1, "backend", ".gradle", "2 files")
Component(M3_2, "maestro-app/src", "TypeScript", "2 files")
Component(M3_3, "(root)", ".sh", "1 files")
Component(M3_4, "backend/main", "Python", "1 files")
}
Boundary(L4, "Tests", "layer") {
Component(M4_0, "backend", "Java, Python", "4 files")
Component(M4_1, "maestro-app", "React", "1 files")
}
Boundary(L5, "Build, CI and hosting", "layer") {
Component(M5_0, "(root)", "Dockerfile, .backend, .frontend", "4 files")
Component(M5_1, ".github", ".yml", "1 files")
}
}
@enduml
UML 4 · Code
4 · Code

Selected declarations, fields and methods grouped by source file. No inheritance or call edges are inferred. Rendered with uml-mcp.

PlantUML source
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
top to bottom direction
hide empty members
package "Maestro" {
package "backend/src/main/java/PFE008/backend/ConversionResponse.java" as F0 {
class "ConversionResponse" as T0_0 {
  getFileName()
  setFileName()
  getDownloadUri()
  setDownloadUri()
  getSize()
  setSize()
}
}
package "backend/src/main/java/PFE008/backend/FileUtil.java" as F1 {
class "FileUtil" as T1_0 {
  saveFile()
  getFileAsResource()
  isValidFile()
  cleanupDirectories()
  deleteFilesInDirectory()
}
}
package "maestro-app/src/pages/MusicSheetUploadForm/MusicSheetUploadFormFooter.tsx" as F2 {
class "MusicSheetUploadFormFooterProps" as T2_0 {
  canResetForm
  file
  loading
  reset
}
}
package "maestro-app/src/hooks/useMaestroClient.ts" as F3 {
class "UseMaestroClientResult" as T3_0 {
  loading
  error
  convert
}
}
package "maestro-app/src/components/musicSheetUploader/MusicSheetUploader.tsx" as F4 {
class "MusicSheetUploaderProps" as T4_0 {
  onFileChange
  file
}
}
}
@enduml

7.3. Public interface

Outside code can use everything listed here. The project also declares 8 public types.

UML Use cases
Use cases

Each actor is a kind of caller, linked to what it can ask the project to do. Rendered with uml-mcp.

PlantUML source
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
left to right direction
actor "HTTP client" as A_http
rectangle "Maestro" {
  usecase "POST /convert" as U0
  usecase "GET /health" as U1
}
A_http --> U0
A_http --> U1
@enduml

HTTP routes 2

MethodPathSource
POST/convertbackend/src/main/java/PFE008/backend/ConvertController.java:46
GET/health opsbackend/src/main/java/PFE008/backend/ConvertController.java:123

Routes marked ops expose health, status or admin endpoints; restrict them in production.

7.4. Private interface

These names are internal by the language’s conventions: a leading underscore, private, static or pub(crate).

private / internal method
2

7.5. Services

7.6. Entities and data model 3

Mermaid Entity class diagram
classDiagram
  direction LR
  class E0["MusicSheetUploadFormFooterProps"] {
    +boolean canResetForm
    +File file
    +boolean loading
    +reset
  }
  class E1["UseMaestroClientResult"] {
    +boolean loading
    +string error
    +convert
  }
  class E2["MusicSheetUploaderProps"] {
    +onFileChange
    +File file
  }

An arrow links a field to the entity its type names.

EntityKindFirst fields
MusicSheetUploadFormFooterPropsRecord or interfacecanResetForm, file, loading, reset
UseMaestroClientResultRecord or interfaceloading, error, convert
MusicSheetUploaderPropsRecord or interfaceonFileChange, file

7.7. Business logic

Once UI code and the services and entities above are set aside, these classes have the most methods.

ConversionResponse Core source, 6 methods
getFileName, setFileName, getDownloadUri, setDownloadUri, getSize, setSize
FileUtil Core source, 5 methods
saveFile, getFileAsResource, isValidFile, cleanupDirectories, deleteFilesInDirectory

7.8. External integrations

HTTP clients

fetch

7.9. Stack and dependencies

JVM (Gradle) backend/build.gradle 4 runtime, 4 dev

Open the manifest

Node.js maestro-app/package.json 27 runtime, 1 dev

Open the manifest

External dependencies

36 declared packages (31 runtime, 5 development) in backend/build.gradle, maestro-app/package.json.

Package table 36
External dependencies
PackageVersionScopePurposeRegistry
org.springframework.boot:spring-boot-starter-web—runtimeWeb frameworkcentral.sonatype.com
org.apache.commons:commons-lang3—runtime—central.sonatype.com
org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0—runtime—central.sonatype.com
org.apache.tika:tika-core:2.9.2—runtime—central.sonatype.com
org.springframework.boot:spring-boot-starter-test—developmentTestingcentral.sonatype.com
org.junit.jupiter:junit-jupiter-api:5.9.3—development—central.sonatype.com
org.mockito:mockito-core:5.2.0—development—central.sonatype.com
org.mockito:mockito-junit-jupiter:5.2.0—development—central.sonatype.com
@emotion/react^11.11.4runtime> Simple styling in React.npmjs.com
@emotion/styled^11.11.5runtimestyled API for emotionnpmjs.com
@fontsource/roboto^5.0.13runtimeSelf-host the Roboto font in a neatly bundled NPM package.npmjs.com
@hookform/resolvers^3.9.0runtimeReact Hook Form validation resolvers: Yup, Joi, Superstruct, Zod, Vest, Class Validator, io-ts, Nope, computed-types, TypeBox, arktype, Typanpmjs.com
@mui/icons-material^5.15.19runtimeUser interfacenpmjs.com
@mui/lab^5.0.0-alpha.170runtimeUser interfacenpmjs.com
@mui/material^5.15.19runtimeUser interfacenpmjs.com
@testing-library/jest-dom^5.17.0runtimeTestingnpmjs.com
@testing-library/react^13.4.0runtimeTestingnpmjs.com
@testing-library/user-event^13.5.0runtimeTestingnpmjs.com
@types/jest^27.5.2runtimeType checkingnpmjs.com
@types/node^16.18.97runtimeType checkingnpmjs.com
@types/react^18.3.3runtimeType checkingnpmjs.com
@types/react-dom^18.3.0runtimeType checkingnpmjs.com
i18next^23.11.5runtimei18next internationalization frameworknpmjs.com
i18next-browser-languagedetector^8.0.0runtimelanguage detector used in browser environment for i18nextnpmjs.com
i18next-http-backend^2.5.2runtimei18next-http-backend is a backend layer for i18next using in Node.js, in the browser and for Deno.npmjs.com
js-file-download^0.4.12runtimeJavascript function that triggers browser to save javascript-generated content to a filenpmjs.com
react^18.3.1runtimeUser interfacenpmjs.com
react-dom^18.3.1runtimeUser interfacenpmjs.com
react-dropzone^14.2.3runtimeUser interfacenpmjs.com
react-hook-form^7.51.5runtimeUser interfacenpmjs.com
react-i18next^14.1.2runtimeUser interfacenpmjs.com
react-scripts5.0.1runtimeUser interfacenpmjs.com
typescript^4.9.5runtimeType checkingnpmjs.com
web-vitals^2.1.4runtimeEasily measure performance metrics in JavaScriptnpmjs.com
yup^1.4.0runtimeData validationnpmjs.com
@babel/plugin-proposal-private-property-in-object^7.21.11developmentBuild toolingnpmjs.com

7.10. CI/CD pipeline

1 GitHub Actions workflow, 1 job. Each box is a job; double-bordered boxes publish or deploy, and arrows follow needs.

Mermaid Pipeline flow
flowchart LR
  subgraph wf0["CI"]
    direction LR
    wf0_build["build<br/>ubuntu-latest"]
  end
  t0(["push · pull request"])
  t0 --> wf0_build
Workflows, triggers, jobs and targets
WorkflowTriggersJobsPublishes to
CI
.github/workflows/ci.yml		push, pull request
  • build ubuntu-latest
    Checkout code · Set up JDK 22 · Set up Python 3.12 · Install dependencies · Install and configure Flatpak · Install Gradle
—

7.11. Deployment

Mermaid Deployment diagram
flowchart LR
  repo[("GitHub repository")]
  ci[["GitHub Actions<br/>1 workflow"]]
  image["Docker image<br/>FROM ubuntu:latest"]
  subgraph compose["Docker Compose"]
    svc_maestro_backend["maestro-backend"]
    svc_maestro_frontend["maestro-frontend"]
  end
  repo -->|"push or pull request"| ci
  ci -->|"docker build"| image
  image -->|"docker compose up"| compose
UML Deployment
Deployment

The outer node is where the code runs. Each base image points to what it builds, solid arrows lead to databases and dashed ones to outside services. Rendered with uml-mcp.

PlantUML source
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
node "Docker Compose" as H {
  node "maestro-backend" as N0 <<container>>
  node "maestro-frontend" as N1 <<container>>
}
artifact "FROM ubuntu:latest" as IMG0
IMG0 ..> N0 : builds
artifact "FROM ubuntu:latest" as IMG1
IMG1 ..> N0 : builds
artifact "FROM ubuntu:latest" as IMG2
IMG2 ..> N0 : builds
@enduml

Where it runs

Compose services

maestro-backend maestro-frontend

Docker base images

ubuntu:latest ubuntu:latest ubuntu:latest

7.12. Monitoring

What the code logs, measures and exposes to tell whether it is working.

Health and metrics routes

GET /health

Container health checks

7.13. Security

Controls

Supply chain

Environment variables 1

The page lists names without their values and underlines the ones that look like secrets.

BACKEND_URL

7.14. Testing

Test files
5
Source files
26
Test cases, about
22
Unit tests
4
Integration tests
1

No measured coverage report in the analyzed sources.

Where the tests are

backend/src/test/java/PFE008/backend 4 maestro-app/src 1

Continuous integration

CI
gradle test
UML CI pipeline
CI pipeline

The main GitHub Actions workflow runs these steps. Jobs that run in parallel sit side by side. Rendered with uml-mcp.

PlantUML source
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
title CI
start
partition "build" {
  :Checkout code;
  :Set up JDK 22;
  :Set up Python 3.12;
  :Install dependencies;
  :Install and configure Flatpak;
  :Install Gradle;
  :Build with Gradle;
  :Run Java Tests;
}
stop
@enduml

Nothing found for: Database.

8. Types and file structure

12 declared types, with 12 in the base-relationship overview.

Type diagram
classDiagram
direction TB
class t0fc2da07ca26["AudiverisController"] {
  AudiverisController()
  convert()
  convertMxlToMidi()
}
class te09535b4ea27["ConvertController"] {
  convert()
  healthCheck()
}
class t5b329a34a4e0["BackendApplication"] {
  main()
}
class t5026bc97d4a6["ConversionResponse"] {
  getFileName()
  setFileName()
  getDownloadUri()
  setDownloadUri()
}
class ta28a28fad99c["FileUtil"] {
  saveFile()
  getFileAsResource()
  isValidFile()
  cleanupDirectories()
}
class t3a8c9a5b3e47["AudiverisController_tests"] {
  setup()
  testConvertSuccess()
  testConvertWrongFile()
  testConvertFileOutput()
}
class tc9ddabb9fef2["ConvertControllerTest"] {
  setup()
  testConvertSuccess()
  testConvertFail()
  testConvertFileNotFound()
}
class tf78cdd633a9f["FileUtil_tests"] {
  setup()
  testSaveFile()
  testGetFileAsResource()
  testSaveFileThrowsIOException()
}
class t306c8eab2abe["TestMxlToMidi"] {
  setUp()
  test_apply_dynamics_to_notes()
  test_print_note_details()
  test_print_part_details()
}
class t5c7dff211126["MusicSheetUploaderProps"] {
  <<interface>>
}
class t28f92fc28615["UseMaestroClientResult"] {
  <<interface>>
}
class td89584c9e8be["MusicSheetUploadFormFooterProps"] {
  <<interface>>
}
class b385cfa4f4c5b["unittest.TestCase"] {
  <<unresolved_base>>
}
b385cfa4f4c5b <|-- t306c8eab2abe

Unresolved bases remain labelled; full signatures are not reconstructed.

9. Reference

32 / 32 eligible files read (128 in the tree); 0 oversized, 0 failed reads and 0 syntax diagnostics.

What the scan covers

Known dependency/build folders, credential files and binaries are excluded. The scan covers READMEs, recognized manifests and parser-supported source files.

Linguist statistics cover the whole repository and may include other languages.

11. Files to read 4

12. Glossary

Repository

The versioned source files, configuration, and history of a project.

README

The repository’s entry document, usually covering its purpose and initial setup.

Dependency

A library, tool, or service that another component needs to build or run.

HTTP

A request-and-response protocol used by browsers and web services. A method, path, headers, and optional body describe a request.

Container

An isolated process environment created from an image. Persistent data needs storage outside the container’s disposable filesystem.

Published port

A host port mapped to a service’s container port. Publishing a port can expose that service beyond its container network.

CLI

A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.

Build

The steps that turn source files and dependencies into a runnable program or distributable artifact.

Backend

An implementation behind a shared interface. Depending on context, it can mean a server-side service or a graphics, input, or storage implementation.

Firmware

Software running on a device or microcontroller to control its hardware and communication.

Fork

A separate repository derived from another project. A change in a fork is not automatically a change in the upstream project.

13. References

  1. antoinebou12. (2026, November 5). Maestro. [Software repository] github.com.
  2. antoinebou12. (2026, November 5). Maestro: README. [Repository documentation] github.com.
  3. antoinebou12. (2026, November 5). backend/src/main/java/PFE008/backend/ConvertController.java. [Source file] github.com.
  4. antoinebou12. (2026, November 5). backend/src/main/java/PFE008/backend/AudiverisController.java. [Source file] github.com.
  5. antoinebou12. (2026, November 5). backend/src/main/MxlToMidi.py. [Source file] github.com.
  6. antoinebou12. (2026, November 5). maestro-app/package.json. [Source file] github.com.
  7. Boucher, A. (2026, October 23). Maestro: Sheet music through an external conversion pipeline. [Project article] antoineboucher.info.

Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.