# paumen/css-promptify architecture

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

- Interactive diagram: https://gitdiagram.com/paumen/css-promptify
- Repository: https://github.com/paumen/css-promptify

## Overview

##### Project type and purpose
- This is an open-source, browser-based CSS review tool (“CSS Promptify”) with an accompanying LLM context/spec pack.
- It ships as a single-page application (SPA) built with React + TypeScript + Vite, and implements a CSS parser + rule-engine entirely in the client.
- The repo also contains a comprehensive “spec” directory (source of truth for rules and product documentation), CI workflows, example generators, and test artifacts.

##### File structure
- Top-level directories:
- app/           → the SPA implementation
- spec/          → product requirement docs & rulebook
- scripts/       → codegen scripts (e.g. generate examples)
- tests/         → validation reports + sample CSS
- .github/       → CI: linting and type-checking workflows
- Inside app/:
- src/parser     → CSS parser module (AST generation)
- src/engine     → rule engine runner & orchestrator
- src/rules      → individual rule definitions (format, style, safety, tokens, modern, education, consolidation)
- src/state      → session-only settings and data store
- src/ui         → React components & panels (Input, Issues, Output, Settings, primitives)
- Build/config: Vite (vite.config.ts), tsconfig, ESLint, package.json.

##### README for additional insights
- The spec (in spec/PRD_BUILD_SPEC.md) is the source of truth for feature requirements and the rulebook.
- No backend or external service calls are implemented: all rule evaluation happens client-side.
- LLM integration consists of a “prompt export” feature—not an API call—from within the UI.

a. Main components
- Browser SPA Container
- UI Layer
– InputPanel (user pastes CSS)
– SettingsPanel (rule toggles)
– IssuesPanel (error/warning/info display)
– OutputPanel (cleaned CSS & fix comments, prompt export)
- Application Core
– State Manager (holds CSS text, settings, engine results)
– Parser Module (CSS → AST)
– Rule Engine
· Rule Dispatcher
· Rule Modules (format, style, safety, modern, tokens, education, consolidation)
- Spec & Context Pack (non-runtime docs)
- CI Pipeline (GitHub Actions for lint/typecheck)
b. Relationships / Data Flow
1. User CSS input → State
2. State triggers Parser → AST
3. AST + Settings → Rule Engine → Diagnostics & Fix Suggestions
4. Engine Output → State → UI Panels render issues & output
5. Prompt Export reads Engine Output + Spec Rules → text for LLM
c. Architectural patterns / principles
– Modular rule plugins: each rule is self-contained and registered via an index.
– Unidirectional data flow: input → parser → engine → UI render.
– Client-only architecture: no server, session-only state.
– Separation of concerns: parser, engine, rules, UI, and docs each in their own directory.
d. Key technologies
- React + TypeScript + Vite
- CSS Modules for styling components
- ESLint + Prettier for code quality
- GitHub Actions (super-linter, typecheck)
- Node.js scripts for codegen (scripts/generate-examples-md.js)

