# mendix/atlas-ui-framework architecture

> Architecture diagram of the GitHub repository mendix/atlas-ui-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mendix/atlas-ui-framework
- Repository: https://github.com/mendix/atlas-ui-framework

## Overview

##### Project type and purpose
- This is a UI theming package (“Mendix Atlas 2 UI”) that provides styling for both web and native Mendix applications.
- It contains source files (SASS, TypeScript, JavaScript), build scripts, sample HTML entry points, and configuration for design properties.

##### File structure
- Top-level:
- index.html / index-rtl.html / login.html / login-with-sso.html — sample web entry points
- scripts/ — version bump utilities
- styles.js — JS-based style exports
- settings*.json — design-property configuration
- styles/
- web/ — SASS source + compiled CSS assets
- native/ — JS/TS source for React Native theming
– core/ — base variables, helpers, widgets
– app/ — _custom overrides for variables & styles
– ui_resources/atlas_ui_resources — building blocks, layouts, page templates
- configuration: package.json, tsconfig.json, manifest JSON files

##### README for additional insights
- The package separates “core” styling from “app” (custom) styling and “UI resources” (blocks, layouts).
- Build process for web uses SASS → CSS (via Calypso or other SCSS compiler).
- Native styling ships as JS/TS modules consumed by the Make It Native app.
- External tools: Calypso, Mendix Design Property Tool, React Native Debugger.

a. Main components
1. Source Repositories
– Web SASS files (styles/web/sass)
– Native JS/TS files (styles/native/js & styles/native/ts)
– Core vs. App (custom overrides) vs. UI Resources
2. Build Tools
– SCSS compiler (Calypso/webpack)
– TypeScript compiler / bundler
– Version bump scripts
3. Output Artifacts
– Web: CSS files (styles/web/css/main.css, source maps)
– Native: JS bundles (styles/native/js/main.js) + manifest
4. Deployment / Consumption
– Mendix Web Apps (load CSS & JS via index.html)
– Mendix Native Apps (import JS modules in React Native)
5. External Services & Tools
– Calypso (SCSS → CSS)
– Design Property Tool (visual theme customization)
– React Native Debugger (inspect native styles)

b. Relationships & data flows
– “scripts/” interacts with package.json to bump versions before builds
– Settings JSON files feed into both build pipelines to generate theme variables
– UI Resources modules consumed by both build outputs

c. Architectural patterns & design principles
– Separation of Concerns: core styling layer vs. custom overrides vs. UI resources
– Theming pipeline: source → compile → output → runtime consumption
– Monorepo-style packaging: tight coupling with widgets-resources repo for shared assets

d. Key technologies, frameworks, libraries
– SASS/SCSS, Calypso (or equivalent)
– TypeScript, Babel/Metro (for React Native)
– Node.js scripts for automation
– Mendix platform (web & native runtime)

##### Detailed breakdown for components
- Core Styling Layer
- Base variables, helpers, widget defaults
- Shared by web & native pipelines
- App (Custom) Layer
- _custom-variables.scss / .js
- Overrides core variables
- UI Resources Layer
- Building blocks (card, header, chat…)
- Layouts & page templates
- Build Scripts
- bump-major/minor/patch (versioning)
- Integration with CI/CD pipelines
- Entry Points
- index.html family for web demos
- Manifest JSON for native bundling

