# arnavsurve/grace architecture

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

- Interactive diagram: https://gitdiagram.com/arnavsurve/grace
- Repository: https://github.com/arnavsurve/grace

## Overview

##### Project type and purpose
- Grace is a compiler + runtime / systems programming language toolchain implemented in Go.
- Purpose: parse “Grace” source (.grc), perform lexical analysis, parsing, semantic analysis, and emit modern COBOL code. It also provides a CLI for init, build, run, and log inspection.

##### File structure
- Top‐level Go modules:
- cmd/ – CLI entry points (built with Cobra: root, build, run, logs, init)
- internal/compiler/ – the compiler implementation, subdivided into:
· lexer
· parser
· ast
· symbols + scope
· emitter
· lib (runtime constants & utilities)
- main.go – glue to invoke cmd/root
- docs/ – grammar spec & demo parser
- tests/ + examples/ – regression suites of .grc inputs and expected .cbl outputs
- Build: Makefile, go.mod, go.sum
- No microservices—single monolithic CLI + compiler library.

##### README for additional insights
- Emphasis on language spec, EBNF grammar (docs/grammar.lark), Python demo (docs/parse_grammar.py).
- Features: fixed‐width files, VSAM, CSV, JSON, SQL, cloud services (these are runtime targets but not source‐controlled connectors).

