# thu-coai/psyqa architecture

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

- Interactive diagram: https://gitdiagram.com/thu-coai/psyqa
- Repository: https://github.com/thu-coai/psyqa

## Overview

##### Project type and purpose
- PsyQA is not an application codebase but a research dataset repository. It contains a small example data file (PsyQA_example.json), a user‐agreement document for full data access, and a README describing the dataset and references to training/evaluation codebases.
- Its primary purpose is to provide structured counseling QA pairs with strategy annotations for training and evaluating text‐generation models in Chinese mental‐health support.

##### File structure
- Top-level files:
- PsyQA_example.json – a small excerpt of the full data in JSON format
- PsyQA数据集使用用户协议.docx – the legal agreement for accessing the full dataset
- README.md – project description, access instructions, and references
- No code or subdirectories; all processing/training/evaluation lives in external repos.

##### README for additional insights
- Mentions two external codebases:
- GPT2-Chinese training code: https://github.com/Morizeyao/GPT2-Chinese
- NLG-evaluation metrics code: https://github.com/GrittyChen/NLG-evaluation

##### Main components
a. Data Source
- PsyQA_example.json (example)
- Full PsyQA dataset (after agreement)
b. Access Control
- User Agreement & Approval process
- Dataset download portal/email workflow
c. Data Preprocessing
- JSON parsing & cleaning
- Strategy annotation extraction
d. Training Pipeline
- GPT2-Chinese codebase
- Tokenization, model fine-tuning, checkpoints
e. Evaluation Pipeline
- NLG-evaluation tools (BLEU, ROUGE, others)
f. (Optional) Deployment/Serving
- Model server or API layer for generating counseling responses

##### Relationships and interactions
1. User fills & submits the agreement → receives dataset link
2. Dataset downloads into a local storage
3. Preprocessing module reads JSON → outputs training examples
4. Preprocessed data feeds into the GPT2-Chinese training pipeline
5. Trained model outputs are sent to the evaluation pipeline
6. Evaluation metrics reported back to researchers

##### Architectural patterns & design principles
- Modular pipelines: clearly separate data ingestion, preprocessing, training, evaluation
- Externalized dependencies: use of maintained open-source repos for model code and metrics
- Reproducibility: versioned data, config files (implied), checkpoints
- Security/compliance: access controlled by signed user agreements

##### Technologies, frameworks & libraries
- Data format: JSON
- Preprocessing: Python scripts (pandas, json)
- Training: Hugging-Face Transformers or native PyTorch code (GPT2-Chinese)
- Evaluation: Python metrics library (from NLG-evaluation repo)
- Orchestration: you may use makefiles, shell scripts, or an ML workflow tool (Airflow, MLflow) if desired

##### Detail without over-fragmenting
- Every logical step in the pipeline, from agreement to final metrics
- Avoid drawing every JSON field; group under “PsyQA JSON data”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Agreement & Access Control
    User["User"]:::admin
    Agreement["PsyQA数据集使用用户协议.docx"]:::admin
    Download["Dataset Download Portal"]:::data

    %% Data Sources
    Example["PsyQA_example.json"]:::data
    Full["Full PsyQA Dataset"]:::data

    %% Preprocessing
    Preprocess["Data Preprocessing\n(Python: pandas, json)"]:::compute

    %% Training
    Training["Training Pipeline\nGPT2-Chinese (PyTorch)"]:::compute
    External1["GPT2-Chinese Repo"]:::external

    %% Evaluation
    Evaluation["Evaluation Pipeline\nNLG-evaluation Metrics"]:::compute
    External2["NLG-evaluation Repo"]:::external

    %% Deployment (Optional)
    Deployment["Deployment/API Layer\n(REST/gRPC)"]:::compute

    %% Project Description
    README["README.md\n(Project Description & References)"]:::external

    %% Flow
    User -->|"submits agreement"| Agreement
    Agreement -->|"grants access"| Download
    Download --> Example
    Download --> Full
    Example --> Preprocess
    Full --> Preprocess
    Preprocess --> Training
    Training --> Evaluation
    Evaluation --> Deployment

    %% External Dependencies
    Training -.-> External1
    Evaluation -.-> External2
    User -.-> README

    %% Click Events
    click Example "https://github.com/thu-coai/psyqa/blob/main/PsyQA_example.json"
    click Agreement "https://github.com/thu-coai/psyqa/blob/main/PsyQA数据集使用用户协议.docx"
    click README "https://github.com/thu-coai/psyqa/blob/main/README.md"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef compute fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100,stroke-dasharray: 5 5;
    classDef admin fill:#E0E0E0,stroke:#9E9E9E,color:#424242;
```
