# tanloong/neosca architecture

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

- Interactive diagram: https://gitdiagram.com/tanloong/neosca
- Repository: https://github.com/tanloong/neosca

## Overview

##### Project Overview and Context
- Project Purpose: NeoSCA performs text complexity analysis. It supports syntactic complexity (SCA) and lexical complexity (LCA) analysis.
- Usage Modes: Users interact with the system either through a GUI (packaged application) or via command-line calls (using “python -m neosca …” commands).
- Key Technical Choices: The project has separate modules for handling NLP and Tregex-like processing, settings/configuration management, and both CLI & GUI entry points.

##### Analyzing the File Structure and Architectural Components
- Top-Level Directories:
- "src/neosca": Houses the primary application logic.
- "scripts": Contains various packaging, version bumping, and auxiliary maintenance scripts.
- "tests": Includes test cases for numerous modules, ensuring project robustness.
- Configuration and packaging files (.pyproject.toml, Makefile, MANIFEST.in, etc.) which are essential for building and distributing the package.
- Core Source Modules:
- CLI and GUI entry points: Look at "ns_main_cli.py" and "ns_main_gui.py" for starting the application.
- Analysis Modules: Two distinct directories are present:
- ns_sca: Likely responsible for Syntactic Complexity Analysis (e.g., l2sca.py, ns_sca.py, and ns_sca_counter.py).
- ns_lca: Dedicated to Lexical Complexity Analysis (e.g., ns_lca.py, ns_lca_counter.py, and word_classifiers.py).
- NLP and Tregex functionality: The "ns_nlp.py" module and entire "ns_tregex" folder (providing head-finding and related tree-processing algorithms) indicate a clear NLP processing layer.
- Supporting Modules: Additional folders like "ns_data" (holding assets and static data), "ns_settings" (handling GUI settings and configuration), "ns_widgets" (GUI component definitions), and utility modules for I/O, printing, platform info, threads, and singletons.
- Testing and CI/CD: The “tests” directory and the configuration files in the “.github/workflows” directory indicate continuous integration and rigorous testing practices.

