# mdwiki-td/translation-dashboard architecture

> Architecture diagram of the GitHub repository mdwiki-td/translation-dashboard, 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/translation-dashboard
- Repository: https://github.com/mdwiki-td/translation-dashboard

## Overview

##### Project Type and Purpose
- This project is a web-based translation dashboard tool. Its primary function is to identify Wikidata items that have a page on mdwiki.org but are missing from another Wikipedia language.
- The README confirms its purpose and shows that it’s deployed to mdwiki.toolforge.org.
- It is built using PHP along with HTML, CSS, and JavaScript for the user interface.

##### Core Architectural Components
A. User Interface/Entry Points:
- Front-facing pages – as per the additional instructions, emphasize the main pages:
- The “results” module (files in the results directory such as SPARQLDispatcher.php, fetch_cat_data.php, etc.).
- The “missing” page (missing.php) which likely shows data for missing translations.
- The “leaderboard” module (contents of the leaderboard directory) that aggregates and displays ranking-related information.
- Other pages (index.php, auth.php, coordinator.php, header, footer, etc.) support login, navigation, and shared layout elements.

B. Frontend Assets:
- CSS Directory: Multiple stylesheets (Responsive_Table.css, dashboard_new1.css, etc.) which provide layout and styling across different views.
- JavaScript Directory: Scripts for autocompletion, sorting, theme management, authentication, and dynamic content (e.g., login.js, sorttable.js, theme.js) which enhance interactivity.
- HTML/PHP Templates: Header, footer, and other common components (head.php, header.php, footer.php) that form the UI framework.

C. Backend Logic / Business Layer:
- Actions Directory: Houses PHP scripts (e.g., mdwiki_api.php, td_api.php, wiki_api.php, etc.) that handle various API calls and business logic. These may communicate with external services (Wikidata API, mdwiki API) and process HTTP requests.
- Tables Directory: Contains files for generating and managing dynamic tables (include.php, sql_tables.php, tables.php) that likely render data in the UI.
- API or SQL Directory: Includes endpoints (data_tab.php, get_lead.php) that manage data retrieval. This may represent an interface between API calls and database interactions if any.
- Coordinator and Auth: Files like coordinator.php and auth.php serve to coordinate backend operations and user authentication.
- Translate and Translate_med: These directories indicate support for further language integration (specifically medwiki), possibly handling translation and data insertion tasks.

D. Integration with External Systems:
- Wikidata/MDwiki APIs: Several files in the actions folder (e.g., mdwiki_api.php, wiki_api.php) integrate with external APIs, indicating that the backend retrieves or posts data to Wikidata and other wiki systems.
- SPARQL Dispatcher and endpoints in the results directory hint at querying a SPARQL endpoint for data aggregation.

E. Testing and Deployment:
- The tests directory includes PHP test scripts (e.g., test_fetch_cat_data.php, test_fetch_cat_data_sparql.php) ensuring that key functionalities are validated.
- CI configurations (as seen with the .github/workflows directory and .coderabbit.yaml) indicate that automated testing/build processes are in place.

##### Relationships and Data Flow
- Users interact with the web application via the three main entry points (results, missing, leaderboard). Their requests are routed to PHP controllers or scripts (present in index.php and associated modules).
- The UI sends HTTP requests that are handled by the backend PHP code, either directly in pages or through “actions” scripts, which then may:
– Query or update tables using the database or SQL files (api_or_sql folder).
– Connect to external APIs (e.g., mdwiki and Wikidata APIs).
– Process SPARQL queries in order to fetch and display categorized or aggregated translation data.
- The backend modules (coordinator.php, auth.php, etc.) mediate between data sources and UI rendering, while external libraries or frameworks (implied by the structure) support tasks like formatting tables and managing sessions.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly separates frontend assets (CSS, JS, HTML templates) from backend business logic (PHP files in actions, API/SQL, Tables, and translate folders).
- Modularization: Specific functionalities are grouped by directories (e.g., results, leaderboard, translate) to ensure the dashboard’s capabilities are modular.
- Integration/Adapters: There are multiple adapter-like scripts that connect to external APIs (Wikidata, mdwiki) and handle SPARQL queries.
- Testing and CI: Presence of tests and CI configuration files suggests an emphasis on reliability and continuous integration.

