# michniks2001/s-lang architecture

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

- Interactive diagram: https://gitdiagram.com/michniks2001/s-lang
- Repository: https://github.com/michniks2001/s-lang

## Overview

1. **What this repository is**
   - This is a Python-based compiler/toolchain for the S-Lang language.
   - The codebase is centered on a classic front-end/back-end pipeline, with the language spec and user-facing examples kept alongside the implementation.

2. **Top-level source boundaries**
   - `src/` contains the compiler implementation: `lexer.py`, `parser.py`, `compiler.py`, `generator.py`, and `errors.py`.
   - `stdlib/` contains built-in S-Lang modules shipped with the language runtime surface.
   - `examples/` holds sample `.sl` programs used to exercise syntax, modules, I/O, structs, and algorithms.
   - `docs/` is extensive reference material for features, errors, runtime checks, project structure, and implementation status.

3. **Compilation pipeline**
   - The main data flow is: S-Lang source text → lexical tokens → parsed structure/AST → semantic validation/type checks → generated output.
   - `lexer.py` is responsible for turning raw `.sl` text into tokens.
   - `parser.py` builds the language structure consumed by later stages.
   - `compiler.py` appears to orchestrate the compilation process, while `generator.py` handles backend emission.

4. **Language semantics live in the compiler, not the examples**
   - The README shows S-Lang is statically typed, with explicit declarations, structs, functions, arrays, maps, sets, modules, and control flow.
   - Those rules imply the compiler carries substantial semantic logic: type matching, const correctness, function signature checking, struct field validation, indexing checks, and operator compatibility.

5. **Error handling is a first-class subsystem**
   - `errors.py` centralizes structured error types and messages.
   - The docs split errors into lexer, parser, semantic, and runtime categories, which suggests each pipeline stage reports failures at its own boundary.
   - This is important for architecture diagrams: errors are not an afterthought; they are part of the compiler contract.

6. **Module system and code organization**
   - S-Lang supports `include`-based module loading and module-qualified names.
   - The README defines a search order for module resolution: source directory first, then current working directory, then `stdlib/`.
   - That makes file-system lookup a key boundary in the compiler, especially for local modules under `examples/local_modules_test/` and built-in modules in `stdlib/`.

7. **Standard library is source-level, not hidden runtime code**
   - `stdlib/io.sl`, `stdlib/math.sl`, and `stdlib/system.sl` are authored in S-Lang and treated as standard modules.
   - This means the language’s core functionality is exposed through normal module imports rather than a separate host-language API surface.
   - The compiler therefore needs to treat stdlib modules as part of the language ecosystem and module resolution path.

8. **Runtime safety is part of the generated program**
   - The README documents runtime checks such as divide-by-zero and array bounds errors, with a flag to disable them for performance.
   - That implies the generator likely emits checks into the compiled output, not just compile-time validation.
   - In the architecture, runtime safety sits at the boundary between semantic analysis and generated executable behavior.

9. **Examples are part of the validation loop**
   - `examples/` provides a progression from basics to a comprehensive showcase, which suggests the repo is used as both a compiler implementation and a language conformance suite.
   - `test_output.txt` likely captures expected output from one of these runs.
   - For a diagram, examples should be shown as external inputs into the compiler pipeline, not as internal runtime components.

10. **Build and developer tooling**
   - `Makefile` is the primary entry point for compiling/running examples, listing examples, and cleaning artifacts.
   - `pyproject.toml` and `.python-version` indicate the implementation is managed as a Python project.
   - This means the repo’s operational boundary is a Python host tool that processes S-Lang source files into executable results.

11. **Documentation maps directly to subsystem boundaries**
   - The docs are organized around language features, implementation status, project structure, error system, and runtime errors.
   - That documentation layout mirrors the compiler’s own architectural layers: syntax, semantics, runtime behavior, and packaging/module layout.
   - In other words, the repo is not just source code; it includes a specification layer tightly coupled to the implementation.

