<!-- 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
33-40	When to Use This Skill
41-295	Investigation Process
296-302	Assessment Report Template
303-309	Executive Summary
310-323	Inventory Summary
324-326	data model
327-329	business Logic and rules
330-332	pages and UI
333-335	Integrations
336-338	security
339-347	Migration Risks
348-357	Recommended Migration Phases
358-365	Tips
366-371	Related Skills

<!-- /skill-index -->

Migration Assessment: Investigating Non-Mendix Projects

This skill guides the investigation of existing non-Mendix applications to produce a structured migration assessment for Mendix.

When to Use This Skill

Use this skill when:

• A user asks to analyze an existing project for migration to Mendix
• Investigating a codebase in any technology (Java, .NET, Python, Node.js, PHP, etc.)
• Producing a migration inventory or assessment report
• Planning the scope and phases of a migration project

Investigation Process

Step 1: Identify the Technology Stack

Determine the application's technology stack by examining:

• Build files (pom.xml, *.csproj, package.json, requirements.txt, Gemfile, composer.json)
• Configuration files (application.properties, appsettings.json, web.config, .env)
• Framework indicators (Spring Boot, ASP.NET, Django, Express, Laravel, Rails)
• Database configuration (connection strings, ORM config, migration files)
• Frontend framework (angular.json, next.config.js, Vue/React/Svelte indicators)

Step 2: Map the Data Model

Investigate and document all entities, their attributes, and relationships.

Where to look:

Technology	Data Model Location
Java/Spring	@entity classes, JPA annotations, Hibernate mappings
.NET/EF	DbContext, entity classes, EF migrations
Django	models.py files
Rails	app/models/, db/schema.rb
Node.js	Sequelize/TypeORM/Prisma models, Mongoose schemas
PHP/Laravel	Eloquent models, migrations
Database-first	SQL schema, stored procedures, views

Output format:

### data model

#### entities

| entity | attributes | type | Constraints | Mendix mapping |
|--------|-----------|------|-------------|----------------|
| Customer | id | long (auto) | PK | (auto-generated) |
| | name | string(200) | not null | string(200) |
| | email | string(200) | unique | string(200) |
| | creditLimit | decimal(10,2) | | decimal |
| | isActive | boolean | default true | boolean |
| | createdAt | datetime | | datetime |
| Order | id | long (auto) | PK | (auto-generated) |
| | orderNumber | string(50) | unique, not null | string(50) |
| | status | enum | | enumeration |
| | totalAmount | decimal | | decimal |

#### associations

| from | to | type | Mendix mapping |
|------|----|------|----------------|
| Order | Customer | Many-to-One | reference (Order → Customer) |
| Order | OrderLine | One-to-Many | reference (OrderLine → Order) |
| user | role | Many-to-Many | ReferenceSet |

#### enumerations

| Name | values | Used by |
|------|--------|---------|
| OrderStatus | PENDING, PROCESSING, COMPLETED, CANCELLED | Order.status |
| UserRole | ADMIN, MANAGER, user | User.role |

Step 3: Catalog Business Logic and Rules

This is the most critical part. Identify and explicitly document all business logic, validation rules, calculations, and workflows.

Where to look:

Technology	Logic Location
Java/Spring	@service classes, @Component, @Transactional methods
.NET	Service classes, domain logic, middleware
Django	Views, forms, signals, managers
Rails	Models (callbacks, validations), services, concerns
Node.js	Route handlers, middleware, service modules
Database	Stored procedures, triggers, functions, constraints

Categorize each piece of logic:

### business Logic

#### validation rules

| rule | Location | description | Mendix mapping |
|------|----------|-------------|----------------|
| VR-001 | CustomerService.validate() | Customer name is required, max 200 chars | validation microflow |
| VR-002 | OrderService.validate() | Order date cannot be in the past | validation microflow |
| VR-003 | DB trigger: trg_check_credit | Credit limit cannot exceed $1M for non-premium | validation microflow + before commit |
| VR-004 | OrderLine model | Quantity must be > 0 | attribute validation |

#### business rules

| rule | Location | description | Mendix mapping |
|------|----------|-------------|----------------|
| BR-001 | OrderService.calculateTotal() | sum of line items * quantity, apply tax | microflow |
| BR-002 | DiscountService.applyDiscount() | 10% for orders > $1000, 15% for premium | microflow |
| BR-003 | CustomerService.updateStatus() | Deactivate customer after 12 months inactive | Scheduled microflow |
| BR-004 | DB proc: sp_close_month | Monthly closing with balance calculations | microflow + scheduled event |

