# leonardoventurini/meteor-scss architecture

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

- Interactive diagram: https://gitdiagram.com/leonardoventurini/meteor-scss
- Repository: https://github.com/leonardoventurini/meteor-scss

## Overview

##### Project Type and Purpose
- This project is a Meteor build plugin designed to compile Sass files by integrating node-sass into the Meteor build process.
- Its primary role is to automatically detect, compile, and bundle all .scss and .sass files (except imports) within a Meteor project.
- Being a plugin, it interfaces deeply with Meteor’s build toolchain and package system.

##### File Structure
- Top-Level Files: Configuration files (.editorconfig, .eslintrc.js, .prettierrc.js, .travis.yml, etc.) support code quality and build processes.
- package.js & package.json: These files indicate how the package is registered and declare dependencies, configuration options, and Meteor-specific settings including isImport flags.
- Plugin Directory: Contains multiple JavaScript files (e.g., compile-scss.js, sass-compiler.js, add-underscore.js) that serve as individual building blocks or utilities to handle different aspects of Sass processing like resolving import paths, handling underscore-prefixed partials, and transforming file paths.
- Configuration File: scss-config.json is used to set include paths and other compile options.
- Test Directories: The “test” folder and tests.js include test cases ensuring the correct functioning of file imports and compilation, which can hint at the different workflows built into the system.

##### Insights from the README
- The README explains the plugin’s usage, installation, and integration within Meteor.
- It distinguishes between Sass source files and Sass imports/partials, highlighting how the plugin determines which files to compile.
- It mentions handling imports from packages, apps, and even node_modules (with symlink considerations), showing that the plugin supports flexible file resolution paths.
- External tools: node-sass is used for the actual compilation, and there are instructions regarding global include paths, sourcemaps, and autoprefixer integration.

a. Main Components:
- Meteor Build System: The entry point where the plugin is registered and invoked.
- Plugin Core Modules: Composed of various modules in the ‘plugin’ directory (such as compile-scss.js, sass-compiler.js, etc.) which handle:
- File detection and categorization (differentiating between Sass sources and partials).
- Import resolution and path transformation (e.g., handling underscores, converting standard paths, and symlink handling).
- Sass file compilation via node-sass.
- Configuration and Setup: scss-config.json and package configuration (package.js) that define build settings and include paths.
- Testing Modules: The “test” directory which validates include paths and different Sass file structures.

b. Relationships and Interactions:
- The Meteor build system loads the plugin based on the registration in package.js.
- Once invoked, the plugin scans the project folders for Sass files and delegates them to the appropriate plugin modules.
- The compilation module interacts with node-sass to convert Sass/SCSS to CSS.
- After compilation, the resultant CSS is integrated into the Meteor application bundle.
- Configuration files (including scss-config.json) provide extra parameters (includePaths) that affect how file imports are resolved.
- Tests exercise various file scenarios ensuring that the plugin can resolve files both locally and from external packages or node_modules.

c. Key Architectural Patterns and Design Principles:
- Modular Design: The separation of concerns is clear, as each plugin file is focused on a distinct aspect (e.g., import resolution, file-checks, compilation pipeline).
- Integration with a Larger Ecosystem: The plugin is designed to work seamlessly within the Meteor build plugin framework.
- Extensibility: With clear separation between core file processing and compilation, the design allows future enhancements (e.g., support for dart-sass).

d. Relevant Technologies and External Dependencies:
- Meteor’s Build System and Package Management.
- node-sass for Sass compilation.
- Testing frameworks and configuration tools for quality control (e.g., ESLint, Prettier).