##### Components and Their Interactions
a. Frontend Components (User Interfaces)
- Command-Line Interface (CLI): Represented by ns_main_cli.py.
- Graphical User Interface (GUI): Represented by ns_main_gui.py (which leverages ns_widgets and ns_settings).
b. Core Analysis Engine
- Syntactic Complexity Analyzer: Encapsulated in the ns_sca submodule.
- Lexical Complexity Analyzer: Encapsulated in the ns_lca submodule.
c. Natural Language Processing Layer
- General NLP Utility: ns_nlp.py.
- Tregex-like Parsing: Contents within ns_tregex (with head-finder and tree modules).
d. Data and Configuration Management
- Settings & Configuration: ns_settings (dialog settings, default settings, widget customization).
e. Infrastructure and Utilities
- Utility Helpers: Modules such as ns_io, ns_platform_info, ns_print, ns_utils, and exception handling.
- Threads and Singleton Management: ns_threads, ns_singleton ensuring proper resource management.
f. External Interfaces
- Packaging and Build Scripts: Scripts for version bumping, packaging, and cross-platform synchronization.
- CI/CD Integrations: GitHub workflows that integrate linting, testing, and packaging (as seen in the .github directory).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design clearly separates interface (CLI/GUI) from the underlying analysis engines.
- Modular Design: Each functionality (analysis, NLP, settings, UI Widgets) is encapsulated in its own module or subpackage.
- Reusability and Extensibility: Utility modules and separated settings facilitate future updates or expansion of functionality.
- Testability: Robust test coverage indicated by the tests directory reinforces modular design and clean separation between components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        CLI["CLI Entry (ns_main_cli)"]:::ui
        GUI["GUI Entry (ns_main_gui)"]:::ui
    end

    subgraph "Core Analysis Engine"
        SCA["Syntactic Complexity Analyzer (ns_sca)"]:::analysis
        LCA["Lexical Complexity Analyzer (ns_lca)"]:::analysis
    end

    subgraph "NLP Processing Layer"
        NLP["General NLP Utilities (ns_nlp)"]:::nlp
        Tregex["Tregex Processing (ns_tregex)"]:::nlp
    end

    subgraph "Data & Configuration"
        Data["Data Assets (ns_data)"]:::data
        Settings["Settings & Configuration (ns_settings, ns_widgets)"]:::data
    end

    subgraph "Utility Modules"
        IO["IO Module (ns_io)"]:::util
        Platform["Platform Info (ns_platform_info)"]:::util
        Print["Print Module (ns_print)"]:::util
        QSS["QSS Module (ns_qss)"]:::util
        Utils["Utils Module (ns_utils)"]:::util
        Exceptions["Exceptions (ns_exceptions)"]:::util
        Singleton["Singleton (ns_singleton)"]:::util
        Threads["Threads (ns_threads)"]:::util
    end

    subgraph "External Integrations"
        Packaging["Packaging & Build Scripts"]:::external
    end

    %% Connections from User Interfaces to Core Analysis Engine
    CLI -->|"calls"| SCA
    CLI -->|"calls"| LCA
    GUI -->|"calls"| SCA
    GUI -->|"calls"| LCA

    %% Connections from Core Analysis Engine to NLP Processing Layer
    SCA -->|"uses"| NLP
    SCA -->|"uses"| Tregex
    LCA -->|"uses"| NLP
    LCA -->|"uses"| Tregex

    %% Connection from GUI to Settings in Data & Configuration
    GUI -->|"reads"| Settings

    %% Connections from Data & Configuration to Core and NLP layers
    Data -->|"supplies"| SCA
    Data -->|"supplies"| LCA
    Data -->|"supplies"| NLP

    %% Connections from Core modules to Utility Modules
    SCA -->|"helper"| IO
    LCA -->|"helper"| Print
    SCA -->|"threadMgmt"| Threads
    LCA -->|"threadMgmt"| Threads

    %% Connections from NLP and Tregex to Utility Modules
    NLP -->|"helper"| Utils
    Tregex -->|"exceptionHandler"| Exceptions

    %% Connection from GUI to Utility Modules (singleton support)
    GUI -->|"singletonAccess"| Singleton

    %% External Integrations connections
    Packaging -->|"deploys"| CLI
    Packaging -->|"deploys"| GUI

    %% Click Events
    click CLI "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_main_cli.py"
    click GUI "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_main_gui.py"
    click SCA "https://github.com/tanloong/neosca/tree/master/src/neosca/ns_sca"
    click LCA "https://github.com/tanloong/neosca/tree/master/src/neosca/ns_lca"
    click NLP "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_nlp.py"
    click Tregex "https://github.com/tanloong/neosca/tree/master/src/neosca/ns_tregex"
    click Data "https://github.com/tanloong/neosca/tree/master/src/neosca/ns_data"
    click Settings "https://github.com/tanloong/neosca/tree/master/src/neosca/ns_settings"
    click IO "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_io.py"
    click Platform "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_platform_info.py"
    click Print "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_print.py"
    click QSS "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_qss.py"
    click Utils "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_utils.py"
    click Exceptions "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_exceptions.py"
    click Singleton "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_singleton.py"
    click Threads "https://github.com/tanloong/neosca/blob/master/src/neosca/ns_threads.py"
    click Packaging "https://github.com/tanloong/neosca/tree/master/scripts"

    %% Styles
    classDef ui fill:#a3d5ff,stroke:#036,stroke-width:2px;
    classDef analysis fill:#ffecd1,stroke:#d35400,stroke-width:2px;
    classDef nlp fill:#d1ffd8,stroke:#27ae60,stroke-width:2px;
    classDef data fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef util fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
```
