# cbourgois/simonsays architecture

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

- Interactive diagram: https://gitdiagram.com/cbourgois/simonsays
- Repository: https://github.com/cbourgois/simonsays

## Overview

##### Project type and purpose
- This is an open-source CLI utility (an npm package) named “SimonSays.”
- Its purpose is to analyze JavaScript and HTML source code—in particular AngularJS code using angular-translate—to extract translation keys, verify their presence in translation files, search for them across projects, and rewrite translation files.

##### File structure
Top-level:
- bin/
– simonsays.js → the CLI entry point, runs commands (check, search, rewrite)
- src/
– angularjs/ → embedded AngularJS’s `$interpolate` and `$parse` implementations
– compiler/ → modules that generate or rewrite translation resource files
– finder/ → modules that scan ASTs for translation key usages
– parser/ → modules that parse JS (via @babel/parser) and HTML into AST, plus translation file parsers
– simonsays.js → orchestrates the high-level logic; ties CLI flags to core modules
- tests alongside source modules for validation
- configuration files: package.json, ava.config.js, ESLint, GitHub CI templates, etc.

##### README for additional insights
- The README describes three CLI commands (check, search, rewrite), the supported options (locale, module, output, merge, prefix), and the underlying approach (parsing JS/HTML ASTs, embedded AngularJS parsing code).

a. Main components
- CLI Layer (bin/simonsays.js)
- Core Orchestrator (src/simonsays.js)
- Parser Subsystem (src/parser/*)
- Finder Subsystem (src/finder/*)
- Compiler Subsystem (src/compiler/*)
- AngularJS Runtime Helpers (src/angularjs/*)
- File System (source code files, translation files: JSON/XML)
- External Dependency: @babel/parser
b. Relationships & data flow
1. User invokes CLI → CLI Layer
2. CLI Layer parses command + flags → invokes Core Orchestrator
3. Core reads input file paths from File System
4. Core calls Parser Subsystem → produces ASTs of .js/.html
5. Finder Subsystem scans ASTs → extracts translation key usages
6. Core optionally loads existing translation files from File System
7. Compiler Subsystem merges/checks/re-writes translation files
8. Core emits output (console report or rewritten files)
c. Architectural patterns & design principles
- Modular layering: CLI → orchestrator → pluggable subsystems
- Single Responsibility: parser only builds AST, finder only extracts keys, compiler only writes files
- Dependency injection of AngularJS helpers into parser/finder to handle AngularJS-specific AST constructs
- Extensibility: new parsers/finders could be added for other frameworks
d. Key technologies & libraries
- Node.js CLI (bin/)
- @babel/parser for JavaScript AST
- Custom HTML AST parser (src/parser/html.js)
- Embedded AngularJS code for `$interpolate` & `$parse` (src/angularjs)
- JSON/XML reading/writing for translation resources

## Diagram (Mermaid)

```mermaid
graph TD
    %% Control Flow Layer
    CLI["CLI Layer<br/>(bin/simonsays.js)"]:::control
    Core["Core Orchestrator<br/>(src/simonsays.js)"]:::control

    %% Subsystems
    subgraph "Parser Subsystem"
        JSParser["JavaScript Parser (AngularJS)"]:::subsystem
        HTMLParser["HTML Parser"]:::subsystem
        TransParser["Translation File Parser"]:::subsystem
    end

    subgraph "Finder Subsystem"
        KeyFinder["AngularJS Key Finder"]:::subsystem
    end

    subgraph "Compiler Subsystem"
        AJResourceComp["AngularJS Resource Compiler"]:::subsystem
        HTMLResourceComp["HTML Resource Compiler"]:::subsystem
    end

    subgraph "AngularJS Runtime Helpers"
        Interpolate["$interpolate Implementation"]:::external
        ParseHelp["$parse Implementation"]:::external
    end

    %% Resources & External Dependencies
    FileSystem["File System<br/>(Source & Translation Files)"]:::resource
    Babel["@babel/parser"]:::external

    %% Tests
    subgraph "Tests (Validation)"
        CoreTest["Core Orchestrator Tests"]:::test
        HTMLParserTest["HTML Parser Tests"]:::test
        TransParserTest["Translation File Parser Tests"]:::test
        FinderTest["Finder Tests"]:::test
    end

    %% Control Flow Connections
    CLI -->|"invokes"| Core
    Core -->|"calls Parser"| JSParser
    Core -->|"calls Parser"| HTMLParser
    Core -->|"calls Parser"| TransParser
    JSParser -->|"ASTs"| KeyFinder
    HTMLParser -->|"ASTs"| KeyFinder
    KeyFinder -->|"keys"| AJResourceComp
    KeyFinder -->|"keys"| HTMLResourceComp
    Core -->|"load existing files"| FileSystem
    AJResourceComp -->|"writes files"| FileSystem
    HTMLResourceComp -->|"writes files"| FileSystem
    Core -->|"output reports"| FileSystem

    %% Dependencies
    Babel -->|used by| JSParser
    Interpolate -->|injected into| JSParser
    ParseHelp -->|injected into| JSParser
    Interpolate -->|injected into| KeyFinder
    ParseHelp -->|injected into| KeyFinder

    %% Tests linkage
    CoreTest -->|validates| Core
    HTMLParserTest -->|validates| HTMLParser
    TransParserTest -->|validates| TransParser
    FinderTest -->|validates| KeyFinder

    %% Click Events for Source Mapping
    click CLI "https://github.com/cbourgois/simonsays/blob/master/bin/simonsays.js"
    click Core "https://github.com/cbourgois/simonsays/blob/master/src/simonsays.js"
    click JSParser "https://github.com/cbourgois/simonsays/blob/master/src/parser/angularjs.js"
    click HTMLParser "https://github.com/cbourgois/simonsays/blob/master/src/parser/html.js"
    click TransParser "https://github.com/cbourgois/simonsays/blob/master/src/parser/translations.js"
    click KeyFinder "https://github.com/cbourgois/simonsays/blob/master/src/finder/angularjs.js"
    click AJResourceComp "https://github.com/cbourgois/simonsays/blob/master/src/compiler/angularjs.js"
    click HTMLResourceComp "https://github.com/cbourgois/simonsays/blob/master/src/compiler/html.js"
    click Interpolate "https://github.com/cbourgois/simonsays/blob/master/src/angularjs/interpolate.js"
    click ParseHelp "https://github.com/cbourgois/simonsays/blob/master/src/angularjs/parse.js"
    click CoreTest "https://github.com/cbourgois/simonsays/blob/master/src/simonsays.test.js"
    click HTMLParserTest "https://github.com/cbourgois/simonsays/blob/master/src/parser/html.test.js"
    click TransParserTest "https://github.com/cbourgois/simonsays/blob/master/src/parser/translations.test.js"
    click FinderTest "https://github.com/cbourgois/simonsays/blob/master/src/finder/angularjs.test.js"

    %% Styles
    classDef control fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef subsystem fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef resource fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef test fill:#FFEBEE,stroke:#E53935,color:#B71C1C;
```
