# postcss/postcss architecture

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

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

## Overview

PostCSS is a JavaScript framework for transforming CSS and other stylesheet syntaxes with plugins. The principal workflow is: a caller configures a processor, supplies CSS, plugins visit and modify the parsed syntax tree, and PostCSS returns generated CSS and source-map information. The graph separates processing, parsing and input handling, the mutable AST, and output and diagnostics. Core call relationships are supported by the excerpts or SOURCE INDEX; broader syntax-extension capabilities are documented in the README, but their external implementations are not in this repository.

Main entry points: [`lib/parser.js`](https://github.com/postcss/postcss/blob/main/lib/parser.js) (CSS parser), [`lib/lazy-result.js`](https://github.com/postcss/postcss/blob/main/lib/lazy-result.js) (Plugin execution), [`lib/input.js`](https://github.com/postcss/postcss/blob/main/lib/input.js) (CSS input), [`lib/container.js`](https://github.com/postcss/postcss/blob/main/lib/container.js) (AST container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_processing["Processing API"]
  node_api["Public API<br/>[postcss.js]"]
  node_processor["Processor<br/>[processor.js]"]
  node_lazy["Plugin execution<br/>[lazy-result.js]"]
end

subgraph group_parsing["Parsing and Input"]
  node_input["CSS input<br/>[input.js]"]
  node_parse["Parse entry<br/>[parse.js]"]
  node_parser["CSS parser<br/>[parser.js]"]
  node_tokenizer["Tokenizer<br/>[tokenize.js]"]
  node_syntax["Syntax extensions"]
end

subgraph group_ast["Stylesheet AST"]
  node_node["Base node<br/>[node.js]"]
  node_container["AST container<br/>[container.js]"]
  node_root["Root tree<br/>[root.js]"]
  node_document["Document tree<br/>[document.js]"]
  node_rule["Rules<br/>[rule.js]"]
  node_atrule["At-rules<br/>[at-rule.js]"]
  node_declaration["Declarations<br/>[declaration.js]"]
  node_comment["Comments<br/>[comment.js]"]
  node_json["AST deserialization<br/>[fromJSON.js]"]
end

subgraph group_output["Output and Diagnostics"]
  node_stringify["Stringify entry<br/>[stringify.js]"]
  node_stringifier["CSS generation<br/>[stringifier.js]"]
  node_maps["Source maps<br/>[map-generator.js]"]
  node_previousmap["Previous maps<br/>[previous-map.js]"]
  node_result["Processing result<br/>[result.js]"]
  node_warning["Warnings<br/>[warning.js]"]
  node_syntaxerror["Syntax errors"]
end

node_caller(("CSS caller"))
node_plugins(("PostCSS plugins"))

node_caller -->|"uses"| node_api
node_plugins -->|"register callbacks"| node_lazy
node_api -->|"creates"| node_processor
node_api -->|"exposes"| node_parse
node_api -->|"exposes"| node_json
node_processor -->|"creates result"| node_lazy
node_lazy -->|"constructs"| node_input
node_lazy -->|"parses CSS"| node_parse
node_parse -->|"creates input"| node_input
node_parse -->|"invokes"| node_parser
node_parser -->|"tokenizes"| node_tokenizer
node_parser -->|"builds tree"| node_root
node_parser -->|"creates nodes"| node_rule
node_parser -->|"creates nodes"| node_atrule
node_parser -->|"creates nodes"| node_declaration
node_parser -->|"creates nodes"| node_comment
node_container -->|"extends"| node_node
node_rule -->|"extends"| node_container
node_root -->|"extends"| node_container
node_document -->|"extends"| node_container
node_atrule -->|"extends"| node_container
node_declaration -->|"extends"| node_node
node_comment -->|"extends"| node_node
node_lazy -->|"generates CSS"| node_stringify
node_stringify -->|"uses"| node_stringifier
node_lazy -->|"generates maps"| node_maps
node_maps -->|"reads source"| node_input
node_input -->|"loads prior map"| node_previousmap
node_lazy -->|"creates result"| node_result
node_result -->|"creates warnings"| node_warning
node_input -->|"reports errors"| node_syntaxerror
node_node -->|"creates errors"| node_syntaxerror
node_caller -.->|"can supply syntax"| node_syntax

click node_api "https://github.com/postcss/postcss/blob/main/lib/postcss.js"
click node_processor "https://github.com/postcss/postcss/blob/main/lib/processor.js"
click node_lazy "https://github.com/postcss/postcss/blob/main/lib/lazy-result.js"
click node_input "https://github.com/postcss/postcss/blob/main/lib/input.js"
click node_parse "https://github.com/postcss/postcss/blob/main/lib/parse.js"
click node_parser "https://github.com/postcss/postcss/blob/main/lib/parser.js"
click node_tokenizer "https://github.com/postcss/postcss/blob/main/lib/tokenize.js"
click node_syntax "https://github.com/postcss/postcss/tree/main/lib"
click node_node "https://github.com/postcss/postcss/blob/main/lib/node.js"
click node_container "https://github.com/postcss/postcss/blob/main/lib/container.js"
click node_root "https://github.com/postcss/postcss/blob/main/lib/root.js"
click node_document "https://github.com/postcss/postcss/blob/main/lib/document.js"
click node_rule "https://github.com/postcss/postcss/blob/main/lib/rule.js"
click node_atrule "https://github.com/postcss/postcss/blob/main/lib/at-rule.js"
click node_declaration "https://github.com/postcss/postcss/blob/main/lib/declaration.js"
click node_comment "https://github.com/postcss/postcss/blob/main/lib/comment.js"
click node_stringify "https://github.com/postcss/postcss/blob/main/lib/stringify.js"
click node_stringifier "https://github.com/postcss/postcss/blob/main/lib/stringifier.js"
click node_maps "https://github.com/postcss/postcss/blob/main/lib/map-generator.js"
click node_previousmap "https://github.com/postcss/postcss/blob/main/lib/previous-map.js"
click node_result "https://github.com/postcss/postcss/blob/main/lib/result.js"
click node_warning "https://github.com/postcss/postcss/blob/main/lib/warning.js"
click node_syntaxerror "https://github.com/postcss/postcss/blob/main/lib/css-syntax-error.js"
click node_json "https://github.com/postcss/postcss/blob/main/lib/fromJSON.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_processor,node_lazy toneBlue
class node_input,node_parse,node_parser,node_tokenizer,node_syntax toneAmber
class node_node,node_container,node_root,node_document,node_rule,node_atrule,node_declaration,node_comment,node_json toneMint
class node_stringify,node_stringifier,node_maps,node_previousmap,node_result,node_warning,node_syntaxerror toneRose
class node_caller,node_plugins toneIndigo
```

## Components

### Processing API

- [Public API](https://github.com/postcss/postcss/blob/main/lib/postcss.js): `lib/postcss.js`
- [Processor](https://github.com/postcss/postcss/blob/main/lib/processor.js): `lib/processor.js`
- [Plugin execution](https://github.com/postcss/postcss/blob/main/lib/lazy-result.js): `lib/lazy-result.js`

### Parsing and Input

- [CSS input](https://github.com/postcss/postcss/blob/main/lib/input.js): `lib/input.js`
- [Parse entry](https://github.com/postcss/postcss/blob/main/lib/parse.js): `lib/parse.js`
- [CSS parser](https://github.com/postcss/postcss/blob/main/lib/parser.js): `lib/parser.js`
- [Tokenizer](https://github.com/postcss/postcss/blob/main/lib/tokenize.js): `lib/tokenize.js`
- [Syntax extensions](https://github.com/postcss/postcss/tree/main/lib): `lib`

### Stylesheet AST

- [Base node](https://github.com/postcss/postcss/blob/main/lib/node.js): `lib/node.js`
- [AST container](https://github.com/postcss/postcss/blob/main/lib/container.js): `lib/container.js`
- [Root tree](https://github.com/postcss/postcss/blob/main/lib/root.js): `lib/root.js`
- [Document tree](https://github.com/postcss/postcss/blob/main/lib/document.js): `lib/document.js`
- [Rules](https://github.com/postcss/postcss/blob/main/lib/rule.js): `lib/rule.js`
- [At-rules](https://github.com/postcss/postcss/blob/main/lib/at-rule.js): `lib/at-rule.js`
- [Declarations](https://github.com/postcss/postcss/blob/main/lib/declaration.js): `lib/declaration.js`
- [Comments](https://github.com/postcss/postcss/blob/main/lib/comment.js): `lib/comment.js`
- [AST deserialization](https://github.com/postcss/postcss/blob/main/lib/fromJSON.js): `lib/fromJSON.js`

### Output and Diagnostics

- [Stringify entry](https://github.com/postcss/postcss/blob/main/lib/stringify.js): `lib/stringify.js`
- [CSS generation](https://github.com/postcss/postcss/blob/main/lib/stringifier.js): `lib/stringifier.js`
- [Source maps](https://github.com/postcss/postcss/blob/main/lib/map-generator.js): `lib/map-generator.js`
- [Previous maps](https://github.com/postcss/postcss/blob/main/lib/previous-map.js): `lib/previous-map.js`
- [Processing result](https://github.com/postcss/postcss/blob/main/lib/result.js): `lib/result.js`
- [Warnings](https://github.com/postcss/postcss/blob/main/lib/warning.js): `lib/warning.js`
- [Syntax errors](https://github.com/postcss/postcss/blob/main/lib/css-syntax-error.js): `lib/css-syntax-error.js`

### Other components

- **CSS caller**
- **PostCSS plugins**

## Connections

- CSS caller → Public API: uses (evidence: `README.md`)
- PostCSS plugins → Plugin execution: register callbacks (evidence: `lib/lazy-result.js`)
- Public API → Processor: creates (evidence: `lib/postcss.js`)
- Public API → Parse entry: exposes (evidence: `lib/postcss.js`)
- Public API → AST deserialization: exposes (evidence: `lib/postcss.js`)
- Processor → Plugin execution: creates result (evidence: `lib/processor.js`)
- Plugin execution → CSS input: constructs (evidence: `lib/lazy-result.js`)
- Plugin execution → Parse entry: parses CSS (evidence: `lib/lazy-result.js`)
- Parse entry → CSS input: creates input (evidence: `lib/parse.js`)
- Parse entry → CSS parser: invokes (evidence: `lib/parse.js`)
- CSS parser → Tokenizer: tokenizes (evidence: `lib/parser.js`)
- CSS parser → Root tree: builds tree (evidence: `lib/parser.js`)
- CSS parser → Rules: creates nodes (evidence: `lib/parser.js`)
- CSS parser → At-rules: creates nodes (evidence: `lib/parser.js`)
- CSS parser → Declarations: creates nodes (evidence: `lib/parser.js`)
- CSS parser → Comments: creates nodes (evidence: `lib/parser.js`)
- AST container → Base node: extends (evidence: `lib/container.js`)
- Rules → AST container: extends (evidence: `lib/rule.js`)
- Root tree → AST container: extends (evidence: `lib/root.js`)
- Document tree → AST container: extends (evidence: `lib/document.js`)
- At-rules → AST container: extends (evidence: `lib/at-rule.js`)
- Declarations → Base node: extends (evidence: `lib/declaration.js`)
- Comments → Base node: extends (evidence: `lib/comment.js`)
- Plugin execution → Stringify entry: generates CSS (evidence: `lib/lazy-result.js`)
- Stringify entry → CSS generation: uses (evidence: `lib/stringify.js`)
- Plugin execution → Source maps: generates maps (evidence: `lib/lazy-result.js`)
- Source maps → CSS input: reads source (evidence: `lib/map-generator.js`)
- CSS input → Previous maps: loads prior map (evidence: `lib/input.js`)
- Plugin execution → Processing result: creates result (evidence: `lib/lazy-result.js`)
- Processing result → Warnings: creates warnings (evidence: `lib/result.js`)
- CSS input → Syntax errors: reports errors (evidence: `lib/input.js`)
- Base node → Syntax errors: creates errors (evidence: `lib/node.js`)
- CSS caller → Syntax extensions: can supply syntax (evidence: `README.md`)