##### Instructing the Principal Software Engineer
– Meteor Build System/Package Registration.
– Plugin Function Modules (with sub-components as needed, e.g., “File Detection” module, “Path Resolution” module, “Sass Compilation” module).
– Configuration/Settings Module.
– External Services (node-sass and possibly autoprefixer if used).
– Testing Suite (to show validation of functionality).
- Use clear, descriptive labels for each component.
– How the build system invokes the plugin.
– Data flow from reading file inputs to passing them through the resolution pipeline to resulting CSS generation.
– Core logic components (plugin modules) vs. configuration files and external dependencies.
– Optional extensions (like nodal symlink handling for node_modules) can be a noted branch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    MBS["Meteor Build System"]:::build
    REG["Package Registration (package.js)"]:::config
    CONFIG_DEP["Build Config (package.json)"]:::config
    CS["Compilation Settings (scss-config.json)"]:::config
    NS["node-sass"]:::external

    subgraph "Plugin Core Modules - File Detection"
        FD1["File Detection (compile-scss.js)"]:::plugin
        FD2["Decode File Path (decode-file-path.js)"]:::plugin
        FD3["File Exists (file-exists.js)"]:::plugin
        FD4["Has Underscore (has-underscore.js)"]:::plugin
    end

    subgraph "Plugin Core Modules - Import Resolution"
        IR1["Add Underscore (add-underscore.js)"]:::plugin
        IR2["Convert to Standard Path (convert-to-standard-path.js)"]:::plugin
        IR3["Create Importer (create-importer.js)"]:::plugin
        IR4["Fix Tilde (fix-tilde.js)"]:::plugin
        IR5["Get Config (get-config.js)"]:::plugin
        IR6["Get Real Import Path (get-real-import-path.js)"]:::plugin
        IR7["Get Real Import Path from Includes (get-real-import-path-from-includes.js)"]:::plugin
        IR8["Replace Package Paths (replace-package-paths.js)"]:::plugin
    end

    SC["Sass Compiler (sass-compiler.js)"]:::plugin

    subgraph "Testing Modules"
        TEST_DIR["Test Directory"]:::test
        TEST_JS["Tests.js"]:::test
    end

    MBS -->|"registers"| REG
    REG -->|"loads"| CONFIG_DEP
    REG -->|"invokes"| FD1
    FD1 --> FD2
    FD2 --> FD3
    FD3 --> FD4
    FD4 -->|"detected files"| IR1
    IR1 --> IR2
    IR2 --> IR3
    IR3 --> IR4
    IR4 --> IR5
    IR5 --> IR6
    IR6 --> IR7
    IR7 --> IR8
    IR8 --> SC
    CS --> SC
    SC -->|"compiles with"| NS
    SC -->|"bundles CSS"| MBS
    TEST_DIR -->|"validates"| FD1
    TEST_JS -->|"tests"| IR1

    click REG "https://github.com/leonardoventurini/meteor-scss/blob/master/package.js"
    click CONFIG_DEP "https://github.com/leonardoventurini/meteor-scss/blob/master/package.json"
    click FD1 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/compile-scss.js"
    click FD2 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/decode-file-path.js"
    click FD3 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/file-exists.js"
    click FD4 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/has-underscore.js"
    click IR1 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/add-underscore.js"
    click IR2 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/convert-to-standard-path.js"
    click IR3 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/create-importer.js"
    click IR4 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/fix-tilde.js"
    click IR5 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/get-config.js"
    click IR6 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/get-real-import-path.js"
    click IR7 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/get-real-import-path-from-includes.js"
    click IR8 "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/replace-package-paths.js"
    click SC "https://github.com/leonardoventurini/meteor-scss/blob/master/plugin/sass-compiler.js"
    click CS "https://github.com/leonardoventurini/meteor-scss/blob/master/scss-config.json"
    click TEST_DIR "https://github.com/leonardoventurini/meteor-scss/tree/master/test"
    click TEST_JS "https://github.com/leonardoventurini/meteor-scss/blob/master/tests.js"

    classDef build fill:#ffcc00,stroke:#333,stroke-width:2px
    classDef config fill:#90ee90,stroke:#333,stroke-width:2px
    classDef plugin fill:#add8e6,stroke:#333,stroke-width:2px
    classDef external fill:#ffa07a,stroke:#333,stroke-width:2px
    classDef test fill:#ffeead,stroke:#333,stroke-width:2px
```
