# pauljoohyunkim/pp architecture

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

- Interactive diagram: https://gitdiagram.com/pauljoohyunkim/pp
- Repository: https://github.com/pauljoohyunkim/pp

## Overview

PP is a C-implemented programming-language compiler with an LLVM backend. A user invokes the `pplang` command on `.pp` files; the compiler processes source through lexing, parsing, semantic analysis, and LLVM code generation, then emits the requested output. The README also documents optimization, LLVM IR and assembly output, `.ppi` declarations, and multi-source linking. The main source index identifies the pipeline’s stage modules, but unsampled CLI and pipeline internals limit confidence about some detailed call relationships.

Main entry points: [`src/pp_compiler_pipeline.c`](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_compiler_pipeline.c) (Compile Pipeline), [`src/pp_lexer.c`](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_lexer.c) (Lexer), [`src/pp_semantic_analyzer.c`](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_semantic_analyzer.c) (Semantic Analyzer), [`src/pp_parser.c`](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_parser.c) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Frontend"]
  node_lexer["Lexer<br/>[pp_lexer.c]"]
  node_parser["Parser<br/>[pp_parser.c]"]
  node_ast["AST<br/>[pp_ast.c]"]
  node_tokens["Token Definitions<br/>[pp_tokens.c]"]
end

subgraph group_semantic["Semantic Model"]
  node_semantic["Semantic Analyzer"]
  node_symbols["Symbol Tables<br/>[pp_symbol_table.c]"]
  node_types["Type System<br/>[pp_type.c]"]
  node_type_table["Global Type Table<br/>[pp_type_table.c]"]
end

subgraph group_backend["LLVM Backend"]
  node_codegen["LLVM Code Generator"]
  node_optimization["LLVM Optimization"]
end

subgraph group_runtime["Compiler Runtime"]
  node_cli["pplang CLI<br/>[pplang.c]"]
  node_pipeline["Compile Pipeline"]
  node_linker["Linker Offload"]
  node_strings["String Pool<br/>[pp_string_pool.c]"]
  node_errors["Error Handling<br/>[pp_error.c]"]
end

node_user(("Compiler User"))
node_llvm["LLVM"]
node_output["Compiled Output"]

node_user -->|"invokes"| node_cli
node_cli -->|"starts compile"| node_pipeline
node_pipeline -->|"lexes source"| node_lexer
node_pipeline -->|"parses tokens"| node_parser
node_pipeline -->|"checks semantics"| node_semantic
node_pipeline -->|"generates LLVM"| node_codegen
node_pipeline -->|"optimizes output"| node_optimization
node_lexer -->|"creates tokens"| node_tokens
node_parser -->|"builds AST"| node_ast
node_semantic -->|"populates symbols"| node_symbols
node_semantic -->|"populates types"| node_type_table
node_semantic -->|"checks types"| node_types
node_codegen -->|"emits LLVM IR"| node_llvm
node_optimization -->|"optimizes IR"| node_llvm
node_pipeline -->|"emits artifact"| node_output
node_cli -->|"links sources"| node_linker
node_lexer -->|"interns lexemes"| node_strings
node_lexer -->|"reports errors"| node_errors
node_parser -->|"reports errors"| node_errors

click node_cli "https://github.com/pauljoohyunkim/pp/blob/main/src/pplang.c"
click node_pipeline "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_compiler_pipeline.c"
click node_lexer "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_lexer.c"
click node_parser "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_parser.c"
click node_ast "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_ast.c"
click node_semantic "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_semantic_analyzer.c"
click node_symbols "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_symbol_table.c"
click node_types "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_type.c"
click node_type_table "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_type_table.c"
click node_codegen "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_code_generator.c"
click node_optimization "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_code_optimization.c"
click node_linker "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_linker_offload.c"
click node_tokens "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_tokens.c"
click node_strings "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_string_pool.c"
click node_errors "https://github.com/pauljoohyunkim/pp/blob/main/src/pp_error.c"

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_lexer,node_parser,node_ast,node_tokens,node_user toneBlue
class node_semantic,node_symbols,node_types,node_type_table toneAmber
class node_codegen,node_optimization toneMint
class node_cli,node_pipeline,node_linker,node_strings,node_errors toneRose
class node_llvm,node_output toneIndigo
```

## Components

### Frontend

- [Lexer](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_lexer.c): `src/pp_lexer.c`
- [Parser](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_parser.c): `src/pp_parser.c`
- [AST](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_ast.c): `src/pp_ast.c`
- [Token Definitions](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_tokens.c): `src/pp_tokens.c`

### Semantic Model

- [Semantic Analyzer](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_semantic_analyzer.c): `src/pp_semantic_analyzer.c`
- [Symbol Tables](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_symbol_table.c): `src/pp_symbol_table.c`
- [Type System](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_type.c): `src/pp_type.c`
- [Global Type Table](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_type_table.c): `src/pp_type_table.c`

### LLVM Backend

- [LLVM Code Generator](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_code_generator.c): `src/pp_code_generator.c`
- [LLVM Optimization](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_code_optimization.c): `src/pp_code_optimization.c`

### Compiler Runtime

- [pplang CLI](https://github.com/pauljoohyunkim/pp/blob/main/src/pplang.c): `src/pplang.c`
- [Compile Pipeline](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_compiler_pipeline.c): `src/pp_compiler_pipeline.c`
- [Linker Offload](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_linker_offload.c): `src/pp_linker_offload.c`
- [String Pool](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_string_pool.c): `src/pp_string_pool.c`
- [Error Handling](https://github.com/pauljoohyunkim/pp/blob/main/src/pp_error.c): `src/pp_error.c`

### Other components

- **Compiler User**
- **LLVM**
- **Compiled Output**

## Connections

- Compiler User → pplang CLI: invokes (evidence: `README.md`)
- pplang CLI → Compile Pipeline: starts compile (evidence: `src/pplang.c`)
- Compile Pipeline → Lexer: lexes source (evidence: `README.md`)
- Compile Pipeline → Parser: parses tokens (evidence: `README.md`)
- Compile Pipeline → Semantic Analyzer: checks semantics (evidence: `README.md`)
- Compile Pipeline → LLVM Code Generator: generates LLVM (evidence: `README.md`)
- Compile Pipeline → LLVM Optimization: optimizes output (evidence: `src/pp_compiler_pipeline.c`)
- Lexer → Token Definitions: creates tokens (evidence: `src/pp_lexer.c`)
- Parser → AST: builds AST (evidence: `src/pp_parser.c`)
- Semantic Analyzer → Symbol Tables: populates symbols
- Semantic Analyzer → Global Type Table: populates types
- Semantic Analyzer → Type System: checks types
- LLVM Code Generator → LLVM: emits LLVM IR
- LLVM Optimization → LLVM: optimizes IR
- Compile Pipeline → Compiled Output: emits artifact
- pplang CLI → Linker Offload: links sources (evidence: `README.md`)
- Lexer → String Pool: interns lexemes (evidence: `src/pp_lexer.c`)
- Lexer → Error Handling: reports errors (evidence: `src/pp_lexer.c`)
- Parser → Error Handling: reports errors
