<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines	section
29-36	When to Use This Skill
37-96	Assessment Workflow
97-352	Quality Guidelines Reference
353-363	Assessment Report Template
364-376	Executive Summary
377-387	project Metrics
388-400	Automated Findings
401-420	Manual Review Findings
421-436	Recommendations
437-447	Sources

<!-- /skill-index -->

Assess Mendix Project Quality

This skill guides a comprehensive quality assessment of a Mendix project, evaluating it against established best practices across naming, security, performance, maintainability, architecture, and more.

When to Use This Skill

Use this skill when:

• A user asks to evaluate the quality of a Mendix project
• Reviewing a project against best practices before go-live
• Performing a health check or audit on an existing application
• Onboarding onto a project and wanting to understand its quality posture

Assessment Workflow

Step 1: Run Automated Analysis

Run the automated linter and report to get a baseline score:

# connect to the project and build a full catalog (needed for deep analysis)
mxcli -p app.mpr -c "refresh catalog full"

# run the linter (41 rules: MDL, SEC, QUAL, ARCH, design, CONV series)
mxcli lint -p app.mpr

# generate the scored best practices report
mxcli report -p app.mpr --format markdown

# score only the app's own modules (not Marketplace / platform modules)
mxcli report -p app.mpr --modules MyModule,OtherModule --format markdown

The report covers 6 categories with scores: Naming, Security, Quality, Architecture, Performance, Design.

Step 2: Explore Project Structure

Use catalog queries to understand the project's shape:

-- Overview of project size and structure
describe structure depth 2;

-- Key metrics
select module_name, count(*) from CATALOG.entities GROUP by module_name;
select module_name, count(*) from CATALOG.microflows GROUP by module_name;
select module_name, count(*) from CATALOG.pages GROUP by module_name;

-- Complexity metrics (McCabe/Sigrid-style)
select qualified_name, cyclomatic_complexity
from CATALOG.microflows
where cyclomatic_complexity > 10
ORDER by cyclomatic_complexity desc;

-- Large microflows
select qualified_name, activity_count
from CATALOG.microflows
where activity_count > 15
ORDER by activity_count desc;

Step 2b: Architecture & Dependency-Graph Analysis

mxcli models the project as a dependency graph and exposes topological analyses on top of it — god nodes, coupling, cohesion, communities, centrality, cycles, and layering. These answer questions catalog metrics can't: what's central, what's tangled, what belongs together.

Read graph-analysis before running graph analysis. It covers setup (two-step refresh required), all eight use cases (impact assessment, dead code, cohesion, communities, bridges, hotspots, cycles, monolith splits), column schemas, false-positive caveats for dead assets, and a quick-reference table mapping questions to tables.

Step 3: Manual Review Against Guidelines

After reviewing automated results, assess the following areas manually. The guidelines below are organized by category.

---

Quality Guidelines Reference

A. Naming Conventions

Enforced by rules: MPR001, CONV001, CONV003, CONV004, CONV005

Element	Convention	Example
Entities	Singular, PascalCase, no underscores	Customer, OrderLine (not Customers, Order_Line)
Attributes	PascalCase	FirstName, OrderDate
Boolean attributes	Prefix with Is/Has/Can/Should/Was/Will	IsActive, HasChildren
Microflows	Prefix indicating purpose	ACT_Customer_Save, DS_Customer_GetAll
Pages	Entity + suffix	Customer_NewEdit, Order_Overview, Product_View
Enumerations	Prefix with ENUM_	ENUM_OrderStatus, ENUM_Gender
Snippets	Prefix with SNIPPET_	SNIPPET_CustomerDetails
Java actions	Prefix with JA_	JA_SendEmail

Microflow prefix reference (21 recognized prefixes):