##### Final advice
- Don’t overthink – represent each directory as a node, group related ones visually.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Layers - Web
    subgraph "Web Source Layers"
        direction TB
        WSC["styles/web/sass/core"]:::source
        WSA["styles/web/sass/app"]:::source
        WSU["styles/web/sass/ui_resources"]:::source
    end

    %% Source Layers - Native
    subgraph "Native Source Layers"
        direction TB
        NJS["styles/native/js/core"]:::source
        NJA["styles/native/js/app"]:::source
        NJU["styles/native/js/ui_resources"]:::source
        NTS["styles/native/ts/core"]:::source
        NTA["styles/native/ts/app"]:::source
        NTU["styles/native/ts/ui_resources"]:::source
    end

    %% Config & Scripts
    subgraph "Configuration & Scripts"
        direction TB
        SETTINGS_WEB["settings.json"]:::source
        SETTINGS_NATIVE["settings-native.json"]:::source
        SCRIPTS["scripts (version bump)"]:::build
    end

    %% Build Tools
    subgraph "Build Tools"
        direction TB
        SCSS["SCSS Compiler (Calypso/webpack)"]:::build
        TSBUNDLE["TypeScript Compiler/Bundler"]:::build
    end

    %% Outputs
    subgraph "Output Artifacts"
        direction TB
        WCSS["styles/web/css (main.css)"]:::output
        NJSB["styles/native/js/main.js"]:::output
        NTSEMBED["styles/native/ts/main.ts → bundled"]:::output
    end

    %% Runtime Consumers
    subgraph "Runtime Consumption"
        direction TB
        WEBAPP["Mendix Web App (index.html family)"]:::runtime
        NATIVEAPP["Mendix Native App (React Native)"]:::runtime
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        CALYPSO["Calypso"]:::external
        DPT["Design Property Tool"]:::external
        RNDEBUG["React Native Debugger"]:::external
    end

    %% Relationships Web
    WSC -->|"compile with SCSS"| SCSS
    WSA -->|"compile with SCSS"| SCSS
    WSU -->|"compile with SCSS"| SCSS
    SETTINGS_WEB -->|"theme vars"| SCSS
    SCSS -->|"outputs CSS"| WCSS
    WCSS -->|"load"| WEBAPP
    WEBAPP -->|"view sample"| INDEX["index.html"]:::runtime
    WEBAPP -->|"view sample RTL"| INDEXRTL["index-rtl.html"]:::runtime
    WEBAPP -->|"view login"| LOGIN["login.html"]:::runtime
    WEBAPP -->|"view login SSO"| LOGINSO["login-with-sso.html"]:::runtime

    %% Relationships Native
    NJS -->|"compile with TSBUNDLE"| TSBUNDLE
    NJA -->|"compile with TSBUNDLE"| TSBUNDLE
    NJU -->|"compile with TSBUNDLE"| TSBUNDLE
    NTS -->|"compile with TSBUNDLE"| TSBUNDLE
    NTA -->|"compile with TSBUNDLE"| TSBUNDLE
    NTU -->|"compile with TSBUNDLE"| TSBUNDLE
    SETTINGS_NATIVE -->|"theme vars"| TSBUNDLE
    TSBUNDLE -->|"outputs JS bundle"| NJSB
    NJSB -->|"import"| NATIVEAPP

    %% Scripts to Tools
    SCRIPTS -->|uses| SETTINGS_WEB
    SCRIPTS -->|uses| SETTINGS_NATIVE
    SCRIPTS -->|runs before| SCSS
    SCRIPTS -->|runs before| TSBUNDLE

    %% External Tools connections
    CALYPSO -.-> SCSS
    DPT -.-> SETTINGS_WEB
    DPT -.-> SETTINGS_NATIVE
    RNDEBUG -.-> NATIVEAPP

    %% Click Events for component mappings
    click INDEX "https://github.com/mendix/atlas-ui-framework/blob/release/index.html"
    click INDEXRTL "https://github.com/mendix/atlas-ui-framework/blob/release/index-rtl.html"
    click LOGIN "https://github.com/mendix/atlas-ui-framework/blob/release/login.html"
    click LOGINSO "https://github.com/mendix/atlas-ui-framework/blob/release/login-with-sso.html"
    click SCRIPTS "https://github.com/mendix/atlas-ui-framework/tree/release/scripts"
    click SETTINGS_WEB "https://github.com/mendix/atlas-ui-framework/blob/release/settings.json"
    click SETTINGS_NATIVE "https://github.com/mendix/atlas-ui-framework/blob/release/settings-native.json"
    click WSC "https://github.com/mendix/atlas-ui-framework/tree/release/styles/web/sass/core"
    click WSA "https://github.com/mendix/atlas-ui-framework/tree/release/styles/web/sass/app"
    click WSU "https://github.com/mendix/atlas-ui-framework/tree/release/styles/web/sass/ui_resources/atlas_ui_resources"
    click WCSS "https://github.com/mendix/atlas-ui-framework/blob/release/styles/web/css/main.css"
    click NJS "https://github.com/mendix/atlas-ui-framework/blob/release/styles/native/js/core/variables.js"
    click NJA "https://github.com/mendix/atlas-ui-framework/blob/release/styles/native/js/app/custom-variables.js"
    click NJU "https://github.com/mendix/atlas-ui-framework/tree/release/styles/native/js/ui_resources/atlas_ui_resources"
    click NTS "https://github.com/mendix/atlas-ui-framework/blob/release/styles/native/ts/core/variables.ts"
    click NTA "https://github.com/mendix/atlas-ui-framework/blob/release/styles/native/ts/app/custom-variables.ts"

    %% Styles
    classDef source fill:#bbdefb,stroke:#1e88e5,color:#000
    classDef build fill:#c8e6c9,stroke:#388e3c,color:#000
    classDef output fill:#ffe0b2,stroke:#f57c00,color:#000
    classDef runtime fill:#e1bee7,stroke:#8e24aa,color:#000
    classDef external fill:#b2dfdb,stroke:#00695c,color:#000
```
