# n1stre/rececss architecture

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

- Interactive diagram: https://gitdiagram.com/n1stre/rececss
- Repository: https://github.com/n1stre/rececss

## Overview

##### Project type and purpose
- This is an open-source, monorepo-style CSS utilities generator (rececss).
- It exposes a CLI, a core “engine,” framework-specific adapters (React, Vue, Vanilla), and a documentation website built with Next.js.

##### High-level file-structure analysis
- Root
- package.json (npm workspaces)
- .github/workflows (CI/CD)
- packages/rececss-core
- Implements core logic in Clean Architecture layers:
– 1_entities (Ruleset, Stylesheet)
– 2_usecases (BuildRulesets, GenerateStylesheetAssets)
– 3_adapters (StylesheetsController)
– 4_infrastructures (CLI entrypoint, config loader, FS & IO, CSS processor utilities)
- Exposes: CLI (`npx rececss`), programmatic API
- packages/rececss-components-* (react, vanilla, vue)
- Framework-specific wrappers that import rececss-core output and render live components
- packages/rececss-website
- Next.js app: docs and component previews
- Pulls in core and components packages via local deps, serves as end-user documentation and demo

##### Key README insights
- Customizable output (path, filename, splitByMedia)
- Rules, media queries, states, CSS generation pipelines
- Motivation: extendable, range support, custom pseudo-states

##### Diagramming the architecture
a. Main components
- CLI (rececss command)
- Core engine (UseCases + Entities + Adapters)
- Infrastructures:
– Config loader
– Filesystem/IO
– CSS Processor utilities
- Framework Adapters (React, Vue, Vanilla)
- Documentation site (Next.js)
- External: NPM registry, GitHub Actions (CI), end-users/projects
b. Relationships & data flow
- CLI → invokes Core UseCases (BuildRulesets, GenerateStylesheetAssets)
- Core UseCases → read config via Config loader (infra) → fetch rules definitions → produce CSS AST → write output via FS/IO (infra)
- Adapters (3_adapters) → expose programmatic API for other tools (e.g. component packages)
- Component packages → import core API → subscribe to generated CSS or call core at build time
- Website → imports core & components → fetches docs markdown → builds pages via Next.js → serves to browser
- CI workflows → build/test core, publish to NPM, deploy docs site
c. Architectural patterns & design principles
- Hexagonal/Clean architecture in rececss-core (layers: entities, usecases, adapters, infrastructures)
- Monorepo npm workspaces for shared deps & versioning
- Separation of concerns: core engine vs. UI/demo layers
d. Key technologies/frameworks
- Node.js, TypeScript, Jest (core tests)
- npm Workspaces / .npmignore / .np-config.json
- Next.js (docs site), React, Vue, Vanilla JS (component packages)
- GitHub Actions (CI), PurgeCSS recommendation

##### Be comprehensive but focused
- Four Clean Architecture layers in rececss-core
- How the monorepo structure supports multiple package outputs
- Data flow: config → generation → output → consumption by downstream packages/site
- Avoid over-splitting: group related adapters or infra blocks but call out key pieces (CLI vs. Config vs. FS)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (rececss)"]:::cli
    end

    %% Core Engine - Clean Architecture Layers
    subgraph "rececss-core (Core Engine)"
        direction TB
        Entities["Entities"]:::core
        UseCases["Use Cases"]:::core
        Adapters["Adapters"]:::adapter
        subgraph "Infrastructures"
            direction TB
            ConfigLoader["Config Loader"]:::infra
            FSIO["FS & IO"]:::infra
            CSSUtils["CSS Processor Utilities"]:::infra
        end
        API["Programmatic API"]:::core
    end

    %% Component Packages
    subgraph "Component Packages"
        ReactPkg["React Adapter"]:::external
        VuePkg["Vue Adapter"]:::external
        VanillaPkg["Vanilla Adapter"]:::external
    end

    %% Documentation Site
    Docs["Docs Website (Next.js)"]:::docs

    %% External Services
    NPMRegistry["NPM Registry"]:::storage
    CI["GitHub Actions (CI/CD)"]:::ci
    Browser["Web Browser"]:::external

    %% Relationships
    CLI -->|"invoke UseCases"| UseCases
    UseCases -->|"load config"| ConfigLoader
    UseCases -->|"use rules/entities"| Entities
    UseCases -->|"process CSS AST"| CSSUtils
    UseCases -->|"write output"| FSIO
    API -->|"calls UseCases"| UseCases
    Adapters -->|"expose API"| API
    ReactPkg -->|"import API"| API
    VuePkg -->|"import API"| API
    VanillaPkg -->|"import API"| API
    Docs -->|"import core & components"| API
    Docs -->|"serve to"| Browser
    CI -->|"build/test/publish"| NPMRegistry
    CI -->|"deploy docs"| Docs

    %% Click Events
    click CLI "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/cli.ts"
    click CLI "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/4_infrastructures/cli/index.ts"
    click Entities "https://github.com/n1stre/rececss/tree/master/packages/rececss-core/src/1_entities"
    click UseCases "https://github.com/n1stre/rececss/tree/master/packages/rececss-core/src/2_usecases"
    click Adapters "https://github.com/n1stre/rececss/tree/master/packages/rececss-core/src/3_adapters"
    click ConfigLoader "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/4_infrastructures/config/Config.ts"
    click FSIO "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/4_infrastructures/fs/NodeFS.ts"
    click FSIO "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/4_infrastructures/io/ConfigFileSystemIO.ts"
    click CSSUtils "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/4_infrastructures/utils/CSSProcessor.ts"
    click API "https://github.com/n1stre/rececss/blob/master/packages/rececss-core/src/index.ts"
    click ReactPkg "https://github.com/n1stre/rececss/tree/master/packages/rececss-components-react"
    click VuePkg "https://github.com/n1stre/rececss/tree/master/packages/rececss-components-vue"
    click VanillaPkg "https://github.com/n1stre/rececss/tree/master/packages/rececss-components-vanilla"
    click Docs "https://github.com/n1stre/rececss/tree/master/packages/rececss-website"
    click CI "https://github.com/n1stre/rececss/blob/master/.github/workflows/node.js.yml"
    click CI "https://github.com/n1stre/rececss/blob/master/.github/workflows/gh-pages.yml"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef infra fill:#bbf,stroke:#333,stroke-width:1px
    classDef cli fill:#fbf,stroke:#333,stroke-width:1px
    classDef adapter fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffe,stroke:#333,stroke-width:1px
    classDef docs fill:#fcf,stroke:#333,stroke-width:1px
    classDef ci fill:#fcc,stroke:#333,stroke-width:1px
    classDef storage fill:#cff,stroke:#333,stroke-width:1px
```
