# catalalang/catala architecture

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

- Interactive diagram: https://gitdiagram.com/catalalang/catala
- Repository: https://github.com/catalalang/catala

## Overview

##### Project Type and Purpose
- Catala is a domain-specific language (DSL) compiler designed for translating legislatively annotated texts into executable, “faithful‐by‐construction” algorithms. In addition to the core compiler, it includes a build system (“clerk”), testing framework, plugin backends, and runtime components for several target languages.
- The README clearly highlights that Catala’s purpose is to allow legal texts to be directly “compiled” into certified code (producing lawyer‐readable outputs) by following a literate programming approach. The project is research-oriented and involves formal semantics and verification.

##### File Structure
- Top-level folders include:
- build_system: Contains the “Clerk” build tool used for testing and orchestration.
- compiler: The core of the Catala compiler, with several subdirectories (such as dcalc, desugared, lcalc, scalc, scopelang, shared_ast, surface, etc.) each representing different stages or representations in the compilation pipeline.
- runtimes: Contains runtime implementations for various target languages (C, OCaml, Python, JavaScript through jsoo, rescript) that the compiler can produce.
- tests: A comprehensive test suite organized by language constructs – helpful for understanding both unit and regression testing.
- syntax_highlighting and doc: Provide auxiliary tools and developer documentation.
- There are also configuration files (e.g., Dockerfile, Makefile, opam files) and build scripts that point to a development-oriented, multi-target, modular design.

A. Compiler Subsystem:
- Frontend:
- The Surface layer (compiler/surface) where the source “legislative text” (annotated with code intentions) is read.
- Lexers, parsers, and token processing (files such as lexer.cppo.ml, parser.mly).
- Transformation Pipeline:
- Desugaring (compiler/desugared): Converting surface code to an intermediate “desugared” form.
- Intermediate representations (modules like dcalc, lcalc, scalc, scopelang) which represent the evolving internal state of the program.
- Shared AST and utility modules (compiler/shared_ast, catala_utils): Common functionality across phases.
- Backend & Plugin Architecture:
- Code generation to target languages (see files in “to_ocaml.ml,” “to_c.ml,” “to_python.ml” in corresponding directories).
- Plugin support (compiler/plugins): Enables dynamic linking and extension of available backends without modifying the core.
- Driver and Orchestration:
- The main compiler driver (compiler/driver.ml) which coordinates these stages.

B. Build System (Clerk Subsystem):
- The build_system directory contains components (clerk.ml, clerk_report.ml, clerk_config) to validate the code, run tests, and generate reports.
- Its design supports executing a series of tasks such as scanning, testing, and running rules to ensure compiler correctness.

C. Runtimes and Integration Points:
- Runtimes provide the execution environments for compiled outputs targeted at languages such as C, OCaml, Python, Rescript, and JavaScript. These are separate modules that plug into the overall system.
- They integrate with the generated code coming out of the compiler (transformation outputs from the backend modules).

D. Testing and Documentation:
- Extensive tests (organized under tests) cover various language features (arithmetic, arrays, exceptions, modules, etc.).
- Documentation and formal proofs (doc/) outline the formal semantics and expected behaviors.
- Auxiliary directories like syntax_highlighting support tooling for editors and developer experience.

## Diagram (Mermaid)

```mermaid
flowchart TD
    X["Annotated Legal Text"]:::compiler
    A["Compiler Driver"]:::compiler
    B["Compiler Frontend (Surface)"]:::compiler
    C["Desugaring"]:::compiler
    D["Dcalc"]:::compiler
    E["Lcalc"]:::compiler
    F["Scalc"]:::compiler
    G["Scopelang"]:::compiler
    H["Shared AST"]:::compiler
    I["Compiler Plugins"]:::compiler
    J["OCaml Code Generator"]:::compiler
    K["C/Python Code Generator"]:::compiler
    L["Generated Code"]:::compiler

    M["C Runtime"]:::runtime
    N["OCaml Runtime"]:::runtime
    O["Python Runtime"]:::runtime
    P["Rescript Runtime"]:::runtime
    Q["JavaScript Runtime (jsoo)"]:::runtime

    R["Build System (Clerk)"]:::build
    S["Testing Framework"]:::test
    T["Documentation & Semantics"]:::doc
    U["Syntax Highlighting"]:::aux

    %% Compiler Pipeline Flow
    X --> B
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> I
    I --> J
    I --> K
    J --> L
    K --> L
    L --> M
    L --> N
    L --> O
    L --> P
    L --> Q

    %% Build System and Auxiliary Tools
    R --> A
    R --> S
    R --> T
    R --> U

    %% Styles
    classDef compiler fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef build fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef runtime fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef test fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef doc fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef aux fill:#CCCCFF,stroke:#333,stroke-width:2px;

    %% Click Events
    click B "https://github.com/catalalang/catala/tree/master/compiler/surface"
    click C "https://github.com/catalalang/catala/tree/master/compiler/desugared"
    click D "https://github.com/catalalang/catala/tree/master/compiler/dcalc"
    click E "https://github.com/catalalang/catala/tree/master/compiler/lcalc"
    click F "https://github.com/catalalang/catala/tree/master/compiler/scalc"
    click G "https://github.com/catalalang/catala/tree/master/compiler/scopelang"
    click H "https://github.com/catalalang/catala/tree/master/compiler/shared_ast"
    click I "https://github.com/catalalang/catala/tree/master/compiler/plugins"
    click J "https://github.com/catalalang/catala/tree/master/compiler/lcalc"
    click K "https://github.com/catalalang/catala/tree/master/compiler/scalc"
    click A "https://github.com/catalalang/catala/blob/master/compiler/driver.ml"
    click R "https://github.com/catalalang/catala/tree/master/build_system"
    click M "https://github.com/catalalang/catala/tree/master/runtimes/c"
    click N "https://github.com/catalalang/catala/tree/master/runtimes/ocaml"
    click O "https://github.com/catalalang/catala/tree/master/runtimes/python"
    click P "https://github.com/catalalang/catala/tree/master/runtimes/rescript"
    click Q "https://github.com/catalalang/catala/tree/master/runtimes/jsoo"
    click S "https://github.com/catalalang/catala/tree/master/tests"
    click T "https://github.com/catalalang/catala/tree/master/doc"
    click U "https://github.com/catalalang/catala/tree/master/syntax_highlighting"
```
