# outsystems/outsystems-ui architecture

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

- Interactive diagram: https://gitdiagram.com/outsystems/outsystems-ui
- Repository: https://github.com/outsystems/outsystems-ui

## Overview

##### Project type and purpose
- This is an open-source UI framework/library (OutSystems UI) written in TypeScript and SCSS.
- It provides a design system, UI patterns (over 70), screen templates, and build tooling for Reactive Web and Native Mobile apps on the OutSystems platform.
- Key deliverables: a compiled NPM package (JS + CSS), documentation site, and OutSystems Service Studio integration.

##### File structure
- Top-level build tooling:
- gulp/ (custom Gulp tasks & specs for TS and SCSS compilation)
- gulpfile.js, package.json, tsconfig.json, typedoc.json
- GitHub Actions workflows under .github/workflows (build, release, docs, npm)
- Source code under src/:
- src/scripts/OSFramework/OSUI – core runtime, event system, feature & pattern abstractions
- src/scripts/OSFramework/OSUI/Pattern – concrete UI Patterns (Accordion, Carousel, Dropdown, …)
- src/scripts/Providers/OSUI – third-party adapters (Flatpickr, Splide, NoUISlider, VirtualSelect, etc.)
- src/scripts/OutSystems/OSUI – glue API layer for OutSystems Service Studio
- src/scss – design tokens, foundations, layouts, widgets, patterns, utilities, deprecated styles
- Documentation source:
- TypeDoc config (typedoc.json)
- markdown under src/README.md, gulp/Template/index.html

##### Extract architecture hints from README
- TypeScript + SCSS input → Gulp pipelines for transpilation (`npm run build`)
- Linting & formatting steps (`npm run lint`, `npm run prettier`)
- CI/CD builds, deploy to NPM, generate docs via TypeDoc
- Integration points:
- Published package on NPM & OutSystems Forge
- Consumed by OutSystems Service Studio at design-time
- Called via the OutSystems JS API at runtime

