# mdwiki-td/tdc architecture

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

- Interactive diagram: https://gitdiagram.com/mdwiki-td/tdc
- Repository: https://github.com/mdwiki-td/tdc

## Overview

##### Project Type and Purpose
- TDC is a web-based platform built to support coordinators in managing translation projects for WikiProject Medicine. It integrates a variety of tools for tracking translation progress, managing user data, and administrating different translation-related components.
- The system is implemented in PHP and is structured as a collection of modules that handle tasks like retrieving recent translations, updating user or QID information, adding new pages, and managing campaign data.

##### Analyzing the File Structure
- Key top-level directories include:
- Tables: Contains SQL-related files (e.g., sql_tables.php, tables.php, langcode.php) that likely define the database schema or utility functions for running SQL queries.
- actions: Holds several PHP files (e.g., mdwiki_sql.php) that serve as intermediaries between the application logic and the database. These files encapsulate SQL queries for reading (SELECT) and writing (INSERT/UPDATE/DELETE) data.
- api_or_sql: Contains endpoints (such as index.php, process_data.php, recent_data.php) that provide API access to underlying SQL operations.
- auth: Manages authentication, which will involve SQL SELECT queries (to verify user credentials) and possibly SQL WRITE operations (to update user data or track login activity).
- coordinator: Has extensive subdirectories (admin, tools, etc.) for specific functional modules – for campaigns, emails, QIDs, settings, and more. Each module here is intended for both administrative oversight and data manipulation, indicating SQL query use both for SELECT (to retrieve current settings, lists, and reports) and WRITE actions (to add or update records).
- Configuration and workflow files (GitHub actions, .yaml files) support CI/CD but do not directly impact SQL operations.

##### Specific Tools/Modules Using SQL SELECT and SQL WRITE

- Tables Module:
- Tables/sql_tables.php and Tables/tables.php: These likely include the definitions and possibly even the execution of SQL commands to create or reference tables. Although not a typical “tool” in runtime, they directly set up the structure upon which SQL SELECT/WRITE commands operate.

- Actions Module:
- actions/mdwiki_sql.php: This file appears dedicated to handling SQL operations concerning wiki-related translation data. Expect it to handle SELECT queries when retrieving translation records (for display in reports) and WRITE operations when inserting or updating translation statuses.
- Other files in the actions folder (like html.php, html_side1.php, and functions.php) may also call SQL operations indirectly through common utility functions.

- API or SQL Module:
- api_or_sql/index.php, process_data.php, and recent_data.php: These endpoints function as the application’s API layer for SQL operations.
° recent_data.php is interpreted as a module primarily executing SQL SELECT queries to return the latest translation information.
° process_data.php is likely used to perform SQL WRITE operations—for example, inserting or updating translation records based on user actions or automated processes.
° include.php serves as the common inclusion tool to facilitate SQL operations in these files.

- Auth Module:
- auth/index.php and related files (config.php, user_infos.php): Upon authentication, these are expected to run SQL SELECT queries (to validate user credentials and fetch profile data) as well as SQL WRITE queries (to update last login timestamps or user activity logs).

- Coordinator Modules (Admin & Tools):
- The coordinator folder comprises several admin and tool submodules such as:
° Admin/Campaigns (index.php, post.php): Use SQL SELECT to list current campaigns and SQL WRITE for inserting or modifying campaign details.
° Admin/Emails (index.php, edit_user.php, post.php, sugust.php): Perform SQL SELECT to present current email lists, and SQL WRITE to update or add new email data.
° Admin/Qids and Qids_Others (index.php, post.php, edit_qid.php): Retrieve existing QID assignments via SELECT and update them via WRITE.
° Admin/Add (index.php, post.php): Facilitates adding new translation pages where it uses SQL WRITE to save new page entries, while likely also using SELECT to confirm data.
° Admin/Settings (index.php, post.php): Reads current settings using SELECT queries and updates configuration parameters via SQL WRITE.
° Additional modules (full_translators, translated, tt, wikirefs_options) similarly rely on a combination of SQL SELECT (to populate UI lists and reports) and SQL WRITE (for new entries or modifications).

a. Main Components to Represent:
- Frontend/UI Components:
- User pages including coordinators’ dashboards, admin panels, and login pages.
- Backend/API Layer:
- Actions and api_or_sql endpoints where the core business logic runs.
- Auth module for authentication.
- Administrative Modules:
- All coordinator/admin sub-modules (Campaigns, Emails, QIDs, etc.) which interface with the frontend UI.
- Database:

b. Relationships and Interactions:
- WRITE operations (e.g., in process_data.php, admin/post.php files) with “SQL WRITE.”
- Auth and Admin modules similarly to the Database, indicating different flows for data retrieval and updates.

c. Architectural Patterns:
- Modules that conform to RESTful API principles (particularly in the api_or_sql and actions directories) and note any MVC-like partitioning in the coordinator modules.