##### Essential elements
- In-browser state store as the single source of truth for UI and engine.
- Local codegen script and spec directory to illustrate documentation is part of system health.
- Document the CI workflows as a separate “DevOps” lane to show how quality gates are applied.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% DevOps & Documentation
  subgraph "DevOps & Docs"
    direction TB
    SpecDocs["Spec & Context Pack"]:::docs
    Codegen["Codegen Scripts"]:::scripts
    CI_Lint["GitHub Actions: Linting"]:::ci
    CI_Type["GitHub Actions: Type Checking"]:::ci
  end

  %% Application Runtime
  subgraph "Browser-based SPA Runtime"
    direction TB
    Browser["Browser SPA Container"]:::container
    Entry["SPA Entry Point"]:::container
    State["State Manager"]:::core
    Parser["Parser Module"]:::core
    Engine["Rule Engine Core"]:::core
    subgraph "Rule Modules"
      direction TB
      Format["Rule: Format"]:::rules
      Style["Rule: Style"]:::rules
      Safety["Rule: Safety"]:::rules
      Modern["Rule: Modern"]:::rules
      Tokens["Rule: Tokens"]:::rules
      Education["Rule: Education"]:::rules
      Consolidation["Rule: Consolidation"]:::rules
    end
    subgraph "UI Layer"
      direction TB
      InputPanel["InputPanel"]:::ui
      SettingsPanel["SettingsPanel"]:::ui
      IssuesPanel["IssuesPanel"]:::ui
      OutputPanel["OutputPanel"]:::ui
      Primitives["UI Primitives"]:::ui
    end
    PromptExport["Prompt Export"]:::core
  end

  %% Application Build Config
  subgraph "Build & Config"
    direction TB
    ViteConfig["Vite Config"]:::config
    TSConfig["TypeScript Configs"]:::config
    ESLintCfg["ESLint Config"]:::config
    Types["Type Definitions"]:::config
    StylesTokens["Styling Tokens"]:::config
  end

  %% Test & Samples
  subgraph "Testing & Samples"
    direction TB
    RuleTests["Rule Tests"]:::tests
    TestSetup["Test Setup"]:::tests
    SampleArtifacts["Sample/Test Artifacts"]:::tests
  end

  %% Relationships
  Browser --> Entry
  Entry --> State
  State --> Parser
  Parser --> Engine
  Engine --> State
  State --> InputPanel
  State --> SettingsPanel
  Engine --> IssuesPanel
  State --> OutputPanel
  Engine --> PromptExport
  SpecDocs -->|informs| Engine
  Codegen --> SpecDocs
  CI_Lint -->|quality gate| Entry
  CI_Type -->|quality gate| Entry

  %% Click Events
  click Browser "https://github.com/paumen/css-promptify/blob/main/app/index.html"
  click Entry "https://github.com/paumen/css-promptify/blob/main/app/src/main.tsx"
  click InputPanel "https://github.com/paumen/css-promptify/blob/main/app/src/ui/InputPanel.tsx"
  click SettingsPanel "https://github.com/paumen/css-promptify/blob/main/app/src/ui/SettingsPanel.tsx"
  click IssuesPanel "https://github.com/paumen/css-promptify/blob/main/app/src/ui/IssuesPanel.tsx"
  click OutputPanel "https://github.com/paumen/css-promptify/blob/main/app/src/ui/OutputPanel.tsx"
  click Primitives "https://github.com/paumen/css-promptify/tree/main/app/src/ui/primitives"
  click State "https://github.com/paumen/css-promptify/blob/main/app/src/state/index.ts"
  click Parser "https://github.com/paumen/css-promptify/blob/main/app/src/parser/index.ts"
  click Engine "https://github.com/paumen/css-promptify/blob/main/app/src/engine/index.ts"
  click Consolidation "https://github.com/paumen/css-promptify/tree/main/app/src/rules/consolidation"
  click Education "https://github.com/paumen/css-promptify/tree/main/app/src/rules/education"
  click Format "https://github.com/paumen/css-promptify/tree/main/app/src/rules/format"
  click Modern "https://github.com/paumen/css-promptify/tree/main/app/src/rules/modern"
  click Safety "https://github.com/paumen/css-promptify/tree/main/app/src/rules/safety"
  click Style "https://github.com/paumen/css-promptify/tree/main/app/src/rules/style"
  click Tokens "https://github.com/paumen/css-promptify/tree/main/app/src/rules/tokens"
  click Types "https://github.com/paumen/css-promptify/blob/main/app/src/types/index.ts"
  click RuleTests "https://github.com/paumen/css-promptify/blob/main/app/src/rules/rules.test.ts"
  click TestSetup "https://github.com/paumen/css-promptify/blob/main/app/src/test/setup.ts"
  click StylesTokens "https://github.com/paumen/css-promptify/blob/main/app/src/styles/tokens.css"
  click ViteConfig "https://github.com/paumen/css-promptify/blob/main/app/vite.config.ts"
  click TSConfig "https://github.com/paumen/css-promptify/blob/main/app/tsconfig.json"
  click ESLintCfg "https://github.com/paumen/css-promptify/blob/main/app/eslint.config.js"
  click SpecDocs "https://github.com/paumen/css-promptify/tree/main/spec/"
  click Codegen "https://github.com/paumen/css-promptify/blob/main/scripts/generate-examples-md.js"
  click CI_Lint "https://github.com/paumen/css-promptify/blob/main/.github/workflows/super-linter.yml"
  click CI_Type "https://github.com/paumen/css-promptify/blob/main/.github/workflows/typecheck.yml"
  click SampleArtifacts "https://github.com/paumen/css-promptify/tree/main/tests/"

  %% Styles
  classDef ui fill:#D0E8FF,stroke:#0266C8,color:#000;
  classDef core fill:#DFF7DF,stroke:#228B22,color:#000;
  classDef rules fill:#E8F4FF,stroke:#1C388F,color:#000;
  classDef container fill:#FFF4E5,stroke:#FFA500,color:#000;
  classDef docs fill:#FFEACC,stroke:#FF8C00,color:#000;
  classDef scripts fill:#F3E5F5,stroke:#8E24AA,color:#000;
  classDef ci fill:#F0F0F0,stroke:#A9A9A9,color:#000;
  classDef config fill:#E8E8FF,stroke:#5F4B8B,color:#000;
  classDef tests fill:#FFF0F5,stroke:#C71585,color:#000;
```
