# its-hmny/choreia architecture

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

- Interactive diagram: https://gitdiagram.com/its-hmny/choreia
- Repository: https://github.com/its-hmny/choreia

## Overview

##### Main Components
- CLI/Entry Point: Represented by cmd/main.go. This component is responsible for accepting user inputs and passing the Go source file to the rest of the system.
- Static Analysis Module: Found in internal/static_analysis, which contains several files (branch.go, channel.go, loop.go, function.go, etc.). This module parses the AST, extracts code constructs, and gathers metadata.
- Data Structures Module: Under internal/data_structures/fsa, this is where the basic types and transitions of the Finite State Automata (FSA) are defined.
- Transformation Layer: Located in internal/transforms (with files like determinization.go, extraction.go, reconciliation.go). This layer takes the raw static analysis output and converts it into a deterministic or well-formed Choreography Automata.
- Examples: Although not part of the core system, the example directory provides use cases that might be helpful when discussing how the tool works on sample inputs.

##### Establish Component Relationships & Data Flow
- The CLI captures the input Go file (using command-line flags such as -i, -o, -t) and invokes the main analysis flow.
- The Go source file is then sent into the Static Analysis Module, where different aspects (branches, loops, channels, function calls) are parsed and analyzed.
- The output of static analysis feeds into the Transformation Layer. Here, processes such as extraction, determinization, and reconciliation are applied to convert the initial metadata into a formal FSA.
- The FSA constructed using the definitions in internal/data_structures/fsa represents the Choreography Automata.
- The final result (e.g., an SVG file for visualization) is output to a user-specified location.

##### Architectural Patterns & Design Principles
- Layered Architecture: Visually represent a pipeline where the input flows through distinct modules.
- Modularity & Extensibility: Each internal package (static_analysis, data_structures, transforms) is built as a modular component. This should be highlighted to show how the system is organized for maintainability and future enhancements.

##### Technologies and Libraries
- Go: As the primary language and runtime.
- Standard Library Packages for AST parsing and file I/O (even if not explicitly shown, mention that the Go toolchain might be leveraged for parsing).
- Any third-party libraries the project might depend on (as mentioned in the README dependencies section).

##### Elements
– "CLI/Entry Point (cmd/main.go)"
– "Static Analyzer (internal/static_analysis)" with subcomponents: Branch, Loop, Channel, Function modules, etc.
– "FSA Data Structures (internal/data_structures/fsa)"
– "Transformation Modules (internal/transforms)" listing determinization, extraction, and reconciliation.
– "Output Generator/Visualizer" (implicitly represented by the SVG output in the README).
– Show data flowing from the CLI to Static Analysis.
– Indicate the subsequent creation and processing of the FSA.

##### Detailed Breakdown
1. Input Collection:
– Command-line interface module accepts flags (-i, -o, -t) and passes the Go file to the analysis engine.
2. Static Analysis Engine:
– Decompose this module further into submodules focusing on different AST elements such as loops, conditions, and channels.
3. Transformation Engine:
– Illustrate the process steps (extraction, determinization, reconciliation) that manipulate and refine the raw analysis data into an FSA.
4. FSA Generation:
5. Output Generation:
– Show the final step where the generated Choreography Automata is rendered (e.g., to an SVG file) and saved.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CLI["CLI/Entry Point (cmd/main.go)"]:::module
    end

    %% Static Analysis Layer
    subgraph "Static Analysis Layer"
        SA["Static Analyzer (internal/static_analysis)"]:::module
        SA1["- Branch Analysis"]:::submodule
        SA2["- Loop Analysis"]:::submodule
        SA3["- Channel Analysis"]:::submodule
        SA4["- Function Analysis"]:::submodule
        SA5["- General Parsing"]:::submodule
        SA --> SA1
        SA --> SA2
        SA --> SA3
        SA --> SA4
        SA --> SA5
    end

    %% Transformation Layer
    subgraph "Transformation Layer"
        TRANS["Transformation Engine (internal/transforms)"]:::module
        TRANS1["- Extraction"]:::submodule
        TRANS2["- Determinization"]:::submodule
        TRANS3["- Reconciliation"]:::submodule
        TRANS --> TRANS1
        TRANS --> TRANS2
        TRANS --> TRANS3
    end

    %% FSA Generation Layer
    subgraph "FSA Generation"
        FSA["FSA Data Structures (internal/data_structures/fsa)"]:::data
    end

    %% Output Generation
    subgraph "Output Generation"
        OUT["Output Generator/Visualizer (SVG)"]:::module
    end

    %% Examples (Side Branch)
    EXAMPLES["Examples (example)"]:::example

    %% Data Flow Connections
    CLI -->|"PassesGoFile"| SA
    SA -->|"StaticMetadata"| TRANS
    TRANS -->|"FSAConstruction"| FSA
    FSA -->|"RenderAutomata"| OUT
    CLI ---|"ReferenceExamples"| EXAMPLES

    %% Click Events
    click CLI "https://github.com/its-hmny/choreia/blob/main/cmd/main.go"
    click SA "https://github.com/its-hmny/choreia/tree/main/internal/static_analysis"
    click TRANS "https://github.com/its-hmny/choreia/tree/main/internal/transforms"
    click FSA "https://github.com/its-hmny/choreia/tree/main/internal/data_structures/fsa"
    click EXAMPLES "https://github.com/its-hmny/choreia/tree/main/example"

    %% Styles
    classDef module fill:#F4D03F,stroke:#333,stroke-width:2px;
    classDef submodule fill:#AED6F1,stroke:#333,stroke-width:1px;
    classDef data fill:#A3E4D7,stroke:#333,stroke-width:2px;
    classDef example fill:#82E0AA,stroke:#333,stroke-width:2px;
```
