# sam1037/cuhk-dao architecture

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

- Interactive diagram: https://gitdiagram.com/sam1037/cuhk-dao
- Repository: https://github.com/sam1037/cuhk-dao

## Overview

##### Main Components
- Data Storage and Ingestion:
- Data Sources: “data”, “archive”, and even “relevantDocuments” (which include research PDFs, JSON, markdown) represent raw input data.
- Their nature – many JSON files (organized by “IssueNumber”) – indicates a data repository containing text-based content (perhaps poems or written material) that is later analyzed.
- Data Processing and Analysis:
- “src/dataLoader.py” is likely responsible for reading and formatting this data.
- Image Generation and Feedback Loop:
- “src/imageGeneration/” contains multiple scripts such as “imgGen.py”, “generateAndSaveImg.py”, “imgEvaluator.py”, and a test file.
- The README mentions “image generation with feedback loop” and notes the need for a token for POE_API_WRAPPER – this reveals an external API dependency used by the image generation component.
- The loop may be visualized as: generated image output → evaluated by “imgEvaluator.py” → feedback to adjust parameters for “imgGen.py” via scripts like “compareModels.py” and “setup.py”.
- Presentation / Web Output:
- The “HTMLForWordpress” directory (and the “template” directory) are used for generating or templating HTML. They likely support the presentation of analysis results or images (WordPress-specific outputs).
- Testing and Integration:
- The “tests” directory and accompanying files (e.g., “test.py”, “corrtest.py”) indicate a test suite for ensuring system correctness and integration.

##### Relationships and Interactions
- Data Flow:
- Raw data from “data” and “archive” is loaded using the data loader modules in “src”.
- Analysis modules process this data to compute correlations and generate visualizations.
- Feedback Loop and Image Generation:
- Based on analysis or external prompts, the image generation module processes inputs. There is an evaluation step where “imgEvaluator.py” provides a feedback signal to the image generation process, possibly iterating over different models (as “compareModels.py” suggests) until an optimal image is produced.
- Presentation Pipeline:
- The outputs (analytical charts, generated images) get integrated into HTML pages through the “HTMLForWordpress” module and templated using files in the “template” directory.
- This may be intended for publication (perhaps on a WordPress-powered site) which is why there is both a “goodIsueOneHTML.html” file and a “generateHTML.py” script.
- External Dependencies:
- The API token for POE_API_WRAPPER (mentioned in the README) is used by the image generation module, suggesting an integration with an external image generation service.
- Additionally, “Noto_Sans_TC” may be providing font assets for any visual output.

##### Architectural Patterns and Design Principles
- Modularity: Each directory (data ingestion, analysis, image generation, output generation, testing) is separated into distinct logical modules.
- Feedback Loop: The image generation employs a feedback loop design, where outputs are evaluated and fed back to improve subsequent iterations.
- Separation of Concerns: Data processing, image generation, and HTML/template presentation are clearly handled in separate parts of the system, which promotes maintainability.
- Extensibility: With dedicated directories for templates and separate “src” processing components, it is easy to extend or substitute particular modules (e.g., trying different analysis algorithms or image generation models).

##### Technologies, Frameworks, and Libraries
- Python is the central programming language as evidenced by the .py files.
- The project may rely on libraries for data visualization (e.g., matplotlib, seaborn) and image manipulation.
- There is usage of external APIs for image generation (perhaps a generative AI library via POE_API_WRAPPER).
- Testing frameworks (possibly pytest based on the names in “tests”).

##### Instructing the Principal Software Engineer—Elements
- Use clear component labels:
- “Data Repository” (for data and archive directories)
- “Image Generation Module” (src/imageGeneration submodule, including imgGen, compareModels, and evaluator)
- “HTML/Template Generation” (HTMLForWordpress and template directories)
- “External API” (for POE_API_WRAPPER and any related token-based integrations)
- “Testing Framework” (tests directory)
- Data flow: from raw data sources → analysis modules → output generation.
- Feedback loop: from image evaluator back to image generator.
- Interaction with external services (e.g., API calls).
- A different style for processing modules.
- Another for external integrations (like a cloud or API service).
- A distinct look for the presentation layer.
- Detailed labeling so that each component shows its function (e.g., “Data Loader: transforms JSON content” or “ImgEvaluator: provides feedback to adjust generation parameters”).

