How mdwiki-td/translation-dashboard works
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.