# naganowl/postcss-squeaky-clean architecture

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

- Interactive diagram: https://gitdiagram.com/naganowl/postcss-squeaky-clean
- Repository: https://github.com/naganowl/postcss-squeaky-clean

## Overview

##### Project type and purpose
- This is an open-source Node.js tool (a PostCSS-based CSS/SCSS transformation library) whose purpose is to automate the transition from global SCSS stylesheets to localized CSS modules. It achieves this by exposing a series of plugins, helpers, and scripts that perform regex-based class-name rewrites, selector extraction, stylesheet flattening, and analytics of style usage.

##### File structure
- Top-level files
- Configuration: .eslintrc.js, .eslintignore, .gitignore, .npmignore, .travis.yml
- Documentation: README.md, API.md, docs/
- Examples: examples/
- Package manifest: package.json
- Core directories
- plugins/ – each JS file is a PostCSS plugin (analytics, clean, extract, flatten, heuristic, specificity)
- helpers/ – utility functions for file discovery, regex matching, shell invocation
- scripts/ – shell or Node scripts to orchestrate a full conversion run
- specs/ – test suite for each plugin
- Patterns and architecture
- Plugin architecture: each plugin encapsulates a single transformation phase (Phase 1 through Phase 4 described in README)
- Helper modules: share common filesystem logic, regex patterns, naming conventions
- Shell integration: spawned via helpers/run-shell.js to leverage UNIX tools for bulk find/replace

##### README for additional insights
- Phased migration architecture:
- Phase 1: Namespacing with regex-driven class rewrites
- Phase 2: Flattening SCSS nesting into CSS modules
- Phase 3: Heuristic analysis of selector usages
- Phase 4: Cleanup of legacy namespacing
- Emphasis on balancing performance vs. correctness by using RegExps and shell tools instead of full AST parsing
- Public API surface documented in API.md; examples in examples/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "User Interface"
        CLI["CLI / Orchestrator"]:::code
    end

    subgraph "File System"
        direction TB
        InputFiles["Raw SCSS / CSS Files"]:::data
        OutputFiles["Rewritten CSS Modules"]:::data
        StatsFile["stats.json"]:::data
    end

    subgraph "Processing Engine"
        direction TB
        PostCSS["PostCSS Core"]:::code
        subgraph "Plugins Sequence"
            direction TB
            Phase1["analytics plugin"]:::plugin
            Phase2["extract plugin"]:::plugin
            Phase3["flatten plugin"]:::plugin
            Phase4["heuristic plugin"]:::plugin
            Phase5["specificity plugin"]:::plugin
            Phase6["clean plugin"]:::plugin
        end
    end

    subgraph "Helper Library"
        Helpers["helpers/"]:::helper
    end

    subgraph "External Tools"
        BashTools["Bash Tools (grep, sed, awk)"]:::external
    end

    subgraph "Testing & CI"
        direction TB
        Specs["Test Harness (specs/)"]:::test
        ESLint["ESLint Config"]:::file
        CI["Travis CI (.travis.yml)"]:::file
    end

    subgraph "Docs & Examples"
        API["API Documentation (API.md)"]:::file
        README["README.md & docs/"]:::file
        Examples["examples/scss-parser.js"]:::file
    end

    subgraph "Scripts"
        Replace["replace_selectors.sh"]:::file
        Verify["verify-sqkd-class-names.js"]:::file
    end

    %% Connections
    CLI -->|reads files| InputFiles
    CLI -->|invokes| PostCSS
    CLI -->|uses| Helpers
    PostCSS -->|runs| Phase1
    PostCSS -->|runs| Phase2
    PostCSS -->|runs| Phase3
    PostCSS -->|runs| Phase4
    PostCSS -->|runs| Phase5
    PostCSS -->|runs| Phase6
    Phase1 -->|calls| Helpers
    Phase2 -->|calls| Helpers
    Phase3 -->|calls| Helpers
    Phase4 -->|calls| Helpers
    Phase5 -->|calls| Helpers
    Phase6 -->|calls| Helpers
    Phase1 -->|may spawn| BashTools
    Phase2 -->|may spawn| BashTools
    Phase3 -->|may spawn| BashTools
    Phase4 -->|may spawn| BashTools
    Phase5 -->|may spawn| BashTools
    Phase6 -->|may spawn| BashTools
    Phase6 -->|writes| OutputFiles
    PostCSS -->|outputs stats| StatsFile
    Specs -.->|imports| Phase1
    Specs -.->|imports| Phase2
    Specs -.->|imports| Phase3
    Specs -.->|imports| Phase4
    Specs -.->|imports| Phase5
    Specs -.->|imports| Phase6
    CLI -->|orchestrates| Replace
    Replace -->|shell script| BashTools
    CLI -->|verification| Verify

    %% Documentation & CI links
    CLI -.->|docs| README
    CLI -.->|api| API
    CLI -.->|examples| Examples
    Specs -->|linted by| ESLint
    Specs -->|tested on| CI

    %% Click Events
    click Phase1 "https://github.com/naganowl/postcss-squeaky-clean/blob/master/plugins/analytics.js"
    click Phase2 "https://github.com/naganowl/postcss-squeaky-clean/blob/master/plugins/extract.js"
    click Phase3 "https://github.com/naganowl/postcss-squeaky-clean/blob/master/plugins/flatten.js"
    click Phase4 "https://github.com/naganowl/postcss-squeaky-clean/blob/master/plugins/heuristic.js"
    click Phase5 "https://github.com/naganowl/postcss-squeaky-clean/blob/master/plugins/specificity.js"
    click Phase6 "https://github.com/naganowl/postcss-squeaky-clean/blob/master/plugins/clean.js"
    click Helpers "https://github.com/naganowl/postcss-squeaky-clean/tree/master/helpers/"
    click Replace "https://github.com/naganowl/postcss-squeaky-clean/blob/master/scripts/replace_selectors.sh"
    click Verify "https://github.com/naganowl/postcss-squeaky-clean/blob/master/scripts/verify-sqkd-class-names.js"
    click Specs "https://github.com/naganowl/postcss-squeaky-clean/tree/master/specs/"
    click API "https://github.com/naganowl/postcss-squeaky-clean/blob/master/API.md"
    click README "https://github.com/naganowl/postcss-squeaky-clean/blob/master/README.md"
    click Examples "https://github.com/naganowl/postcss-squeaky-clean/blob/master/examples/scss-parser.js"
    click ESLint "https://github.com/naganowl/postcss-squeaky-clean/blob/master/.eslintrc.js"
    click CI "https://github.com/naganowl/postcss-squeaky-clean/blob/master/.travis.yml"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef plugin fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef helper fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef external fill:#FAD7A0,stroke:#B9770E,color:#7E5109;
    classDef data fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef test fill:#E8DAEF,stroke:#6C3483,color:#4A235A;
    classDef file fill:#A9DFBF,stroke:#229954,color:#145A32;
```