Prefix	Purpose	Layer
ACT_	UI action (button click handler)	UI
DS_	Data source for pages/widgets	UI
NAV_	Navigation microflow	UI
LOGIN_	Login/authentication flow	UI
SUB_	Reusable submicroflow	Logic
VAL_	Validation logic	Logic
BCO_	Before commit handler	Event
ACO_	After commit handler	Event
BCR_	Before create handler	Event
ACR_	After create handler	Event
BDE_	Before delete handler	Event
ADE_	After delete handler	Event
BRO_	Before rollback handler	Event
ARO_	After rollback handler	Event
OCH_	On-change handler	Event
SCH_	Scheduled event	Integration
IVK_	Invocable (called by external systems)	Integration
SE_	Scheduled event (alternative)	Integration
DL_	Deep link handler	Integration
PWS_	Published web service	Integration
ASU_	After startup microflow	System

Manual check: Verify that microflow names are descriptive beyond just the prefix. For example, ACT_Customer_Save is better than ACT_Save.

B. Folder Structure

Not automatically enforced (folder hierarchy not fully captured in catalog)

Convention	What to Check
Each module has [objects] and [UI] top-level folders	Open in Studio Pro or check folder data
ACT_ and DS_ microflows live in the [UI] folder	These are page-related, belong in UI
Entity-specific microflows grouped in entity subfolders under [objects]	e.g., [objects]/Customer/BCO_Customer_Validate
Pages organized by entity or feature	Not scattered randomly

C. Security

Enforced by rules: SEC001-SEC010, CONV006, CONV007, CONV008, MPR007

C.1 Entity Access

Guideline	Rule	Priority
All persistent entities must have access rules	SEC001	Critical
Every role that opens a page can read the entities its grids, galleries and combo boxes list (else it renders empty at Production)	SEC010	High
Do not grant Create or Delete rights on entity access rules	CONV006	High
All entity access rules should have XPath constraints	CONV007	High
Set default access rights to None	Manual check	High
Do not use entity validation rules (use microflow validation instead)	CONV015	Medium
Do not use entity event handlers (use explicit microflow calls)	CONV016	Medium

C.2 Role Management

Guideline	Rule	Priority
1:1 mapping between module roles and user roles	CONV008	High
Pages in navigation must have allowed roles	MPR007	High
Every user role can open its home page (else CE2729 at Production security)	MPR007	High
No guest/anonymous access to sensitive data	SEC004	Critical
Strict security mode enabled	SEC005	High
No demo users in production	SEC003	Critical
Password policy >= 8 characters	SEC002	High

C.3 DIVD Findings (Common Misconfigurations)

The Dutch Institute for Vulnerability Disclosure (DIVD) found widespread authorization misconfigurations in Mendix apps. Key checks:

Check	What to Verify
Anonymous user permissions	Anonymous role should have minimal entity access; no access to business data
Newly registered user permissions	Default user role should not grant broad data access
XPath constraints completeness	Every READ/WRITE access rule on business entities needs XPath constraints
Published REST/OData security	All published services require authentication
Entity access audit	Run select * from CATALOG.permissions where is_constrained = 0

C.4 Additional Security Practices

• Do not store sensitive information (passwords, API keys) in constants (values are visible in version control)
• Sanitize user input to prevent XSS (use HTMLSanitize() from Community Commons)
• Be cautious with nanoflow security — nanoflows execute client-side and can be inspected
• Use HTTPS for all external integrations
• Validate and urlEncode() all values used in REST URLs

D. Maintainability

Enforced by rules: QUAL001-QUAL004, CONV009, CONV012, CONV014, MPR002, MPR004, MPR006

Guideline	Rule/Check	Threshold
Microflow complexity (McCabe)	QUAL001	Cyclomatic complexity <= 10
Microflow size	CONV009	Max 15 activities
Documentation on public microflows	QUAL002	All ACT_, DS_, IVK_ should be documented
No orphaned/unused elements	QUAL004	Remove unused microflows, pages, entities
No empty microflows	MPR002	Every microflow should have at least one activity
Caption on exclusive splits	CONV012	All decision points must have captions
No "Continue" error handling	CONV014	Never swallow errors silently
ACT_ microflows: thin controllers	CONV010	Only page activities + submicroflow calls