Main entry points: [`src/compiler.py`](https://github.com/michniks2001/s-lang/blob/main/src/compiler.py) (Module loader), [`src/errors.py`](https://github.com/michniks2001/s-lang/blob/main/src/errors.py) (Errors), [`src/lexer.py`](https://github.com/michniks2001/s-lang/blob/main/src/lexer.py) (Lexer), [`src/parser.py`](https://github.com/michniks2001/s-lang/blob/main/src/parser.py) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo surface"]
  node_readme["README<br/>spec guide<br/>[README.md]"]
  node_makefile["Makefile<br/>dev entrypoint"]
  node_pyproject["Py project<br/>python config<br/>[pyproject.toml]"]
end

subgraph group_src["Compiler"]
  node_lexer["Lexer<br/>frontend<br/>[lexer.py]"]
  node_parser["Parser<br/>syntax tree<br/>[parser.py]"]
  node_compiler["Compiler<br/>orchestrator<br/>[compiler.py]"]
  node_semantics{{"Semantics<br/>analysis<br/>[compiler.py]"}}
  node_modules{{"Module loader<br/>resolution<br/>[compiler.py]"}}
  node_generator["Generator<br/>backend<br/>[generator.py]"]
  node_errors["Errors<br/>diagnostics<br/>[errors.py]"]
end

subgraph group_stdlib["Stdlib"]
  node_io_stdlib["IO module<br/>stdlib module<br/>[io.sl]"]
  node_math_stdlib["Math module<br/>stdlib module<br/>[math.sl]"]
  node_system_stdlib["System module<br/>stdlib module<br/>[system.sl]"]
end

subgraph group_examples["Examples"]
  node_examples_showcase["Showcase<br/>example suite"]
  node_local_modules["Local modules<br/>example modules<br/>[db.sl]"]
end

subgraph group_docs["Docs"]
  node_docs_errors["Error docs<br/>reference<br/>[ERROR_SYSTEM.md]"]
end

node_readme -->|"defines"| node_compiler
node_readme -->|"describes"| node_modules
node_makefile -->|"runs"| node_examples_showcase
node_pyproject -->|"hosts"| node_compiler
node_examples_showcase -->|"input"| node_lexer
node_local_modules -->|"imports"| node_modules
node_lexer -->|"tokens"| node_parser
node_parser -->|"ast"| node_compiler
node_compiler -->|"checks"| node_semantics
node_semantics -->|"reports"| node_errors
node_parser -->|"reports"| node_errors
node_lexer -->|"reports"| node_errors
node_compiler -->|"resolves"| node_modules
node_modules -->|"loads"| node_io_stdlib
node_modules -->|"loads"| node_math_stdlib
node_modules -->|"loads"| node_system_stdlib
node_semantics -->|"approved"| node_generator
node_generator -->|"checks"| node_errors
node_generator -.->|"mirrors"| node_docs_errors
node_docs_errors -.->|"specifies"| node_compiler

click node_readme "https://github.com/michniks2001/s-lang/blob/main/README.md"
click node_makefile "https://github.com/michniks2001/s-lang/tree/main/Makefile"
click node_pyproject "https://github.com/michniks2001/s-lang/blob/main/pyproject.toml"
click node_lexer "https://github.com/michniks2001/s-lang/blob/main/src/lexer.py"
click node_parser "https://github.com/michniks2001/s-lang/blob/main/src/parser.py"
click node_compiler "https://github.com/michniks2001/s-lang/blob/main/src/compiler.py"
click node_semantics "https://github.com/michniks2001/s-lang/blob/main/src/compiler.py"
click node_modules "https://github.com/michniks2001/s-lang/blob/main/src/compiler.py"
click node_generator "https://github.com/michniks2001/s-lang/blob/main/src/generator.py"
click node_errors "https://github.com/michniks2001/s-lang/blob/main/src/errors.py"
click node_io_stdlib "https://github.com/michniks2001/s-lang/blob/main/stdlib/io.sl"
click node_math_stdlib "https://github.com/michniks2001/s-lang/blob/main/stdlib/math.sl"
click node_system_stdlib "https://github.com/michniks2001/s-lang/blob/main/stdlib/system.sl"
click node_examples_showcase "https://github.com/michniks2001/s-lang/blob/main/examples/10_comprehensive_showcase.sl"
click node_local_modules "https://github.com/michniks2001/s-lang/blob/main/examples/local_modules_test/db.sl"
click node_docs_errors "https://github.com/michniks2001/s-lang/blob/main/docs/ERROR_SYSTEM.md"

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_readme,node_makefile,node_pyproject toneBlue
class node_lexer,node_parser,node_compiler,node_semantics,node_modules,node_generator,node_errors toneAmber
class node_io_stdlib,node_math_stdlib,node_system_stdlib toneMint
class node_examples_showcase,node_local_modules toneRose
class node_docs_errors toneIndigo
```

## Components

### Repo surface

Project metadata, build entrypoints, and shared references.

- [README](https://github.com/michniks2001/s-lang/blob/main/README.md): spec guide · Top-level language and project overview. · `README.md`
- [Makefile](https://github.com/michniks2001/s-lang/tree/main/Makefile): dev entrypoint · Primary task runner for building, running, and cleaning. · `Makefile`
- [Py project](https://github.com/michniks2001/s-lang/blob/main/pyproject.toml): python config · Python packaging and toolchain metadata. · `pyproject.toml`

### Compiler

Python implementation of the S-Lang toolchain.

- [Lexer](https://github.com/michniks2001/s-lang/blob/main/src/lexer.py): frontend · Converts S-Lang source text into tokens. · `src/lexer.py`
- [Parser](https://github.com/michniks2001/s-lang/blob/main/src/parser.py): syntax tree · Builds the language structure consumed by later stages. · `src/parser.py`
- [Compiler](https://github.com/michniks2001/s-lang/blob/main/src/compiler.py): orchestrator · Coordinates compilation, semantic validation, and module handling. · `src/compiler.py`
- [Semantics](https://github.com/michniks2001/s-lang/blob/main/src/compiler.py): analysis · Performs type checks, signature checks, indexing rules, and other validation. · `src/compiler.py`
- [Module loader](https://github.com/michniks2001/s-lang/blob/main/src/compiler.py): resolution · Resolves includes and module-qualified names across source and stdlib paths. · `src/compiler.py`
- [Generator](https://github.com/michniks2001/s-lang/blob/main/src/generator.py): backend · Emits compiled output and runtime safety checks. · `src/generator.py`
- [Errors](https://github.com/michniks2001/s-lang/blob/main/src/errors.py): diagnostics · Structured lexer, parser, semantic, and runtime error types. · `src/errors.py`

### Stdlib

Built-in S-Lang modules shipped with the language.

- [IO module](https://github.com/michniks2001/s-lang/blob/main/stdlib/io.sl): stdlib module · Built-in source-level I/O support. · `stdlib/io.sl`
- [Math module](https://github.com/michniks2001/s-lang/blob/main/stdlib/math.sl): stdlib module · Built-in source-level math support. · `stdlib/math.sl`
- [System module](https://github.com/michniks2001/s-lang/blob/main/stdlib/system.sl): stdlib module · Built-in source-level system support. · `stdlib/system.sl`

### Examples

Sample S-Lang programs used to exercise the compiler and modules.

- [Showcase](https://github.com/michniks2001/s-lang/blob/main/examples/10_comprehensive_showcase.sl): example suite · Representative sample programs covering core language features. · `examples/10_comprehensive_showcase.sl`
- [Local modules](https://github.com/michniks2001/s-lang/blob/main/examples/local_modules_test/db.sl): example modules · Example of repository-local module resolution. · `examples/local_modules_test/db.sl`

### Docs

Reference material for features, errors, structure, and status.

- [Error docs](https://github.com/michniks2001/s-lang/blob/main/docs/ERROR_SYSTEM.md): reference · Documentation for compiler and runtime error categories. · `docs/ERROR_SYSTEM.md`

## Connections

- README → Compiler: defines · Language rules and architecture constrain the compiler.
- README → Module loader: describes · Documents module search order and include behavior.
- Makefile → Showcase: runs · Build and run tasks execute example programs.
- Py project → Compiler: hosts · Project metadata for the Python implementation.
- Showcase → Lexer: input · Example source is fed into the compilation pipeline.
- Local modules → Module loader: imports · Exercises repository-local module lookup.
- Lexer → Parser: tokens · Token stream flows into parsing.
- Parser → Compiler: ast · Parsed structure is handed to orchestration and analysis.
- Compiler → Semantics: checks · Compiler coordinates semantic validation.
- Semantics → Errors: reports · Validation failures become structured diagnostics.
- Parser → Errors: reports · Syntax failures are emitted as structured diagnostics.
- Lexer → Errors: reports · Lexical failures are emitted as structured diagnostics.
- Compiler → Module loader: resolves · Compiler locates included and qualified modules.
- Module loader → IO module: loads · Search path reaches built-in source modules.
- Module loader → Math module: loads · Search path reaches built-in source modules.
- Module loader → System module: loads · Search path reaches built-in source modules.
- Semantics → Generator: approved · Validated programs advance to code generation.
- Generator → Errors: checks · Runtime safety and emission failures are surfaced.
- Generator → Error docs: mirrors · Implementation corresponds to documented error categories.
- Error docs → Compiler: specifies · Documentation mirrors compiler boundaries and behavior.
