# sere-language/sere architecture

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

- Interactive diagram: https://gitdiagram.com/sere-language/sere
- Repository: https://github.com/sere-language/sere

## Overview

Sere is a statically typed, ahead-of-time language compiler that produces native executables and `.slib` libraries. The principal workflow starts at the `sere` command, processes source through lexical, syntactic, and semantic stages, then generates and optimizes LLVM code for native output. The repository also includes macro expansion, project and package management, a language server with editor support, and a C/C++ runtime. Several driver and code-generation call sites were not sampled, so those relationships are marked unverified rather than asserted.

Main entry points: [`lib/driver/Frontend.cpp`](https://github.com/sere-language/sere/blob/main/lib/driver/Frontend.cpp) (Frontend), [`lib/lsp/LanguageServer.cpp`](https://github.com/sere-language/sere/blob/main/lib/lsp/LanguageServer.cpp) (Language Server), [`tools/sere/main.cpp`](https://github.com/sere-language/sere/blob/main/tools/sere/main.cpp) (Compiler CLI), [`lib/driver/Compiler.cpp`](https://github.com/sere-language/sere/blob/main/lib/driver/Compiler.cpp) (Compiler Driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler Front End"]
  node_cli["Compiler CLI<br/>[main.cpp]"]
  node_driver["Compiler Driver<br/>[Compiler.cpp]"]
  node_frontend["Frontend<br/>[Frontend.cpp]"]
  node_source["Source Manager<br/>[SourceManager.cpp]"]
  node_lexer["Lexer<br/>[Lexer.cpp]"]
  node_parser["Parser<br/>[Parser.cpp]"]
  node_ast["Syntax AST<br/>[Syntax.cpp]"]
  node_macros["Macro Expander<br/>[Expander.cpp]"]
  node_checker["Type Checker<br/>[TypeChecker.cpp]"]
  node_types["Type Context<br/>[TypeContext.cpp]"]
  node_diagnostics["Diagnostics"]
end

subgraph group_codegen["Native Code Generation"]
  node_ir["LLVM IR Generator<br/>[IRGenerator.cpp]"]
  node_optimization["Optimization Pipeline<br/>[OptPipeline.cpp]"]
  node_backend["Sere LLVM Backend"]
end

subgraph group_projects["Projects And Packages"]
  node_projects["Project Manager<br/>[Project.cpp]"]
  node_packages["Package Manager<br/>[Packages.cpp]"]
  node_registry["Package Registry<br/>[Registry.cpp]"]
  node_installer["Installer<br/>[Installer.cpp]"]
end

subgraph group_editor["Editor Services"]
  node_lsp["Language Server<br/>[LanguageServer.cpp]"]
  node_queries["AST Queries<br/>[Query.cpp]"]
  node_completion["Completion"]
  node_import_completion["Import Completion"]
  node_semantic_tokens["Semantic Tokens<br/>[SemanticTokens.cpp]"]
  node_vscode["VS Code Extension<br/>[extension.js]"]
end

subgraph group_runtime["Runtime"]
  node_runtime["Sere Runtime<br/>[sere_rt.c]"]
  node_stdlib["Standard Library Runtime<br/>[sere_stdlib.c]"]
end

node_user(("Sere Developer"))
node_native["Native Executable"]

node_user -->|"invokes"| node_cli
node_cli -->|"delegates"| node_driver
node_driver -.->|"compiles with"| node_frontend
node_frontend -->|"uses"| node_source
node_frontend -->|"checks with"| node_checker
node_frontend -->|"uses"| node_types
node_lexer -.->|"reads"| node_source
node_parser -->|"uses"| node_lexer
node_parser -->|"builds"| node_ast
node_checker -->|"checks"| node_ast
node_checker -->|"resolves types"| node_types
node_frontend -->|"reports errors"| node_diagnostics
node_macros -->|"reports errors"| node_diagnostics
node_frontend -.->|"expands macros"| node_macros
node_driver -.->|"generates code"| node_ir
node_ir -.->|"optimizes IR"| node_optimization
node_optimization -.->|"lowers LLVM"| node_backend
node_backend -.->|"emits native code"| node_native
node_cli -.->|"manages projects"| node_projects
node_projects -.->|"uses packages"| node_packages
node_packages -.->|"queries registry"| node_registry
node_packages -.->|"installs dependencies"| node_installer
node_user -->|"requests editor help"| node_lsp
node_lsp -->|"analyzes documents"| node_frontend
node_lsp -->|"queries AST"| node_queries
node_lsp -->|"provides completion"| node_completion
node_lsp -->|"completes imports"| node_import_completion
node_lsp -->|"provides tokens"| node_semantic_tokens
node_vscode -.->|"connects to"| node_lsp
node_native -.->|"uses"| node_runtime
node_runtime -.->|"provides"| node_stdlib

click node_cli "https://github.com/sere-language/sere/blob/main/tools/sere/main.cpp"
click node_driver "https://github.com/sere-language/sere/blob/main/lib/driver/Compiler.cpp"
click node_frontend "https://github.com/sere-language/sere/blob/main/lib/driver/Frontend.cpp"
click node_source "https://github.com/sere-language/sere/blob/main/lib/source/SourceManager.cpp"
click node_lexer "https://github.com/sere-language/sere/blob/main/lib/lex/Lexer.cpp"
click node_parser "https://github.com/sere-language/sere/blob/main/lib/parse/Parser.cpp"
click node_ast "https://github.com/sere-language/sere/blob/main/lib/ast/Syntax.cpp"
click node_macros "https://github.com/sere-language/sere/blob/main/lib/macro/Expander.cpp"
click node_checker "https://github.com/sere-language/sere/blob/main/lib/sema/TypeChecker.cpp"
click node_types "https://github.com/sere-language/sere/blob/main/lib/types/TypeContext.cpp"
click node_diagnostics "https://github.com/sere-language/sere/blob/main/lib/diag/DiagnosticEngine.cpp"
click node_ir "https://github.com/sere-language/sere/blob/main/lib/codegen/IRGenerator.cpp"
click node_optimization "https://github.com/sere-language/sere/blob/main/lib/codegen/OptPipeline.cpp"
click node_backend "https://github.com/sere-language/sere/blob/main/lib/codegen/backends/SeremLLVMBackend.cpp"
click node_projects "https://github.com/sere-language/sere/blob/main/lib/driver/Project.cpp"
click node_packages "https://github.com/sere-language/sere/blob/main/lib/driver/Packages.cpp"
click node_registry "https://github.com/sere-language/sere/blob/main/lib/driver/Registry.cpp"
click node_installer "https://github.com/sere-language/sere/blob/main/lib/driver/Installer.cpp"
click node_lsp "https://github.com/sere-language/sere/blob/main/lib/lsp/LanguageServer.cpp"
click node_queries "https://github.com/sere-language/sere/blob/main/lib/ast/Query.cpp"
click node_completion "https://github.com/sere-language/sere/blob/main/lib/lsp/MemberCompletion.cpp"
click node_import_completion "https://github.com/sere-language/sere/blob/main/lib/lsp/ImportCompletion.cpp"
click node_semantic_tokens "https://github.com/sere-language/sere/blob/main/lib/lsp/SemanticTokens.cpp"
click node_vscode "https://github.com/sere-language/sere/blob/main/editors/vscode/extension.js"
click node_runtime "https://github.com/sere-language/sere/blob/main/runtime/sere_rt.c"
click node_stdlib "https://github.com/sere-language/sere/blob/main/runtime/sere_stdlib.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_cli,node_driver,node_frontend,node_source,node_lexer,node_parser,node_ast,node_macros,node_checker,node_types,node_diagnostics toneBlue
class node_ir,node_optimization,node_backend toneAmber
class node_projects,node_packages,node_registry,node_installer toneMint
class node_lsp,node_queries,node_completion,node_import_completion,node_semantic_tokens,node_vscode toneRose
class node_runtime,node_stdlib,node_user,node_native toneIndigo
```

## Components

### Compiler Front End

- [Compiler CLI](https://github.com/sere-language/sere/blob/main/tools/sere/main.cpp): `tools/sere/main.cpp`
- [Compiler Driver](https://github.com/sere-language/sere/blob/main/lib/driver/Compiler.cpp): `lib/driver/Compiler.cpp`
- [Frontend](https://github.com/sere-language/sere/blob/main/lib/driver/Frontend.cpp): `lib/driver/Frontend.cpp`
- [Source Manager](https://github.com/sere-language/sere/blob/main/lib/source/SourceManager.cpp): `lib/source/SourceManager.cpp`
- [Lexer](https://github.com/sere-language/sere/blob/main/lib/lex/Lexer.cpp): `lib/lex/Lexer.cpp`
- [Parser](https://github.com/sere-language/sere/blob/main/lib/parse/Parser.cpp): `lib/parse/Parser.cpp`
- [Syntax AST](https://github.com/sere-language/sere/blob/main/lib/ast/Syntax.cpp): `lib/ast/Syntax.cpp`
- [Macro Expander](https://github.com/sere-language/sere/blob/main/lib/macro/Expander.cpp): `lib/macro/Expander.cpp`
- [Type Checker](https://github.com/sere-language/sere/blob/main/lib/sema/TypeChecker.cpp): `lib/sema/TypeChecker.cpp`
- [Type Context](https://github.com/sere-language/sere/blob/main/lib/types/TypeContext.cpp): `lib/types/TypeContext.cpp`
- [Diagnostics](https://github.com/sere-language/sere/blob/main/lib/diag/DiagnosticEngine.cpp): `lib/diag/DiagnosticEngine.cpp`

### Native Code Generation

- [LLVM IR Generator](https://github.com/sere-language/sere/blob/main/lib/codegen/IRGenerator.cpp): `lib/codegen/IRGenerator.cpp`
- [Optimization Pipeline](https://github.com/sere-language/sere/blob/main/lib/codegen/OptPipeline.cpp): `lib/codegen/OptPipeline.cpp`
- [Sere LLVM Backend](https://github.com/sere-language/sere/blob/main/lib/codegen/backends/SeremLLVMBackend.cpp): `lib/codegen/backends/SeremLLVMBackend.cpp`

### Projects And Packages

- [Project Manager](https://github.com/sere-language/sere/blob/main/lib/driver/Project.cpp): `lib/driver/Project.cpp`
- [Package Manager](https://github.com/sere-language/sere/blob/main/lib/driver/Packages.cpp): `lib/driver/Packages.cpp`
- [Package Registry](https://github.com/sere-language/sere/blob/main/lib/driver/Registry.cpp): `lib/driver/Registry.cpp`
- [Installer](https://github.com/sere-language/sere/blob/main/lib/driver/Installer.cpp): `lib/driver/Installer.cpp`

### Editor Services

- [Language Server](https://github.com/sere-language/sere/blob/main/lib/lsp/LanguageServer.cpp): `lib/lsp/LanguageServer.cpp`
- [AST Queries](https://github.com/sere-language/sere/blob/main/lib/ast/Query.cpp): `lib/ast/Query.cpp`
- [Completion](https://github.com/sere-language/sere/blob/main/lib/lsp/MemberCompletion.cpp): `lib/lsp/MemberCompletion.cpp`
- [Import Completion](https://github.com/sere-language/sere/blob/main/lib/lsp/ImportCompletion.cpp): `lib/lsp/ImportCompletion.cpp`
- [Semantic Tokens](https://github.com/sere-language/sere/blob/main/lib/lsp/SemanticTokens.cpp): `lib/lsp/SemanticTokens.cpp`
- [VS Code Extension](https://github.com/sere-language/sere/blob/main/editors/vscode/extension.js): `editors/vscode/extension.js`

### Runtime

- [Sere Runtime](https://github.com/sere-language/sere/blob/main/runtime/sere_rt.c): `runtime/sere_rt.c`
- [Standard Library Runtime](https://github.com/sere-language/sere/blob/main/runtime/sere_stdlib.c): `runtime/sere_stdlib.c`

### Other components

- **Sere Developer**
- **Native Executable**

## Connections

- Sere Developer → Compiler CLI: invokes (evidence: `README.md`)
- Compiler CLI → Compiler Driver: delegates (evidence: `tools/sere/main.cpp`)
- Compiler Driver → Frontend: compiles with
- Frontend → Source Manager: uses
- Frontend → Type Checker: checks with
- Frontend → Type Context: uses
- Lexer → Source Manager: reads
- Parser → Lexer: uses (evidence: `lib/parse/Parser.cpp`)
- Parser → Syntax AST: builds (evidence: `lib/parse/Parser.cpp`)
- Type Checker → Syntax AST: checks (evidence: `lib/sema/TypeChecker.cpp`)
- Type Checker → Type Context: resolves types
- Frontend → Diagnostics: reports errors
- Macro Expander → Diagnostics: reports errors (evidence: `lib/macro/Expander.cpp`)
- Frontend → Macro Expander: expands macros
- Compiler Driver → LLVM IR Generator: generates code
- LLVM IR Generator → Optimization Pipeline: optimizes IR
- Optimization Pipeline → Sere LLVM Backend: lowers LLVM
- Sere LLVM Backend → Native Executable: emits native code
- Compiler CLI → Project Manager: manages projects
- Project Manager → Package Manager: uses packages
- Package Manager → Package Registry: queries registry
- Package Manager → Installer: installs dependencies
- Sere Developer → Language Server: requests editor help (evidence: `README.md`)
- Language Server → Frontend: analyzes documents (evidence: `lib/lsp/LanguageServer.cpp`)
- Language Server → AST Queries: queries AST (evidence: `lib/lsp/LanguageServer.cpp`)
- Language Server → Completion: provides completion (evidence: `lib/lsp/LanguageServer.cpp`)
- Language Server → Import Completion: completes imports (evidence: `lib/lsp/LanguageServer.cpp`)
- Language Server → Semantic Tokens: provides tokens (evidence: `lib/lsp/LanguageServer.cpp`)
- VS Code Extension → Language Server: connects to
- Native Executable → Sere Runtime: uses
- Sere Runtime → Standard Library Runtime: provides