d. Technologies and Frameworks:
- PHP is the primary language used.
- Although not explicitly detailed, the use of GitHub actions implies CI/CD integration.
- If any SQL abstraction libraries or frameworks are present (check auth/vendor_load.php for potential composer dependencies), note their role in mediating SQL operations.

##### Final Remarks
- Don’t hesitate to add brief text annotations or legends that clarify the technical choices and the flow of data, which is especially useful for modules in the admin area.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        F1["Frontend: Dashboard & Login"] 
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        AL["Actions: mdwiki_sql.php - Handles wiki translation operations (SQL SELECT/WRITE)"]
        API["API/SQL Module: Endpoints (index, recent_data[SELECT], process_data[WRITE], include)"]
        AUTH["Auth Module: Manages authentication (SQL SELECT/WRITE)"]
        
        subgraph "Coordinator Admin Modules"
            CAM["Campaigns Module: Lists campaigns and updates records (SELECT/WRITE)"]
            EMA["Emails Module: Retrieves and updates email data (SELECT/WRITE)"]
            QID["QIDs Module: Manages QID assignments and updates (SELECT/WRITE)"]
            ADD["Add Module: Adds new pages with verification (SELECT/WRITE)"]
            SET["Settings Module: Reads and updates configuration (SELECT/WRITE)"]
            FT["Full Translators Module: Manages translator data (SELECT/WRITE)"]
            TR["Translated Module: Handles translation records (SELECT/WRITE)"]
            TT["TT Module: Manages translation types (SELECT/WRITE)"]
            WR["Wikirefs Options Module: Configures wikireference settings (SELECT/WRITE)"]
            TOOLS["Tools Module: Processes data and displays statistics (SELECT/WRITE)"]
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DB["Database: Translation Tables"]
    end

    %% Data flow from Frontend to Backend Modules
    F1 -->|"Request"| AUTH
    F1 -->|"Request"| AL
    F1 -->|"Request"| API
    F1 -->|"Request"| CAM
    F1 -->|"Request"| EMA
    F1 -->|"Request"| QID
    F1 -->|"Request"| ADD
    F1 -->|"Request"| SET
    F1 -->|"Request"| FT
    F1 -->|"Request"| TR
    F1 -->|"Request"| TT
    F1 -->|"Request"| WR
    F1 -->|"Request"| TOOLS

    %% Backend Modules interacting with Database
    AL -->|"SQL SELECT/WRITE"| DB
    API -->|"SQL SELECT/WRITE"| DB
    AUTH -->|"SQL SELECT/WRITE"| DB
    CAM -->|"SQL SELECT/WRITE"| DB
    EMA -->|"SQL SELECT/WRITE"| DB
    QID -->|"SQL SELECT/WRITE"| DB
    ADD -->|"SQL SELECT/WRITE"| DB
    SET -->|"SQL SELECT/WRITE"| DB
    FT -->|"SQL SELECT/WRITE"| DB
    TR -->|"SQL SELECT/WRITE"| DB
    TT -->|"SQL SELECT/WRITE"| DB
    WR -->|"SQL SELECT/WRITE"| DB
    TOOLS -->|"SQL SELECT/WRITE"| DB

    %% Click Events for Component Mapping
    click DB "https://github.com/mdwiki-td/tdc/blob/main/Tables/tables.php"
    click AL "https://github.com/mdwiki-td/tdc/blob/main/actions/mdwiki_sql.php"
    click API "https://github.com/mdwiki-td/tdc/blob/main/api_or_sql/index.php"
    click AUTH "https://github.com/mdwiki-td/tdc/blob/main/auth/index.php"
    click CAM "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/Campaigns/index.php"
    click EMA "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/Emails/index.php"
    click QID "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/qids/index.php"
    click ADD "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/add/index.php"
    click SET "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/settings/index.php"
    click FT "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/full_translators/index.php"
    click TR "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/translated/index.php"
    click TT "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/tt/index.php"
    click WR "https://github.com/mdwiki-td/tdc/blob/main/coordinator/admin/wikirefs_options/index.php"
    click TOOLS "https://github.com/mdwiki-td/tdc/blob/main/coordinator/tools/index.php"

    %% Styles
    classDef frontend fill:#f9d6d5,stroke:#d45b5b,stroke-width:2px,color:#000;
    classDef backend fill:#d5e8d4,stroke:#82b366,stroke-width:2px,color:#000;
    classDef coordinator fill:#d0e0e3,stroke:#4a777a,stroke-width:2px,color:#000;
    classDef database fill:#fce5cd,stroke:#e69138,stroke-width:2px,color:#000;

    class F1 frontend;
    class AL,API,AUTH backend;
    class CAM,EMA,QID,ADD,SET,FT,TR,TT,WR,TOOLS coordinator;
    class DB database;
```