a. Main components
1) CLI Layer (cmd/)
- Commands: init, build, run, logs
- Uses Cobra for parsing flags & subcommands
2) Compiler Pipeline (internal/compiler/)
- Lexer: reads source chars → tokens
- Parser: tokens → parse tree / AST
- Semantic Analyzer: symbol table, scope resolution, type checking
- Emitter/Codegen: AST → COBOL code
- Runtime Lib: constants & helper routines embedded in output
3) I/O / File System
- Reads .grc, writes .cbl, manages templates (cmd/templates/*.tpl)
4) Tests & Examples
- tests/good & tests/bad drive regression based on expected outputs
5) Docs / Grammar Specification (external reference)
b. Relationships & data flow
- CLI “build” invokes Driver → Source File
→ Lexer → Parser → AST → Semantic → Emitter → write COBOL file
- “run” may compile + invoke runtime (Go exec child process or embed the generated code in target environment)
- “init” scaffolds a new project directory using templates
- Tests harness (test/run.go) exercises CLI commands and verifies outputs
c. Architectural patterns & design principles
- Pipeline pattern in compiler front‐end
- Single responsibility per package (lexer, parser, ast, emitter, scope, symbols)
- Library vs. application separation: internal compiler API vs. CLI wrappers
d. Key technologies
- Go + Cobra CLI framework
- LALR(1) or recursive‐descent parser (in parser/parser.go)
- Templates for code scaffolding
- Python demo harness (docs/parse_grammar.py) — ancillary

##### Final advice
- Be very detailed: split the pipeline into its subcomponents.
- CLI layer, compiler core, I/O, and tests as separate zones.
- Use consistent visual notation so a reader immediately sees the data flow and module boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef cli fill:#a2d5a2,stroke:#333,stroke-width:1px
    classDef frontend fill:#a2c7e5,stroke:#333,stroke-width:1px
    classDef backend fill:#f5b888,stroke:#333,stroke-width:1px
    classDef io fill:#d3d3d3,stroke:#333,stroke-width:1px

    subgraph "CLI Layer" 
        direction TB
        Main["main.go"]:::cli
        Root["cmd/root.go"]:::cli
        Build["cmd/build.go"]:::cli
        RunCmd["cmd/run.go"]:::cli
        Init["cmd/init.go"]:::cli
        Logs["cmd/logs.go"]:::cli
    end

    subgraph "Templates" 
        direction TB
        Gitignore["gitignore.tpl"]:::io
        GraceYml["grace.yml.tpl"]:::io
        HelloTpl["hello.grc.tpl"]:::io
    end

    subgraph "Compiler Pipeline"
        direction TB
        Driver["Compiler Driver"]:::frontend
        TokenDefs["Token Definitions"]:::frontend
        Lexer["Lexer (lexer.go)"]:::frontend
        Parser["Parser (parser.go)"]:::frontend
        AST["AST (ast.go)"]:::frontend
        subgraph "Semantic Analysis"
            direction TB
            Symbols["Symbols (symbols.go)"]:::frontend
            Scope["Scope (scope.go)"]:::frontend
        end
        Emitter["Emitter (emitter.go)"]:::backend
        subgraph "Runtime Library"
            direction TB
            Constants["Constants (constants.go)"]:::backend
            Utils["Utilities (utils.go)"]:::backend
        end
    end

    subgraph "I/O / Files"
        direction TB
        SourceFile[".grc Source File"]:::io
        COBOLFile[".cbl Output File"]:::io
    end

    subgraph "Tests & Examples"
        direction TB
        TestHarness["test/run.go"]:::io
        Positive["tests/good/*.grc & expected"]:::io
        Negative["tests/bad/*.grc"]:::io
        ExampleSrc["examples/hello.grc"]:::io
    end

    subgraph "Docs / Grammar Spec"
        direction TB
        GrammarSpec["grammar.lark"]:::io
        DemoParser["parse_grammar.py"]:::io
    end

    subgraph "Build & Dependencies"
        direction TB
        Makefile["Makefile"]:::io
        GoMod["go.mod"]:::io
        GoSum["go.sum"]:::io
    end

    Main --> Root
    Root --> Build
    Root --> RunCmd
    Root --> Init
    Root --> Logs

    Build --> Driver
    RunCmd --> Driver
    Init --> Gitignore
    Init --> GraceYml
    Init --> HelloTpl

    Driver --> SourceFile
    SourceFile --> TokenDefs
    TokenDefs --> Lexer
    Lexer --> Parser
    Parser --> AST
    AST --> Symbols
    AST --> Scope
    Symbols --> Emitter
    Scope --> Emitter
    Emitter --> COBOLFile

    Driver --> COBOLFile

    Driver --> TestHarness
    TestHarness --> Positive
    TestHarness --> Negative

    Driver --> ExampleSrc

    Driver --> GrammarSpec
    Driver --> DemoParser

    Driver --> Makefile
    Driver --> GoMod
    Driver --> GoSum

    click Main "https://github.com/arnavsurve/grace/blob/main/main.go"
    click Root "https://github.com/arnavsurve/grace/blob/main/cmd/root.go"
    click Build "https://github.com/arnavsurve/grace/blob/main/cmd/build.go"
    click RunCmd "https://github.com/arnavsurve/grace/blob/main/cmd/run.go"
    click Init "https://github.com/arnavsurve/grace/blob/main/cmd/init.go"
    click Logs "https://github.com/arnavsurve/grace/blob/main/cmd/logs.go"
    click Gitignore "https://github.com/arnavsurve/grace/blob/main/cmd/templates/gitignore.tpl"
    click GraceYml "https://github.com/arnavsurve/grace/blob/main/cmd/templates/grace.yml.tpl"
    click HelloTpl "https://github.com/arnavsurve/grace/blob/main/cmd/templates/hello.grc.tpl"
    click Driver "https://github.com/arnavsurve/grace/blob/main/internal/compiler/driver.go"
    click Lexer "https://github.com/arnavsurve/grace/blob/main/internal/compiler/lexer/lexer.go"
    click Parser "https://github.com/arnavsurve/grace/blob/main/internal/compiler/parser/parser.go"
    click TokenDefs "https://github.com/arnavsurve/grace/blob/main/internal/compiler/token/token.go"
    click AST "https://github.com/arnavsurve/grace/blob/main/internal/compiler/ast/ast.go"
    click Symbols "https://github.com/arnavsurve/grace/blob/main/internal/compiler/symbols/symbols.go"
    click Scope "https://github.com/arnavsurve/grace/blob/main/internal/compiler/scope/scope.go"
    click Emitter "https://github.com/arnavsurve/grace/blob/main/internal/compiler/emitter/emitter.go"
    click Constants "https://github.com/arnavsurve/grace/blob/main/internal/compiler/lib/constants.go"
    click Utils "https://github.com/arnavsurve/grace/blob/main/internal/compiler/lib/utils.go"
    click GrammarSpec "https://github.com/arnavsurve/grace/blob/main/docs/grammar.lark"
    click DemoParser "https://github.com/arnavsurve/grace/blob/main/docs/parse_grammar.py"
    click TestHarness "https://github.com/arnavsurve/grace/blob/main/test/run.go"
    click ExampleSrc "https://github.com/arnavsurve/grace/blob/main/examples/hello.grc"
```
