1.3 Project Directory Structure & Architecture

1.3 Project Directory Structure & Architecture

Exam Focus: A Mendix Intermediate Developer must understand what occurs on the physical filesystem behind the visual canvas of Mendix Studio Pro. You will be tested on the purpose of each directory in a Mendix project root, which files must be committed to version control versus excluded via .gitignore, the underlying architecture of the .mpr file, and how to troubleshoot Java library conflicts in userlib/.

When developing an enterprise low-code application, Studio Pro abstracts away much of the underlying boilerplate. However, enterprise development requires incorporating external Java libraries, custom JavaScript widgets, SCSS styling, and configuration templates. Understanding the physical directory structure is vital for debugging build failures, managing repository sizes, and collaborating cleanly via Team Server.

---

Physical Anatomy of a Mendix Project Directory

Opening the project directory on your local machine (via Studio Pro's menu: App > Show App Directory in Explorer / Finder) reveals a standardized folder structure. Every folder has a specific lifecycle and operational scope:

<AppRoot>/
├── <ProjectName>.mpr      # Primary model database (SQLite)
├── theme/                 # Web & native styling (SCSS, JS, images, fonts)
├── resources/             # Static server resources (certificates, templates)
├── javasource/            # Java action source files (.java)
├── javascriptsource/      # Client-side JavaScript action files (.js)
├── widgets/               # Pluggable widget packages (.mpk)
├── userlib/               # External third-party Java libraries (.jar)
├── deployment/            # TRANSIENT: Compiled build output (Ignored by Git)
└── data/                  # TRANSIENT: Local runtime database & logs (Ignored by Git)

Comprehensive Directory Breakdown

Deep Dive: The .mpr Model Repository File

At the very core of every Mendix application is the .mpr (Mendix Project Repository) file. While developers interact with it as a visual design canvas inside Studio Pro, under the hood it is an SQLite relational database.

Architectural Significance of the SQLite .mpr Structure

• Entity-Relationship Storage: All visual elements—domain model entities, associations, microflow activity nodes, decision splits, page layout widgets, and role access rules—are stored as relational records and BLOBs within SQLite tables.
• Binary Nature: Because .mpr is an SQLite database rather than a line-oriented plaintext file (such as XML, JSON, or YAML), traditional text-based diff and merge tools (like standard git diff or git merge) cannot interpret or reconcile changes inside it.
• Studio Pro's Custom Engine: Mendix Studio Pro incorporates a specialized, model-aware conflict resolution engine capable of opening, analyzing, and merging conflicting SQLite records at the semantic model level.
• The .mpr.lock File: When an instance of Studio Pro opens a project, it generates a temporary <ProjectName>.mpr.lock file in the project root. This prevents multiple concurrent Studio Pro processes from writing to the SQLite database simultaneously and corrupting model state. The lock file is deleted automatically upon closing Studio Pro.

---

Client-Side vs Server-Side Extensibility Assets

Mendix cleanly demarcates where custom code resides based on where it executes:

Server-Side Code: javasource/ & userlib/

Custom business logic that must execute securely on the server runtime (such as cryptographic hashing, legacy database JDBC queries, or SAP RFC connections) is authored in Java:

• javasource/: Contains Java packages structured as javasource/<ModuleName>/actions/<ActionName>.java. Each file represents a custom Java action configured in Studio Pro. The developer writes code between the // BEGIN USER CODE and // END USER CODE comment blocks. When Studio Pro synchronizes or compiles, it preserves code within those blocks while regenerating the outer class boilerplate.
• userlib/: Holds compiled .jar dependencies required by those Java actions. For example, if a Java action parses Excel sheets using Apache POI, the necessary poi-5.2.3.jar and poi-ooxml-5.2.3.jar must be placed in userlib/.

The Marketplace Module Dependency Trap (Duplicate JARs)

A frequent exam topic and real-world stumbling block occurs when importing or updating Marketplace modules.

Exam Trap: When you upgrade a Marketplace module (for example, upgrading the Excel Importer or RestServices module), the new package may introduce an updated dependency (e.g., commons-codec-1.16.jar). However, Studio Pro does not automatically delete the older version (commons-codec-1.14.jar) from userlib/.

When two versions of the same library exist in userlib/, the Java Virtual Machine loads whichever .class it encounters first on the classpath. This nondeterministic behavior causes runtime errors such as:

• java.lang.NoSuchMethodError
• java.lang.ClassNotFoundException
• java.lang.LinkageError

The Solution: Whenever updating Marketplace modules with Java dependencies, developers must manually inspect userlib/, identify duplicate .jar files bearing different version numbers, and delete the obsolete versions before running the application.

Client-Side Code: javascriptsource/, theme/, & widgets/

Logic that executes directly in the user's web browser or mobile client device runs in a JavaScript runtime:

• javascriptsource/: Contains custom JavaScript actions used within Nanoflows. These execute entirely client-side, enabling offline capabilities, native device feature access (camera, geolocation), and responsive browser UI manipulation.
• theme/: Contains the SCSS stylesheets compiled by Mendix's build tools into CSS for the Atlas UI design system. Changes here dictate corporate branding, typography, and responsive grids.
• widgets/: Houses .mpk packages containing React-based pluggable widgets. Studio Pro unpacks these during build and bundles them into the client web application.

---

Build Artifacts vs Version Control Hygiene

Maintaining clean version control is vital for team velocity. Two directories in the project root must never be checked into Team Server Git:

deployment/ (Transient Build Output)

During local compilation (pressing Run Locally / F5), Studio Pro compiles Java source code into bytecode, bundles client-side JavaScript and SCSS assets, generates runtime configuration YAML/JSON files, and sets up a local web server environment inside deployment/.

• Because this directory is completely regenerated during every build, committing it to Git bloats the repository by gigabytes, generates endless merge conflicts, and pollutes commit histories.

data/ (Local Runtime Data & Database)

When running locally using the built-in database (such as HSQLDB), the actual database table files, transaction logs, and search indexes are stored in data/database/.

• Committing data/ risks sharing stale, unencrypted test records, risks leaking sensitive credentials, and introduces file-lock conflicts between team members.

Standard .gitignore Configuration

A compliant Mendix .gitignore file at the project root must always include:

# Mendix build and runtime artifacts
/deployment/
/data/
*.mpr.lock
*.mpr.bak
.cache/
.mendix-cache/