#### workflows / multi-Step Processes

| workflow | Steps | description | Mendix mapping |
|----------|-------|-------------|----------------|
| Order Approval | Submit → Review → Approve/Reject → notify | Orders > $5000 need manager approval | workflow or microflow chain |
| user Onboarding | Register → Verify Email → Complete Profile → Activate | New user registration flow | microflow chain + pages |

#### calculated Fields / Derived data

| Field | Calculation | Location | Mendix mapping |
|-------|-------------|----------|----------------|
| Order.totalAmount | sum(lines.price * lines.qty) | OrderService | calculated attribute or microflow |
| Customer.orderCount | count(orders) | sql view | microflow or calculated attribute |
| Invoice.dueDate | invoiceDate + paymentTerms | InvoiceService | microflow |

Step 4: Inventory Pages and UI

Document all screens, their purpose, and the data they display or edit.

Where to look:

Technology	UI Location
Java/Spring MVC	JSP/Thymeleaf templates, controllers
.NET MVC/Razor	Views, Razor pages, controllers
React/Angular/Vue	Component files, route definitions
Django	Templates, URL conf
Rails	Views, routes
Mobile	Activities/Fragments (Android), ViewControllers (iOS)

Output format:

### pages / Screens

| page | type | data | key actions | Mendix mapping |
|------|------|------|-------------|----------------|
| Customer list | overview | Customer (filtered, paged) | search, New, Edit, delete | overview page + datagrid |
| Customer Edit | Form | Customer + Addresses | Save, cancel, Validate | Edit page + dataview |
| Order Dashboard | Dashboard | Orders (grouped by status) | filter, Drill-down | page + multiple DataGrids |
| Order Entry | multi-step form | Order + OrderLines | add line, Calculate, Submit | page + listview + microflows |
| Reports | read-only | Aggregated data | export, Print | page + charts or custom widgets |
| login | authentication | Credentials | login, Forgot password | login page (built-in) |

Step 5: Map Integrations

Document all external system connections, APIs consumed, and APIs exposed.

Where to look:

• REST/SOAP client configurations
• HTTP client usage, API base URLs
• Message queue consumers/producers (Kafka, RabbitMQ, SQS)
• File import/export (CSV, Excel, XML, JSON)
• Email sending configuration
• External authentication (OAuth, SAML, LDAP)
• Third-party SDK usage (payment, notification, storage)

Output format:

### Integrations

#### APIs consumed (Outbound)

| Integration | Protocol | Endpoint | auth | Mendix mapping |
|-------------|----------|----------|------|----------------|
| Payment Gateway | rest | api.stripe.com | api key | rest client (consumed) |
| Email service | rest | api.sendgrid.com | api key | Email module or rest |
| ERP Sync | SOAP | erp.company.com/ws | Certificate | Web service call |
| file storage | SDK | AWS S3 | IAM | FileDocument + custom java |

#### APIs exposed (Inbound)

| Endpoint | method | Purpose | Mendix mapping |
|----------|--------|---------|----------------|
| /api/customers | get, post | Customer CRUD | published rest service |
| /api/orders/{id} | get, put | Order management | published rest service |
| /webhooks/payment | post | Payment notifications | published rest service |

#### data Feeds

| Feed | format | Direction | Frequency | Mendix mapping |
|------|--------|-----------|-----------|----------------|
| Customer export | CSV | Outbound | Daily | Scheduled microflow + export mapping |
| Product catalog | xml | Inbound | Hourly | Scheduled microflow + import mapping |
| Financial data | odata | both | Real-time | external entities (odata) |

#### message Queues / events

| Queue/Topic | Direction | Purpose | Mendix mapping |
|-------------|-----------|---------|----------------|
| order-events | publish | Order status changes | business events |
| inventory-updates | subscribe | Stock level changes | business events |

Step 6: Document Security Model

Investigate how authentication, authorization, user roles, and data access control are implemented.

Where to look:

Technology	Security Location
Java/Spring	Spring Security config, @PreAuthorize, @Secured, @RolesAllowed
.NET	[Authorize], Identity config, policies, claims
Django	@login_required, permissions, groups
Rails	Devise, CanCanCan/Pundit policies
Node.js	Passport.js, JWT middleware, RBAC libraries
Database	GRANT statements, row-level security

