IRIS App Introduction & Platform Overview
What Is an IRIS App?
An IRIS App is a custom Vue.js 3 front-end application that runs natively inside the Magentrix portal. IRIS stands for Integrated Rich Interactive Solutions. Each app is delivered through Module Federation, meaning it loads seamlessly inside the host portal without an iframe — sharing the portal's authentication session, CSS theme, and navigation structure.
IRIS Apps are the primary way development teams extend the Magentrix platform with custom pages, dashboards, workflows, and interactive experiences tailored to their business needs.
Tech Stack
| Layer | Technology |
|---|
| Frontend | Vue 3 + TypeScript + Vite + Module Federation |
| Data Access | Magentrix SDK (@magentrix-corp/magentrix-sdk) wrapping the REST API V3 |
| Backend Logic | C# .NET Framework 4.8 — Active Controllers (.ctrl) and Active Classes (.ac) |
| Tooling | Magentrix CLI (@magentrix-corp/magentrix-cli) |
Platform Architecture
An IRIS App operates across four layers that work together to deliver a secure, themed, and data-connected experience inside the portal.
┌──────────────────────────────────────────────────┐
│ IRIS App (Vue 3 + TypeScript) │
│ - Components, composables, routing │
│ - Magentrix SDK for all data operations │
│ - Module Federation: integrates with portal │
├──────────────────────────────────────────────────┤
│ Magentrix Platform (Host) │
│ - Authentication & session management │
│ - REST API V3 — primary data layer │
│ - IrisDataResponse (data + metadata + security) │
│ - Portal CSS theming via --mag-* variables │
├──────────────────────────────────────────────────┤
│ C# Backend (only when REST API is insufficient) │
│ - Active Controllers (.ctrl) → /acls/ routes │
│ - Active Classes (.ac) — reusable server logic │
│ - Database class — LINQ queries and CRUD │
├──────────────────────────────────────────────────┤
│ Magentrix CLI (Tooling) │
│ - Link, build, stage, publish │
│ - Dev server with portal asset injection │
│ - App lifecycle: delete and recovery │
└──────────────────────────────────────────────────┘
When published, an IRIS App deploys as a bundle — remoteEntry.js plus an assets/ folder — staged into the Magentrix workspace under src/iris-apps/<app-slug>/. The platform automatically creates a navigation entry for the app and makes it accessible based on user role and permissions.
Core Development Principles
1. REST API First
The Magentrix SDK wraps the REST API V3 and handles authentication, session management, and response parsing automatically. This is your primary data access layer. Use it for all standard operations.
| Use the SDK and REST API | Use a custom C# controller (/acls/) |
|---|
| Standard CRUD — create, read, update, delete | Complex multi-step business logic |
MEQL queries via query() | Transactions spanning multiple entities |
Single record retrieval via retrieve() | Operations requiring admin or system privileges |
| Batch create, edit, or delete | Custom aggregation or data transformation |
Current user context via getUserInfo() | Server-side scheduling, email dispatch, caching |
💡 Rule of thumb: If the SDK's query(), retrieve(), create(), edit(), or delete() methods can fulfil the requirement, use them. Only build a custom controller when the REST API cannot.
2. Business Logic Belongs on the Server
IRIS Apps are front-end only. All business rule evaluation, calculations, and data orchestration must happen at the C# server level — in Active Controllers or Active Classes — not inside Vue components. The frontend is responsible for display and user interaction only.
3. Always Use magentrix vue-run-dev
Always start the development server using magentrix vue-run-dev, not npm run dev directly. The CLI command fetches portal CSS assets from your Magentrix instance and injects them into VITE_ASSETS, which provides all --mag-* theme variables at runtime.
⚠️ Warning: Running npm run dev directly skips asset injection. Every --mag-* theme variable will be undefined and the app will render without any portal styling.
How an IRIS App Is Delivered
Developer machine
└── Vue project (src/, config.ts, .env.development)
│
├── magentrix vue-run-dev ← local development with portal assets
│
└── magentrix vue-run-build ← production build
│
└── dist/ → staged to src/iris-apps/<app-slug>/
│
└── magentrix publish → Magentrix server
│
└── Portal renders app via Module Federation
Key Concepts Glossary
| Term | Definition |
|---|
| IRIS App | A Vue 3 application delivered via Module Federation inside the Magentrix portal. |
| Magentrix SDK | The npm package (@magentrix-corp/magentrix-sdk) that wraps the REST API V3. The primary way IRIS Apps read and write data. |
| REST API V3 | The Magentrix REST API. Supports CRUD operations, MEQL queries, and OAuth token authentication. |
| MEQL | Magentrix Entity Query Language — a SQL-like query language used by the SDK's query() method and the REST API query endpoint. |
| Active Controller | A .ctrl file that defines server-side API endpoints accessible at /acls/<ControllerName>/<ActionName>. Used only when the REST API is insufficient. |
| Active Class | A .ac file that defines reusable server-side utility logic, callable from controllers and triggers. |
| IrisDataResponse | The server response envelope returned by SDK methods. Contains entity data, field-level security enforcement, per-record permissions, and entity metadata. |
| Module Federation | The Vite mechanism that allows the IRIS App bundle to load dynamically inside the host portal at runtime without an iframe. |
--mag-* variables | CSS custom properties injected by the portal at runtime, providing the active theme — colors, fonts, borders, and shadows. |
VITE_ASSETS | An environment variable populated by magentrix vue-run-dev with portal CSS asset URLs. Required for correct theming during local development. |
| App Slug | The unique identifier for an IRIS App, set as appSlug in config.ts. Used as the folder name on the server and in the portal navigation system. |
What to Read Next