- From the Data Loader, branch out to two processing streams:
– Another to “Image Generation & Feedback Loop” (src/imageGeneration elements, including imgEvaluator.py).
- An external node for “POE_API_WRAPPER” connected to the Image Generation module.
- “HTML/Template Generator” (using HTMLForWordpress and template data) receiving outputs from the processing pipelines.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Sources Subgraph
    subgraph "Data Sources"
        Data["Data Directory"]:::data
        Archive["Archive Directory"]:::data
        Relevant["RelevantDocuments Directory"]:::data
    end

    %% Data Processing and Analysis Subgraph
    subgraph "Data Loader & Analysis"
        Loader["Data Loader<br/>(Transforms JSON content)"]:::processing
        Analysis["Analysis Module"]:::processing
        Visualization["Visualization Module"]:::processing
        Complexity["Language Complexity Analysis"]:::processing
    end

    %% Image Generation and Feedback Loop Subgraph
    subgraph "Image Generation Module"
        ImgGen["Image Generation Core"]:::image
        AutoGen["Image Generation Automation"]:::image
        Compare["Model Comparison"]:::image
        Evaluator["Image Evaluation (Feedback)"]:::image
        Setup["Setup & Utilities<br/>(Setup)"]:::image
        Utils["Setup & Utilities<br/>(Utils)"]:::image
    end

    %% External API Component
    POE["POE_API_WRAPPER"]:::external

    %% Presentation / Web Output Subgraph
    subgraph "HTML / Template Generation"
        HTMLGen["HTML Generator"]:::presentation
        Template["Template Files"]:::presentation
    end

    %% Testing Component
    TestSuite["Test Suite"]:::testing

    %% Connections from Data Sources to Data Loader
    Data --> Loader
    Archive --> Loader
    Relevant --> Loader

    %% Connections within Data Loader & Analysis
    Loader --> Analysis
    Loader --> Visualization
    Loader --> Complexity

    %% Connections from Analysis to Presentation
    Analysis --> HTMLGen
    Visualization --> HTMLGen
    Complexity --> HTMLGen

    %% Connections from Analysis to Image Generation
    Analysis --> ImgGen

    %% Internal Image Generation flow
    ImgGen --> AutoGen
    AutoGen --> Compare
    ImgGen --> Evaluator
    Evaluator -- "feedback" --> ImgGen
    ImgGen --> Setup
    Setup --> Utils

    %% External API integration with Image Generation
    POE --> ImgGen

    %% Image Generation output to Presentation
    ImgGen --> HTMLGen
    Compare --> HTMLGen
    Evaluator --> HTMLGen

    %% Testing connections (dashed lines)
    TestSuite --- Loader
    TestSuite --- Analysis
    TestSuite --- Visualization
    TestSuite --- Complexity
    TestSuite --- ImgGen
    TestSuite --- Evaluator
    TestSuite --- HTMLGen

    %% Click Events for Data Sources
    click Data "https://github.com/sam1037/cuhk-dao/tree/main/data"
    click Archive "https://github.com/sam1037/cuhk-dao/tree/main/archive"
    click Relevant "https://github.com/sam1037/cuhk-dao/tree/main/relevantDocuments"

    %% Click Events for Data Processing and Analysis
    click Loader "https://github.com/sam1037/cuhk-dao/blob/main/src/dataLoader.py"
    click Analysis "https://github.com/sam1037/cuhk-dao/blob/main/src/analysis.py"
    click Visualization "https://github.com/sam1037/cuhk-dao/blob/main/src/visualize.py"
    click Complexity "https://github.com/sam1037/cuhk-dao/blob/main/src/wordingComplexity.py"

    %% Click Events for Image Generation and Feedback Loop
    click ImgGen "https://github.com/sam1037/cuhk-dao/blob/main/src/imageGeneration/imgGen.py"
    click AutoGen "https://github.com/sam1037/cuhk-dao/blob/main/src/imageGeneration/generateAndSaveImg.py"
    click Compare "https://github.com/sam1037/cuhk-dao/blob/main/src/imageGeneration/compareModels.py"
    click Evaluator "https://github.com/sam1037/cuhk-dao/blob/main/src/imageGeneration/imgEvaluator.py"
    click Setup "https://github.com/sam1037/cuhk-dao/blob/main/src/imageGeneration/setup.py"
    click Utils "https://github.com/sam1037/cuhk-dao/blob/main/src/imageGeneration/utils.py"

    %% Click Events for Presentation / Web Output
    click HTMLGen "https://github.com/sam1037/cuhk-dao/tree/main/HTMLForWordpress"
    click Template "https://github.com/sam1037/cuhk-dao/tree/main/template"

    %% Click Event for Testing
    click TestSuite "https://github.com/sam1037/cuhk-dao/tree/main/tests"

    %% Styles
    classDef data fill:#AEE1F9,stroke:#0B74C6,stroke-width:2px;
    classDef processing fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef image fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#D68910,stroke-width:2px;
    classDef presentation fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef testing fill:#D5DBDB,stroke:#616A6B,stroke-width:2px;
```