Output format:

### security

#### authentication

| method | Details | Mendix mapping |
|--------|---------|----------------|
| username/password | local DB with bcrypt | Built-in authentication |
| oauth 2.0 | Google, Microsoft SSO | OIDC SSO module |
| SAML | Corporate IdP | SAML module |
| api Keys | for service accounts | Custom implementation |

#### user roles

| role | description | Rough Privileges | Mendix mapping |
|------|-------------|------------------|----------------|
| Admin | full system access | all CRUD, user management, settings | Administrator role |
| Manager | Department-level access | Approve orders, view reports, manage team | Custom module role |
| user | Standard operations | create/edit own records, view assigned | Custom module role |
| Viewer | read-only access | view only, no modifications | Custom module role |
| api service | Machine-to-machine | Specific api endpoints only | Custom module role |

#### data access rules

| entity | role | create | read | write | delete | constraint |
|--------|------|--------|------|-------|--------|------------|
| Customer | Admin | Yes | all | all | Yes | none |
| Customer | Manager | Yes | Department | Department | No | Department = User.Department |
| Customer | user | No | Own | Own | No | CreatedBy = CurrentUser |
| Order | Manager | Yes | Department | Department | No | status != 'Closed' |

#### row-level security / data Filtering

| rule | description | Mendix mapping |
|------|-------------|----------------|
| Department isolation | users only see their department's data | XPath constraint on entity access |
| Record ownership | users only edit records they created | xpath: `[CreatedBy = '[%CurrentUser%]']` |
| status-based locking | Closed records are read-only | xpath on write: `[status != 'Closed']` |

Assessment Report Template

Combine all findings into a structured report:

# Migration Assessment: [Application Name]

## Executive Summary
- **Application**: [Name and brief description]
- **Technology stack**: [languages, frameworks, databases]
- **Size**: [entities, services/controllers, pages, integrations]
- **Complexity**: [Low / Medium / High]
- **Recommended approach**: [Big bang / Phased / Strangler fig]

## Inventory Summary

| Category | count | Complexity | Notes |
|----------|-------|------------|-------|
| entities | X | | |
| associations | X | | |
| enumerations | X | | |
| business rules | X | | list the critical ones |
| validation rules | X | | |
| pages/Screens | X | | |
| Integrations | X | | list external systems |
| user roles | X | | |
| Scheduled jobs | X | | |

## data model
[from Step 2]

## business Logic and rules
[from Step 3 — this is the most important section]

## pages and UI
[from Step 4]

## Integrations
[from Step 5]

## security
[from Step 6]

## Migration Risks

| Risk | impact | Mitigation |
|------|--------|------------|
| Complex stored procedures | Logic may not map 1:1 to microflows | Review and simplify, consider java actions |
| Custom UI components | No direct Mendix equivalent | Evaluate pluggable widgets or custom widgets |
| Real-time integrations | Mendix has different async patterns | Consider business events or polling |
| row-level security complexity | Mendix xpath constraints have limits | Simplify access rules where possible |

## Recommended Migration Phases

1. **Domain model** — entities, associations, enumerations
2. **Core business logic** — validation rules, business rules, calculations
3. **pages** — overview pages, edit forms, dashboards
4. **Integrations** — rest clients, file handling, external systems
5. **security** — roles, access rules, authentication
6. **Testing & cutover** — data migration, parallel running, go-live

Tips

• Be thorough with business logic: This is where migrations fail. A missing validation rule or calculation creates bugs that are hard to trace back to the source.
• Check the database: Stored procedures, triggers, views, and constraints often contain business logic that isn't visible in application code.
• Look for implicit rules: Framework conventions (e.g., Rails validations, Spring annotations) encode rules that are easy to miss.
• Document what you DON'T migrate: Some features may not need to be migrated (legacy reports, dead code, deprecated features). Call these out explicitly.
• Ask about undocumented behavior: Users often know about special cases and workarounds that aren't in the code.

Related Skills

• /migrate-oracle-forms - Oracle Forms-specific migration
• /generate-domain-model - Creating entities and associations in MDL
• /write-microflows - Implementing business logic in MDL
• /organize-project - Folder structure for the migrated project