- Create clearly labeled modules representing:
– User Interface Layer:
- Main pages: “results”, “missing”, “leaderboard”, plus shared UI components.
- Additional navigation and layout components (header, footer).
– Frontend Assets:
- CSS and JS modules as a supporting layer for the UI.
– Backend/Business Logic Layer:
- Controllers or PHP scripts handling authentication (auth.php), coordination (coordinator.php), and main actions (contained in the actions directory).
- API and database integration components (api_or_sql folder, Tables directory).
- Translation modules (translate, translate_med) for extended features.
– External Integrations:
- External API connectors (files like mdwiki_api.php, wiki_api.php).
- SPARQL endpoints (in the results folder) used to query external datasets.
– Testing & Deployment:
- CI/CD pipeline (via GitHub workflows) and test components.
– Frontend vs. backend vs. external systems.
– Static resource layers (CSS/JS) versus dynamic logic (PHP controllers and API integrations).
- Interactions:
– The UI layer forwards requests to the PHP controllers.
– Controllers call action scripts that either execute business logic or retrieve data.
– Data flows from external APIs (Wikidata/MDwiki services or SPARQL endpoints) back through the controllers to be rendered by the UI.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Browser
    UB["User Browser"]:::ui

    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["Results Module"]:::ui
        UI2["Missing Page"]:::ui
        UI3["Leaderboard Module"]:::ui
        UI4["Shared UI Components"]:::ui
    end

    %% Frontend Assets
    subgraph "Frontend Assets"
        FA1["CSS Assets"]:::assets
        FA2["JS Assets"]:::assets
    end

    %% Backend / Business Logic Layer
    subgraph "Backend/Business Logic"
        BE1["Controllers / Auth"]:::backend
        BE2["Actions/API Integration"]:::backend
        BE3["API/SQL Endpoints"]:::backend
        BE4["Table Management"]:::backend
        BE5["Translation Modules"]:::backend
    end

    %% External Services
    ES["Wikidata/mdwiki APIs"]:::external

    %% Testing & Deployment
    subgraph "Testing & Deployment"
        TD1["Testing Suite"]:::testing
        TD2["CI/CD Pipeline"]:::testing
    end

    %% Data Flow Connections
    UB --> UI1
    UB --> UI2
    UB --> UI3
    UB --> UI4

    %% UI Layer loads Frontend Assets (CSS & JS)
    UI1 --- FA1
    UI1 --- FA2
    UI2 --- FA1
    UI2 --- FA2
    UI3 --- FA1
    UI3 --- FA2
    UI4 --- FA1
    UI4 --- FA2

    %% UI Layer interacts with Backend Controllers
    UI1 -->|"triggers"| BE1
    UI2 -->|"triggers"| BE1
    UI3 -->|"triggers"| BE1
    UI4 -->|"provides layout"| BE1

    %% Backend Controllers delegate to other backend components
    BE1 -->|"calls"| BE2
    BE1 -->|"calls"| BE3
    BE1 -->|"renders"| BE4
    BE1 -->|"invokes"| BE5

    %% Backend Actions and API/SQL communicate with External Services
    BE2 -->|"API request"| ES
    BE3 -->|"data query"| ES

    %% Testing and Deployment interactions
    BE1 ---|"tested by"| TD1
    BE2 ---|"tested by"| TD1
    BE3 ---|"tested by"| TD1
    BE4 ---|"tested by"| TD1
    BE5 ---|"tested by"| TD1
    TD2 -->|"deploys"| BE1

    %% Click Events
    click UI1 "https://github.com/mdwiki-td/translation-dashboard/tree/main/results"
    click UI2 "https://github.com/mdwiki-td/translation-dashboard/blob/main/missing.php"
    click UI3 "https://github.com/mdwiki-td/translation-dashboard/tree/main/leaderboard"
    click UI4 "https://github.com/mdwiki-td/translation-dashboard/blob/main/header.php"
    click FA1 "https://github.com/mdwiki-td/translation-dashboard/tree/main/css"
    click FA2 "https://github.com/mdwiki-td/translation-dashboard/tree/main/js"
    click BE1 "https://github.com/mdwiki-td/translation-dashboard/blob/main/coordinator.php"
    click BE2 "https://github.com/mdwiki-td/translation-dashboard/tree/main/actions"
    click BE3 "https://github.com/mdwiki-td/translation-dashboard/tree/main/api_or_sql"
    click BE4 "https://github.com/mdwiki-td/translation-dashboard/tree/main/Tables"
    click BE5 "https://github.com/mdwiki-td/translation-dashboard/tree/main/translate"
    click TD1 "https://github.com/mdwiki-td/translation-dashboard/tree/main/tests"
    click TD2 "https://github.com/mdwiki-td/translation-dashboard/tree/main/.github/workflows"

    %% Styles
    classDef ui fill:#a8d0e6,stroke:#333,stroke-width:2px;
    classDef assets fill:#f6e3b4,stroke:#333,stroke-width:2px;
    classDef backend fill:#c5e1a5,stroke:#333,stroke-width:2px;
    classDef external fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef testing fill:#d1c4e9,stroke:#333,stroke-width:2px;
```