##### Main components & interactions
a. Components
1. Source modules
- Core Runtime (OSFramework/OSUI/…), Pattern Implementations, Provider Adapters
- SCSS Design System (tokens → patterns → utilities)
2. Build & Tooling
- Gulp tasks (TS transpile, SCSS compile, version bump, npm prepare)
- TypeDoc (documentation generator)
3. CI/CD (GitHub Actions)
- Release pipeline (testing → build → npm publish)
- Docs pipeline (TypeDoc → GitHub Pages)
4. Consumers
- OutSystems Service Studio (design-time drag-drop)
- Web & Mobile runtime pulling in compiled JS/CSS
- 3rd-party dependencies (Flatpickr, Splide, NoUISlider, VirtualSelect)
b. Relationships / Data flow
- Developers commit TypeScript & SCSS → CI/CD triggers → Gulp builds artifacts →
- JS/CSS package published to NPM & Forge
- Documentation generated & deployed
- At runtime, consumer apps import the JS/CSS bundle → instantiate UI Patterns →
- Core Runtime manages events, gestures, accessibility
- Pattern modules render to DOM & apply SCSS styles
- Providers supply underlying third-party library implementations
- OutSystems API layer exposes a uniform interface to Service Studio
c. Architectural patterns / design principles
- Modular architecture: Core abstractions (AbstractPattern, AbstractFeature) → concrete patterns
- Provider pattern for pluggable underlying libraries
- Separation of concerns: Runtime (events, helpers), Patterns, Styles, Build
- Convention-over-configuration: Gulp specs define naming & file conventions for auto-generation
d. Technologies & frameworks
- TypeScript (strict typing, interfaces, classes)
- SCSS (design tokens, partials, modular structure)
- Gulp (task runner), Node.js
- TypeDoc (API docs), ESLint/Prettier (lint & format)
- CI/CD: GitHub Actions, npm registry, GitHub Pages

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Code Layer
    subgraph "Source Code" 
        direction TB
        CoreRuntime["Core Runtime\n(src/scripts/OSFramework/OSUI)"]:::code
        Patterns["Pattern Implementations\n(src/scripts/OSFramework/OSUI/Pattern)"]:::code
        Providers["Provider Adapters\n(src/scripts/Providers/OSUI)"]:::code
        OutSystemsAPI["OutSystems Service Studio API Layer\n(src/scripts/OutSystems/OSUI)"]:::code
        SCSS["SCSS Design System\n(src/scss)"]:::code
    end

    %% Build Tools Layer
    subgraph "Build & Tooling"
        direction TB
        Gulp["Gulp Build Tooling\n(gulp & gulpfile.js)"]:::build
        TSConfig["TypeScript Configuration\n(tsconfig.json)"]:::build
        PackageJSON["NPM Package Metadata & Scripts\n(package.json)"]:::build
    end

    %% CI/CD Layer
    subgraph "CI/CD Pipelines"
        direction TB
        Workflows["GitHub Actions Workflows\n(.github/workflows)"]:::build
    end

    %% Documentation Layer
    subgraph "Documentation"
        direction TB
        TypeDoc["Documentation Generator\n(typedoc.json)"]:::docs
        DocsTemplate["Documentation Templates\n(gulp/Template/index.html)"]:::docs
        README["Project README\n(README.md)"]:::docs
    end

    %% Artifacts
    subgraph "Artifacts"
        direction TB
        NPMPackage["Compiled NPM Package\n(JS + CSS)"]:::external
        DocsSite["Generated Documentation Site"]:::external
    end

    %% Consumers
    subgraph "Consumers"
        direction TB
        ServiceStudio["OutSystems Service Studio\n(Design-time)"]:::external
        RuntimeApp["Web & Mobile Apps\n(Runtime)"]:::external
    end

    %% Relationships
    CoreRuntime -->|"used by"| Patterns
    Patterns -->|"depends on"| Providers
    Providers -->|"adapts third-party libs"| SCSS
    CoreRuntime -->|"styles from"| SCSS
    SourceCodeEnd((Source Modules & Styles))

    CoreRuntime --> SourceCodeEnd
    Patterns --> SourceCodeEnd
    Providers --> SourceCodeEnd
    OutSystemsAPI --> SourceCodeEnd
    SCSS --> SourceCodeEnd

    SourceCodeEnd -->|"build input"| Gulp
    TSConfig -->|"config for"| Gulp
    PackageJSON -->|"scripts & metadata"| Gulp
    Gulp -->|"transpile & compile"| NPMPackage
    Gulp -->|"generate docs"| DocsSite
    TypeDoc -->|"docs input"| DocsSite
    DocsTemplate -->|"template used"| DocsSite
    README -->|"docs content"| DocsSite

    Gulp -->|"pipeline defined in"| Workflows
    Workflows -->|"publish artifacts to"| NPMPackage
    Workflows -->|"deploy docs to"| DocsSite

    NPMPackage -->|"installed by"| ServiceStudio
    NPMPackage -->|"imported by"| RuntimeApp
    OutSystemsAPI -->|"exposes API to"| ServiceStudio
    RuntimeApp -->|"calls pattern.render()"| CoreRuntime

    %% Click Events
    click CoreRuntime "https://github.com/outsystems/outsystems-ui/tree/dev/src/scripts/OSFramework/OSUI"
    click Patterns "https://github.com/outsystems/outsystems-ui/tree/dev/src/scripts/OSFramework/OSUI/Pattern"
    click Providers "https://github.com/outsystems/outsystems-ui/tree/dev/src/scripts/Providers/OSUI"
    click OutSystemsAPI "https://github.com/outsystems/outsystems-ui/tree/dev/src/scripts/OutSystems/OSUI"
    click SCSS "https://github.com/outsystems/outsystems-ui/tree/dev/src/scss"
    click Gulp "https://github.com/outsystems/outsystems-ui/tree/dev/gulp"
    click TSConfig "https://github.com/outsystems/outsystems-ui/blob/dev/tsconfig.json"
    click PackageJSON "https://github.com/outsystems/outsystems-ui/blob/dev/package.json"
    click Workflows "https://github.com/outsystems/outsystems-ui/tree/dev/.github/workflows"
    click TypeDoc "https://github.com/outsystems/outsystems-ui/blob/dev/typedoc.json"
    click DocsTemplate "https://github.com/outsystems/outsystems-ui/blob/dev/gulp/Template/index.html"
    click README "https://github.com/outsystems/outsystems-ui/blob/dev/README.md"

    %% Styles
    classDef code fill:#E8F1FC,stroke:#0366D6,color:#0366D6;
    classDef build fill:#E6F4EA,stroke:#28A745,color:#28A745;
    classDef docs fill:#FFF4E5,stroke:#D77A02,color:#D77A02;
    classDef external fill:#F3E8FF,stroke:#6F42C1,color:#6F42C1;
```