Manual checks:

• Don't change activity captions (they should match the default for readability)
• Don't modify imported/marketplace modules (fork or extend instead)
• Generalize repeated snippets — if the same layout appears 3+ times, extract to a snippet
• Remove all Studio Pro warnings (yellow markers)
• Limit use of non-Mendix languages (Java, JavaScript) to what's necessary

E. Performance

Enforced by rules: CONV011, CONV016, CONV017

Guideline	Rule/Check	Impact
No calculated attributes	CONV017	Calculated attributes execute on every retrieve
No entity event handlers	CONV016	Event handlers fire on every create/commit/delete, often unnecessarily
No commit inside loops	CONV011	Each commit is a database round-trip; batch instead
No Export to Excel widget	Manual	Use CSV export for large datasets
Minimize in-use session objects	Manual	Large session caches increase memory pressure

XPath performance tips:

• Avoid negation in XPath (not(), !=) — these cannot use indexes efficiently
• Use indexed attributes in XPath constraints
• Prefer [Assoc/entity/attribute = value] over retrieving + filtering in microflow
• For large datasets, consider using a data source microflow with pagination

Microflow performance tips:

• Use batching for operations on 100+ objects (retrieve in batches of 1000, process, commit batch)
• Avoid deep nesting of microflow calls (call stack overhead)
• Use list operations (find, filter, head) instead of loops when possible

F. Architecture

Enforced by rules: ARCH001-ARCH003, CONV010, MPR003

Guideline	Rule/Check	Details
No cross-module direct data access	ARCH001	Access data through microflows, not direct entity references
Data changes through microflows only	ARCH002	Don't change entities from pages directly
Business key on entities	ARCH003	Persistent entities should have a business key attribute
Domain model size	MPR003	Max 15 persistent entities per module
Entity attribute count	DESIGN001	Max 10 attributes per entity (consider splitting)

Manual checks:

• Modules should represent bounded contexts (clear responsibilities)
• Avoid circular dependencies between modules
• Use non-persistent entities for view models / DTOs
• Keep page data sources simple — use DS_ microflows for complex data retrieval

G. Error Handling

Enforced by rules: CONV013, CONV014

Guideline	Details
Default error handling	All microflows should use Stop + Log + Roll back + Show user message
Custom error handling on service calls	REST calls, web service calls, and Java actions need custom error handling
Never use "Continue" error handling	This silently swallows errors — always handle explicitly
Log with context	Include status code, response body, and input parameters in error logs
Rethrow after logging	After logging the error details, rethrow so the caller can handle it

Pattern for REST call error handling:

1. Call REST service (with custom error handling)
2. On error: check if $latestHttpResponse exists
3. If yes: log status code + reason + response content, then rethrow
4. If no: default error handling is sufficient (timeout/connection refused)

H. Connectors (Consumed Services)

Guideline	Details
Simplify mappings	Remove empty/optional entities from import mappings
Tree structure for domain model	Parent entities above children, use inheritance, add comments between sections
String attributes: set to Unlimited	Connector strings should not have length limits
Remove default value 0 on numbers	Default 0 is confusing for connector data — leave empty
Add documentation to model	Document each entity and attribute purpose
Use ConnectionDetails entity	Centralize endpoint, username, password, timeout in one entity
Use constants for connection settings	Avoid dependency on Encryption module; use constants with empty defaults
Operations naming	Follow METHOD_VERSION_OPERATION pattern
File structure	Separate connection Details, Operations, Private folders
Validate input before urlEncode	Check for empty values before constructing URLs

I. UI Best Practices

Guideline	Details
Use SASS, not inline CSS	All styling in _custom-variables.scss or theme files
Avoid nested styling rules	Keep CSS flat for maintainability
No inline style attributes	Use CSS classes instead
Consistent page layout	Use layout grids, not absolute positioning

J. Quality Metrics (SIG/Sigrid Model)

