# ella-to/ella architecture

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

- Interactive diagram: https://gitdiagram.com/ella-to/ella
- Repository: https://github.com/ella-to/ella

## Overview

##### Project Type and Purpose
- Ella is a standalone compiler CLI tool (written in Go) that reads `.ella` schema files and emits Go and TypeScript code.
- Its core responsibility is to parse a simple IDL, build an AST, validate it, and run code generators (Go & TS).

##### File Structure
- Top‐level files:
- `main.go` – CLI entry point.
- `go.mod`, `go.sum` – module configuration.
- `Makefile` – build/test scripts.
- `README.md`, `LICENSE`, `.gitignore`.
- Directories:
- `internal/compiler` – core compiler pipeline:
– `scanner/` – lexical analysis (lexer & token definitions).
– `parser/` – syntactic analysis + validation.
– `ast/` – in‐memory schema representation.
– `gen/` – code generators (Go & TS templates).
- `internal/strcase` – utility for converting identifier case styles.
- `e2e` – end‐to‐end schema examples & tests (download, HTTP, RPC, stream, upload).

##### Key Insights from README
- CLI commands (`gen`, `fmt`, `ver`) orchestrate the pipeline.
- Designed for easy extension: to add another target language, implement a new generator in `internal/compiler/gen`.
- E2E folder demonstrates supported service patterns (JSON/JSON, Streams, RPC).

##### Main Components & Their Interactions
a. CLI Layer
– Parses arguments (`gen`, `fmt`).
– Invokes the compiler pipeline.
b. Pipeline Stages
1. Scanner: Reads `.ella` files → produces Token stream.
2. Parser: Consumes tokens → builds AST + performs semantic validations.
3. AST: Shared in‐memory model of schemas (constants, enums, models, services, errors).
4. Generator Factory:
- Chooses Go or TS generator based on output extension.
- Feeds AST into templating engine (`text/template` or similar).
5. Output Writer:
- Emits `.gen.go` or `.gen.ts` files.
c. Utilities
– `strcase` for consistent identifier casing in generated code.
– E2E tests for validating end‐to‐end generation scenarios.

##### Architectural Patterns & Principles
- Compiler Pipeline (Lex → Parse → AST → Generate)
- Template‐based Code Generation (separate templates for Go & TS)
- Single‐binary CLI with pluggable generators
- Clear separation: core compiler vs. language‐specific generators vs. utilities vs. tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% File Input
    EllaFiles(("*.ella")):::files

    %% CLI Layer
    CLI["CLI (main.go)"]:::cli

    %% Pipeline Stages
    Scanner["Scanner"]:::pipeline
    ParserValidator["Parser/Validator"]:::pipeline
    AST["AST Model"]:::pipeline
    GenFactory["Generator Factory"]:::pipeline

    %% Code Generators
    GoGen["Go Generator"]:::generator
    TSGen["TS Generator"]:::generator
    NewGen["Add New Generator"]:::extension

    %% Outputs
    GoOutput(("*.gen.go")):::files
    TSOutput(("*.gen.ts")):::files

    %% Utility
    Strcase["strcase Utility"]:::util

    %% External Tests
    E2ETests(("E2E Tests")):::external

    %% Flow
    EllaFiles --> CLI
    CLI --> Scanner
    Scanner --> ParserValidator
    ParserValidator --> AST
    AST --> GenFactory
    GenFactory --> GoGen
    GenFactory --> TSGen
    GenFactory --> NewGen

    GoGen --> GoOutput
    TSGen --> TSOutput

    E2ETests --> CLI

    %% Utility Usage
    Strcase -.-> ParserValidator
    Strcase -.-> GoGen
    Strcase -.-> TSGen

    %% Click Events
    click CLI "https://github.com/ella-to/ella/blob/main/main.go"
    click Scanner "https://github.com/ella-to/ella/tree/main/internal/compiler/scanner"
    click ParserValidator "https://github.com/ella-to/ella/tree/main/internal/compiler/parser"
    click AST "https://github.com/ella-to/ella/tree/main/internal/compiler/ast"
    click GenFactory "https://github.com/ella-to/ella/blob/main/internal/compiler/gen/gen.go"
    click GoGen "https://github.com/ella-to/ella/blob/main/internal/compiler/gen/golang.go"
    click TSGen "https://github.com/ella-to/ella/blob/main/internal/compiler/gen/typescript.go"
    click Strcase "https://github.com/ella-to/ella/tree/main/internal/strcase"
    click E2ETests "https://github.com/ella-to/ella/tree/main/e2e"
    
    %% Styles
    classDef pipeline fill:#D6EFFF,stroke:#0366d6,stroke-width:2px;
    classDef generator fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef util fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef extension fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px,stroke-dasharray: 5 5;
    classDef files fill:#FFE0B2,stroke:#BF360C,stroke-width:2px,shape:cylinder;
    classDef cli fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,stroke-dasharray: 3 3;
    classDef external fill:#E0E0E0,stroke:#424242,stroke-width:2px,shape:cloud;
```
