# scrossuk/locic architecture

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

- Interactive diagram: https://gitdiagram.com/scrossuk/locic
- Repository: https://github.com/scrossuk/locic

## Overview

##### Project Type and Purpose
- This is a language compiler toolchain (“Loci Compiler Tools”). It’s a multi-stage compiler for the Loci programming language, built in C++ and relying on LLVM as a backend. Additionally it bundles:
- A standard library (stdlib/) and runtime support (runtime/) in Loci itself.
- Example programs (examples/) to illustrate language features.
- Documentation (docs/) describing language design and user guides.
- Tests (test/, unittests/) and utilities (utils/) to verify correctness of the compiler.

##### Top-Level Architecture
- Build system (CMake + submodules)
- Compiler driver (tools/locic.cpp, tools/loci-vtable.cpp)
- Compiler core subdivided into phases:
1. Lexical Analysis (locic/Lex)
2. Parsing (locic/Parser) → AST (locic/AST)
3. Semantic Analysis (locic/SemanticAnalysis)
4. Code Generation (locic/CodeGen) → LLVM IR + object code
- Linking with:
- Loci runtime library (runtime/)
- Loci standard library (stdlib/)
- 3rd-party API stubs (3rdparty/Qt, 3rdparty/SFML) for binding example GUIs.
- Tools & Tests:
- FileCheck utility (utils/FileCheck)
- Googletest harness (utils/googletest)
- Unit tests and integration tests (unittests/, test/)

##### Build & Deployment
- CMakeLists.txt and cmake/** configure build targets: compiler executable(s), runtime library, stdlib modules, tools, tests.
- External submodules (Qt, SFML) are integrated via CMake modules under 3rdparty/.
- Continuous integration configured in .travis.yml.

##### Diagramming Conventions
- Blue for compiler phases (frontend, semantic, codegen)
- Green for libraries (runtime, stdlib, 3rd-party)
- Orange for tools & tests
- Gray for build system
- Rectangles for modules/projects
- Parallelograms for data artifacts (source files, IR, binaries)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Artifacts
    SourceFiles[/"Source Files (.loci)"/]:::data

    %% Build System
    subgraph "Build System"
        B1["CMakeLists.txt"]:::buildSystem
        B2["cmake/"]:::buildSystem
        B3["3rdparty/CMakeLists.txt"]:::buildSystem
    end

    %% Compiler Driver
    C1["Compiler Driver"]:::driver

    %% Frontend
    subgraph "Frontend"
        F1["Lexer"]:::frontend
        F2["Parser"]:::frontend
        F3["AST"]:::frontend
    end

    %% Semantic and CodeGen
    D1["Semantic Analyzer"]:::semantic
    D2["Code Generator"]:::codegen
    IR[/"LLVM IR"/]:::data
    LLVM["LLVM Toolchain"]:::libs

    %% Linker & Runtime
    subgraph "Linker & Runtime"
        L1["Linker"]:::codegen
        L2["Loci Runtime"]:::libs
        L3["Loci Stdlib"]:::libs
        L4["3rd-party Stubs"]:::libs
    end

    Executable[/"Executable"/]:::data

    %% Verification
    subgraph "Verification"
        T1["FileCheck"]:::tools
        T2["GoogleTest"]:::tools
        T3["Unit & Integration Tests"]:::tools
    end

    %% Documentation
    subgraph "Documentation"
        DOCsrc[/"docs/"/]:::data
        DOC["Sphinx Docs"]:::tools
    end

    %% Connections
    SourceFiles --> B1
    B1 --> C1
    B2 --> C1
    B3 --> C1

    C1 --> F1
    F1 --> F2
    F2 --> F3
    F3 --> D1
    D1 --> D2
    D2 --> IR
    IR --> LLVM
    LLVM --> L1
    L1 --> L2
    L1 --> L3
    L1 --> L4
    L2 --> Executable
    L3 --> Executable
    L4 --> Executable

    C1 --> T1
    C1 --> T3

    DOCsrc --> DOC

    %% Click Events
    click B1 "https://github.com/scrossuk/locic/blob/master/CMakeLists.txt"
    click B2 "https://github.com/scrossuk/locic/tree/master/cmake/"
    click B3 "https://github.com/scrossuk/locic/blob/master/3rdparty/CMakeLists.txt"
    click C1 "https://github.com/scrossuk/locic/blob/master/tools/locic.cpp"
    click C1 "https://github.com/scrossuk/locic/blob/master/tools/loci-vtable.cpp"
    click F1 "https://github.com/scrossuk/locic/tree/master/include/locic/Lex/"
    click F1 "https://github.com/scrossuk/locic/tree/master/lib/Lex/"
    click F2 "https://github.com/scrossuk/locic/tree/master/include/locic/Parser/"
    click F2 "https://github.com/scrossuk/locic/tree/master/lib/Parser/"
    click F3 "https://github.com/scrossuk/locic/tree/master/include/locic/AST/"
    click F3 "https://github.com/scrossuk/locic/tree/master/lib/AST/"
    click D1 "https://github.com/scrossuk/locic/tree/master/include/locic/SemanticAnalysis/"
    click D1 "https://github.com/scrossuk/locic/tree/master/lib/SemanticAnalysis/"
    click D2 "https://github.com/scrossuk/locic/tree/master/include/locic/CodeGen/"
    click D2 "https://github.com/scrossuk/locic/tree/master/lib/CodeGen/"
    click L1 "https://github.com/scrossuk/locic/blob/master/include/locic/CodeGen/Linker.hpp"
    click L2 "https://github.com/scrossuk/locic/tree/master/runtime/"
    click L3 "https://github.com/scrossuk/locic/tree/master/stdlib/"
    click L4 "https://github.com/scrossuk/locic/tree/master/3rdparty/Qt/"
    click L4 "https://github.com/scrossuk/locic/tree/master/3rdparty/SFML/"
    click T1 "https://github.com/scrossuk/locic/tree/master/utils/FileCheck/"
    click T2 "https://github.com/scrossuk/locic/tree/master/utils/googletest/"
    click T3 "https://github.com/scrossuk/locic/tree/master/unittests/"
    click T3 "https://github.com/scrossuk/locic/tree/master/test/"
    click DOCsrc "https://github.com/scrossuk/locic/tree/master/docs/"

    %% Styles
    classDef buildSystem fill:#ddd,stroke:#333,stroke-width:1px
    classDef driver fill:#ccc,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef semantic fill:#bbf,stroke:#333,stroke-width:1px
    classDef codegen fill:#bbf,stroke:#333,stroke-width:1px
    classDef libs fill:#bfb,stroke:#333,stroke-width:1px
    classDef tools fill:#fb8,stroke:#333,stroke-width:1px
    classDef data fill:#eee,stroke:#333,stroke-width:1px
```