The catalog includes McCabe cyclomatic complexity metrics aligned with the ISO 25010 maintainability standard used by Sigrid. Use these queries to assess code quality:

-- Complexity distribution (Sigrid-style)
select
  case
    when cyclomatic_complexity <= 5 then 'Low (1-5)'
    when cyclomatic_complexity <= 10 then 'Moderate (6-10)'
    when cyclomatic_complexity <= 20 then 'High (11-20)'
    else 'Very High (>20)'
  end as complexity_band,
  count(*) as microflow_count
from CATALOG.microflows
GROUP by complexity_band;

-- Top complex microflows
select qualified_name, cyclomatic_complexity, activity_count
from CATALOG.microflows
where cyclomatic_complexity > 10
ORDER by cyclomatic_complexity desc
limit 20;

Sigrid benchmarks (5-star system):

• 5 stars: 90%+ of microflows have complexity <= 5
• 4 stars: 80%+ of microflows have complexity <= 10
• 3 stars: 70%+ of microflows have complexity <= 15
• Below 3 stars: significant maintainability risk

K. View Entities

View entities are powerful for specific scenarios but not universal replacements for standard logic:

Use Case	Recommendation
Large dataset performance	View entity is recommended when microflow data source is too slow
Complex OQL queries	View entity can replace complex microflow logic with loops/filters
Flattening data for reports	More efficient than non-persistent entities filled by microflows

Caution: View entities increase technical complexity and require OQL knowledge. Only use when there is a clear performance or simplification benefit.

---

Assessment Report Template

After running the automated tools and performing manual review, produce a report using this structure:

# Mendix project Quality Assessment

**project:** [Name]
**date:** [date]
**Assessor:** Claude Code

## Executive Summary

Overall Score: [X]/100 (from `mxcli report`)

| Category | Score | key Finding |
|----------|-------|-------------|
| Naming | X% | [one-line summary] |
| security | X% | [one-line summary] |
| Quality | X% | [one-line summary] |
| Architecture | X% | [one-line summary] |
| Performance | X% | [one-line summary] |
| design | X% | [one-line summary] |

## project Metrics

| Metric | value |
|--------|-------|
| modules | X |
| entities (persistent) | X |
| microflows | X |
| pages | X |
| avg complexity | X |
| max complexity | X |

## Automated Findings

[Summary of lint violations by category, grouped by severity]

### critical Issues (must fix)
- [list]

### High Priority (should fix)
- [list]

### Medium Priority (consider fixing)
- [list]

## Manual Review Findings

### Naming Conventions
[Assessment against Section A guidelines]

### security Posture
[Assessment against Section C guidelines, including DIVD checklist]

### Maintainability
[Assessment against Section D guidelines]

### Performance Risks
[Assessment against Section E guidelines]

### Architecture
[Assessment against Section F guidelines]

### error Handling
[Assessment against Section G guidelines]

## Recommendations

### Top 5 actions (Highest impact)
1. [specific, actionable recommendation]
2. [specific, actionable recommendation]
3. [specific, actionable recommendation]
4. [specific, actionable recommendation]
5. [specific, actionable recommendation]

### Quick Wins (Low Effort, High value)
- [list of easy fixes]

### long-term Improvements
- [list of architectural/structural improvements]

Sources

This skill incorporates guidelines from:

• Conventions.pdf — Squad Apps internal best practices (14 categories, 80+ guidelines)
• CONV001-CONV017 lint rules — Automated checks derived from Conventions.pdf
• MPR001-MPR007, SEC001-SEC010 — Built-in linter rules
• ARCH, DESIGN, QUAL series — Starlark architecture/quality rules
• Mendix Performance Best Practices — Official Mendix documentation on performance optimization
• Mendix Security Best Practices — Official Mendix documentation on security configuration
• DIVD Mendix Findings — Dutch Institute for Vulnerability Disclosure (entity access misconfigurations)
• SIG/Sigrid Quality Model — ISO 25010 maintainability metrics, McCabe complexity benchmarks