# notesjor/corpusexplorer.terminal.console architecture

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

- Interactive diagram: https://gitdiagram.com/notesjor/corpusexplorer.terminal.console
- Repository: https://github.com/notesjor/corpusexplorer.terminal.console

## Overview

##### Overall project type and purpose
- The README shows that this is a console utility (originally named CorpusExplorer-Port-R) that wraps a rich set of corpus analysis actions. It exposes command‑line, scripting, and even RESTful web service interfaces.
- The tool is designed for corpus annotation, conversion, filtering, statistical analysis (e.g. token frequency, KWIC, clustering) and supports additional integrations with R, Python, and Jupyter Notebooks.
- It provides many “actions” (each implemented in the Action folder) and supports plugins/extensions for different import/export formats and tagging systems.

##### File structure and extract main architectural components
- The “Action” folder contains many C# classes under the “CorpusExplorer.Sdk.Action” namespace. These classes implement the myriad “actions” (from basic analysis to complex queries) and are the core of the processing engine.
- The “Helper” folder contains utility classes (for file queries, XML value extraction, etc.) that assist the Action components.
- The “Web” and “Swagger” directories show that a RESTful web service exists – one component is a router/bridge (e.g. WebService.cs, WebServiceDirect.cs) that converts web requests into calls to the action engine.
- There is a “Python” folder. It contains setup and packaging files so that parts of the logic or APIs can be wrapped and called from Python (and by extension, from Jupyter).
- “Xml” shows classes and XSD/processing scripts that relate to processing or transforming XML representations of corpus data.
- Build and configuration files (e.g. .csproj files, App.config, packages.config) indicate this is a .NET-based application, with additional support for .NET 5 (under the DotNet5 folder).

##### Key components and relationships
a. Main Components:
– Console Application: The entry point (Program.cs and CorpusExplorer.Terminal.Console project) that parses command‑line arguments.
– Action Engine/SDK: Located in the Action/CorpusExplorer.Sdk.Action folder; a collection of classes (such as FrequencyAction, ClusterAction, etc.) which execute individual corpus analysis commands.
– Helpers and Utilities: General support functionality such as corpus loading (CorpusLoadHelper), file queries (FileQueriesHelper) – grouped together in modules.
– Web Service Interface: The “Web” and “Swagger” directories expose a REST-based interface (via WebService.cs and its related bridge classes) which wraps calls to the Action Engine.
– Python Integration: A packaged version (in the Python directory) to allow invocation from Python scripts and notebooks.
– XML Processor: Modules that process, validate, and transform XML (under the Xml directory), which may be used by actions that require XML-based corpus representations.
– Configuration/BOM: Application configuration files (App.config, packages.config) and metadata files that control dependency injection or settings in the application.

b. Relationships and interactions:
– The Console Application takes commands (for example, “import”, “annotate”, “convert”, “query”), parses them, and dispatches them to the Action Engine.
– The Action Engine modules (individual action classes) perform the specific corpus operations and may call into helper classes for tasks like file I/O, XML parsing, or parallel execution.
– When a web service call is received (via the REST interface), the WebService component translates it into a standard action call, thereby reusing the action engine.
– Python clients call into the packaged API (via compiled assemblies or using a subprocess call to “cec.exe”) – integrating through the same underlying action engine.
– The XML module is used to process script definitions that might be provided at runtime or for configuration/export purposes.

##### Architectural Patterns/Design Principles
- A modular design with clear separation between the user/interface layer (Console, API, Python), the business logic layer (Action Engine), and supporting utilities (Helpers and XML Processing).
- Plugin-like architecture in the Action Engine: new actions can be added simply as new classes implementing a common interface, making the tool easily extensible.
- Use of dependency injection (implied by the structure and helper classes) to decouple components.
- A multi-protocol approach: same business logic is exposed via command line, batch-scripting, REST, and even via Python wrappers.
- Separation of concerns: each layer (parsing commands, performing actions, formatting output) is kept in its own module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend/Interfaces"
        CLI["Console Entry Point (cec.exe)"]:::frontend
        REST["REST Web Service Layer"]:::frontend
        PY["Python Integration Layer"]:::frontend
    end

    subgraph "Core Processing"
        AE["Action Engine Module"]:::core
    end

    subgraph "Supporting Modules"
        UTIL["Helper Utilities"]:::utility
        XMLP["XML Processing Module"]:::utility
        CFG["Configuration / Build Files"]:::config
    end

    CLI -->|"commandParsing"| AE
    REST -->|"requestDispatch"| AE
    PY -->|"apiCall"| AE
    AE -->|"usesHelper"| UTIL
    AE -->|"processXML"| XMLP
    CFG -->|"configures"| AE

    click CLI "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Program.cs"
    click CLI "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/CorpusExplorer.Terminal.Console.csproj"
    click AE "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Action/CorpusExplorer.Sdk.Action"
    click UTIL "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Helper/ConsoleHelper.cs"
    click UTIL "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Helper/CorpusLoadHelper.cs"
    click UTIL "https://github.com/notesjor/corpusexplorer.terminal.console/tree/master/Action/CorpusExplorer.Sdk.Action/Helper"
    click REST "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Web/WebService.cs"
    click REST "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Web/WebServiceDirect.cs"
    click REST "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Swagger/WebService/swagger.json"
    click REST "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Swagger/WebServiceDirect/swagger.yaml"
    click PY "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Python/setup.py"
    click PY "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Python/src/CorpusExplorer/CorpusExplorer.py"
    click XMLP "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Xml/Processor/XmlScriptProcessor.cs"
    click XMLP "https://github.com/notesjor/corpusexplorer.terminal.console/tree/master/Xml/Model"
    click CFG "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/App.config"
    click CFG "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/Action/CorpusExplorer.Sdk.Action/app.config"
    click CFG "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/packages.config"
    click CFG "https://github.com/notesjor/corpusexplorer.terminal.console/blob/master/DotNet5/CorpusExplorer.Terminal.Console.DotNet5/CorpusExplorer.Terminal.Console.DotNet5.csproj"

    classDef frontend fill:#f96,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef utility fill:#9f6,stroke:#333,stroke-width:2px;
    classDef config fill:#f66,stroke:#333,stroke-width:2px;
```
