# naiemofficial/cards-for-github architecture

> Architecture diagram of the GitHub repository naiemofficial/cards-for-github, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naiemofficial/cards-for-github
- Repository: https://github.com/naiemofficial/cards-for-github

## Overview

1. **Project type and runtime**
   - This is a **WordPress plugin** for rendering GitHub “cards” inside posts/pages.
   - The main runtime is WordPress/PHP, with a frontend JavaScript path for client-side loading and a plugin admin UI for configuration.

2. **Plugin entry and bootstrap**
   - `cards-for-github.php`, `github-card.php`, and `functions.php` act as the core bootstrap/utility layer.
   - These files are the central wiring point for WordPress hooks, shortcode registration, asset loading, and shared helper logic.

3. **Presentation layer: shortcode-driven rendering**
   - The `shortcodes/` directory is the main rendering boundary.
   - Separate shortcode handlers exist for different GitHub entities: `repo`, `user`, and `linguist`, plus `template.php` for shared markup.
   - This suggests the plugin can render multiple card variants from the same underlying data model.

4. **Data access layer: GitHub API wrappers**
   - The `api/` directory contains dedicated fetchers for `repo`, `user`, and `linguist`.
   - This is the boundary between plugin logic and the external **GitHub API**.
   - The repo data likely powers stars/forks/issues/description, while linguist data supports language breakdown and colors.

5. **Caching layer**
   - The `cache/` directory contains parallel cache handlers for `repo`, `user`, and `linguist`, plus shared cache helpers.
   - Caching is a distinct subsystem to reduce GitHub API calls and improve page performance.
   - The architecture implies requests flow through cache first, then fall back to GitHub API when needed.

6. **Frontend rendering path**
   - `assets/js/github-card.js` and `assets/css/styles.css` provide the public-facing card behavior and styling.
   - The README indicates cards can load via **JavaScript** as well as PHP, so the frontend path is not just static output; it can hydrate or fetch data dynamically.
   - Font Awesome and bundled fonts are used for iconography and visual polish.

7. **Admin/configuration path**
   - The `admin/` directory contains the WordPress admin page, its scripts, styles, localization, and UI assets.
   - `admin/admin-page.php` is the main settings screen, while `admin/assets/js/github-card-admin.js` and related CSS support the configuration experience.
   - This is where users choose loading mode, preloader behavior, auto-scaling, color options, language bar toggles, and cache settings.

8. **Settings and shared frontend configuration**
   - `includes/settings-input.php`, `includes/settings-frontend.php`, and `includes/settings-scripts-styles.php` separate configuration concerns from rendering logic.
   - These files likely bridge admin-stored options into frontend behavior, ensuring the same settings affect both PHP-rendered and JS-rendered cards.

9. **AJAX / dynamic interaction boundary**
   - `includes/ajax.php` is the likely WordPress AJAX bridge for browser-driven requests.
   - This provides a second delivery path besides direct PHP rendering: the frontend can request card data asynchronously, which is important for the JavaScript load mode described in the README.

10. **Localization and text domain support**
   - `localize.php` and `admin/localize.php` indicate the plugin is prepared for translated UI strings.
   - This is mainly a presentation/admin concern, but it also shows the plugin has a formal settings and UI surface, not just a shortcode renderer.

11. **Static assets and packaging**
   - `assets/` and `libs/` contain the public CSS/JS, icon libraries, fonts, and supporting files.
   - `vendor/`, `composer.json`, and `composer.lock` indicate Composer-managed dependencies, though the architecture is still centered on WordPress plugin conventions rather than a framework app.

12. **Operational flow for an end-user card**
   - A WordPress content editor inserts a shortcode.
   - The shortcode handler selects the requested entity type and card template.
   - Data is resolved from cache, or fetched from the GitHub API through the API layer.
   - The result is rendered as HTML, or delivered to frontend JavaScript for dynamic rendering, with assets and settings shaping the final card appearance.

13. **Key architectural boundaries to show in a diagram**
   - WordPress content/admin UI vs plugin internals.
   - Rendering path vs API/data-fetch path.
   - Cache layer vs live GitHub API calls.
   - Server-side PHP rendering vs client-side JavaScript rendering.
   - Shared settings/configuration feeding both admin and frontend behavior.

14. **What matters most for an architecture diagram**
   - The plugin is best modeled as a **WordPress extension with three core subsystems**: shortcode rendering, GitHub data retrieval/caching, and admin/settings management.
   - External dependency is primarily the **GitHub API**; everything else is internal plugin infrastructure around WordPress.

Main entry points: [`github-card.php`](https://github.com/naiemofficial/cards-for-github/blob/main/github-card.php) (github-card.php), [`assets/js/github-card.js`](https://github.com/naiemofficial/cards-for-github/blob/main/assets/js/github-card.js) (Card JS), [`shortcodes/repo.php`](https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/repo.php) (Repo card), [`shortcodes/user.php`](https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/user.php) (User card)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wp["WordPress"]
  node_cards_for_github_php["cards-for-github.php<br/>plugin bootstrap"]
  node_github_card_php["github-card.php<br/>plugin core<br/>[github-card.php]"]
  node_admin_page_php["Admin page<br/>settings screen<br/>[admin-page.php]"]
  node_ajax_php["AJAX bridge<br/>dynamic endpoint<br/>[ajax.php]"]
end

subgraph group_render["Rendering"]
  node_shortcodes_repo_php["Repo card<br/>shortcode handler<br/>[repo.php]"]
  node_shortcodes_user_php["User card<br/>shortcode handler<br/>[user.php]"]
  node_shortcodes_linguist_php["Linguist card<br/>shortcode handler<br/>[linguist.php]"]
  node_shortcodes_template_php["Template<br/>[template.php]"]
end

subgraph group_data["Data"]
  node_api_repo_php["Repo API<br/>GitHub fetcher<br/>[repo.php]"]
  node_api_user_php["User API<br/>GitHub fetcher<br/>[user.php]"]
  node_api_linguist_php["Linguist API<br/>GitHub fetcher<br/>[linguist.php]"]
  node_cache_functions_php["Cache helpers<br/>cache utilities<br/>[functions.php]"]
  node_cache_repo_php["Repo cache<br/>cache layer<br/>[repo.php]"]
  node_cache_user_php["User cache<br/>cache layer<br/>[user.php]"]
  node_cache_linguist_php["Linguist cache<br/>cache layer<br/>[linguist.php]"]
end

subgraph group_ui["UI Assets"]
  node_admin_localize_php["Admin i18n<br/>i18n bootstrap<br/>[localize.php]"]
  node_github_card_js["Card JS<br/>frontend script<br/>[github-card.js]"]
  node_github_card_admin_js["Admin JS<br/>admin script"]
  node_styles_css["Styles<br/>[styles.css]"]
  node_admin_styles_css["Admin styles<br/>[styles.css]"]
end

subgraph group_shared["Shared"]
  node_functions_php["functions.php<br/>helpers<br/>[functions.php]"]
  node_settings_input_php["Settings input<br/>settings model<br/>[settings-input.php]"]
  node_settings_frontend_php["Frontend settings<br/>settings bridge"]
  node_settings_scripts_styles_php["Asset settings<br/>asset bridge"]
  node_localize_php["Localization<br/>i18n bootstrap<br/>[localize.php]"]
end

node_github_api[("GitHub API<br/>external service")]

node_cards_for_github_php -->|"bootstraps"| node_github_card_php
node_github_card_php -->|"uses"| node_functions_php
node_github_card_php -->|"registers"| node_shortcodes_repo_php
node_github_card_php -->|"registers"| node_shortcodes_user_php
node_github_card_php -->|"registers"| node_shortcodes_linguist_php
node_shortcodes_repo_php -->|"renders"| node_shortcodes_template_php
node_shortcodes_user_php -->|"renders"| node_shortcodes_template_php
node_shortcodes_linguist_php -->|"renders"| node_shortcodes_template_php
node_shortcodes_repo_php -->|"reads"| node_cache_repo_php
node_shortcodes_user_php -->|"reads"| node_cache_user_php
node_shortcodes_linguist_php -->|"reads"| node_cache_linguist_php
node_cache_repo_php -->|"falls back to"| node_api_repo_php
node_cache_user_php -->|"falls back to"| node_api_user_php
node_cache_linguist_php -->|"falls back to"| node_api_linguist_php
node_api_repo_php -->|"calls"| node_github_api
node_api_user_php -->|"calls"| node_github_api
node_api_linguist_php -->|"calls"| node_github_api
node_admin_page_php -->|"uses"| node_settings_input_php
node_settings_input_php -->|"feeds"| node_settings_frontend_php
node_settings_frontend_php -->|"feeds"| node_settings_scripts_styles_php
node_admin_page_php -->|"uses"| node_admin_localize_php
node_github_card_js -->|"requests"| node_ajax_php
node_github_card_js -->|"uses"| node_settings_frontend_php
node_github_card_js -->|"pairs with"| node_styles_css
node_github_card_admin_js -->|"drives"| node_admin_page_php
node_github_card_admin_js -->|"pairs with"| node_admin_styles_css
node_localize_php -->|"localizes"| node_github_card_js
node_admin_localize_php -->|"localizes"| node_github_card_admin_js

click node_cards_for_github_php "https://github.com/naiemofficial/cards-for-github/blob/main/cards-for-github.php"
click node_github_card_php "https://github.com/naiemofficial/cards-for-github/blob/main/github-card.php"
click node_functions_php "https://github.com/naiemofficial/cards-for-github/blob/main/functions.php"
click node_shortcodes_repo_php "https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/repo.php"
click node_shortcodes_user_php "https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/user.php"
click node_shortcodes_linguist_php "https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/linguist.php"
click node_shortcodes_template_php "https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/template.php"
click node_api_repo_php "https://github.com/naiemofficial/cards-for-github/blob/main/api/repo.php"
click node_api_user_php "https://github.com/naiemofficial/cards-for-github/blob/main/api/user.php"
click node_api_linguist_php "https://github.com/naiemofficial/cards-for-github/blob/main/api/linguist.php"
click node_cache_functions_php "https://github.com/naiemofficial/cards-for-github/blob/main/cache/functions.php"
click node_cache_repo_php "https://github.com/naiemofficial/cards-for-github/blob/main/cache/repo.php"
click node_cache_user_php "https://github.com/naiemofficial/cards-for-github/blob/main/cache/user.php"
click node_cache_linguist_php "https://github.com/naiemofficial/cards-for-github/blob/main/cache/linguist.php"
click node_admin_page_php "https://github.com/naiemofficial/cards-for-github/blob/main/admin/admin-page.php"
click node_settings_input_php "https://github.com/naiemofficial/cards-for-github/blob/main/includes/settings-input.php"
click node_settings_frontend_php "https://github.com/naiemofficial/cards-for-github/blob/main/includes/settings-frontend.php"
click node_settings_scripts_styles_php "https://github.com/naiemofficial/cards-for-github/blob/main/includes/settings-scripts-styles.php"
click node_ajax_php "https://github.com/naiemofficial/cards-for-github/blob/main/includes/ajax.php"
click node_localize_php "https://github.com/naiemofficial/cards-for-github/blob/main/localize.php"
click node_admin_localize_php "https://github.com/naiemofficial/cards-for-github/blob/main/admin/localize.php"
click node_github_card_js "https://github.com/naiemofficial/cards-for-github/blob/main/assets/js/github-card.js"
click node_github_card_admin_js "https://github.com/naiemofficial/cards-for-github/blob/main/admin/assets/js/github-card-admin.js"
click node_styles_css "https://github.com/naiemofficial/cards-for-github/blob/main/assets/css/styles.css"
click node_admin_styles_css "https://github.com/naiemofficial/cards-for-github/blob/main/admin/assets/css/styles.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cards_for_github_php,node_github_card_php,node_admin_page_php,node_ajax_php toneBlue
class node_shortcodes_repo_php,node_shortcodes_user_php,node_shortcodes_linguist_php,node_shortcodes_template_php toneAmber
class node_api_repo_php,node_api_user_php,node_api_linguist_php,node_cache_functions_php,node_cache_repo_php,node_cache_user_php,node_cache_linguist_php toneMint
class node_admin_localize_php,node_github_card_js,node_github_card_admin_js,node_styles_css,node_admin_styles_css toneRose
class node_functions_php,node_settings_input_php,node_settings_frontend_php,node_settings_scripts_styles_php,node_localize_php toneIndigo
class node_github_api toneNeutral
```

## Components

### WordPress

Plugin entry points, hooks, shortcode registration, admin integration, and AJAX bridge.

- [cards-for-github.php](https://github.com/naiemofficial/cards-for-github/blob/main/cards-for-github.php): plugin bootstrap · Primary plugin entry file that wires WordPress hooks and initializes the plugin. · `cards-for-github.php`
- [github-card.php](https://github.com/naiemofficial/cards-for-github/blob/main/github-card.php): plugin core · Core plugin wiring and shared runtime behavior. · `github-card.php`
- [Admin page](https://github.com/naiemofficial/cards-for-github/blob/main/admin/admin-page.php): settings screen · WordPress admin settings page for configuring the plugin. · `admin/admin-page.php`
- [AJAX bridge](https://github.com/naiemofficial/cards-for-github/blob/main/includes/ajax.php): dynamic endpoint · WordPress AJAX endpoint for asynchronous card loading. · `includes/ajax.php`

### Rendering

Shortcode handlers and template logic for public card output.

- [Repo card](https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/repo.php): shortcode handler · Renders repository cards from shortcode input. · `shortcodes/repo.php`
- [User card](https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/user.php): shortcode handler · Renders user cards from shortcode input. · `shortcodes/user.php`
- [Linguist card](https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/linguist.php): shortcode handler · Renders language breakdown cards from shortcode input. · `shortcodes/linguist.php`
- [Template](https://github.com/naiemofficial/cards-for-github/blob/main/shortcodes/template.php): markup template · Shared card markup and presentation template. · `shortcodes/template.php`

### Data

GitHub fetchers and cache layers for card content.

- [Repo API](https://github.com/naiemofficial/cards-for-github/blob/main/api/repo.php): GitHub fetcher · Fetches repository data from GitHub. · `api/repo.php`
- [User API](https://github.com/naiemofficial/cards-for-github/blob/main/api/user.php): GitHub fetcher · Fetches user profile data from GitHub. · `api/user.php`
- [Linguist API](https://github.com/naiemofficial/cards-for-github/blob/main/api/linguist.php): GitHub fetcher · Fetches language metadata used by linguist cards. · `api/linguist.php`
- [Cache helpers](https://github.com/naiemofficial/cards-for-github/blob/main/cache/functions.php): cache utilities · Shared caching helpers and cache behavior. · `cache/functions.php`
- [Repo cache](https://github.com/naiemofficial/cards-for-github/blob/main/cache/repo.php): cache layer · Caches repository responses to reduce API calls. · `cache/repo.php`
- [User cache](https://github.com/naiemofficial/cards-for-github/blob/main/cache/user.php): cache layer · Caches user responses to reduce API calls. · `cache/user.php`
- [Linguist cache](https://github.com/naiemofficial/cards-for-github/blob/main/cache/linguist.php): cache layer · Caches linguist responses to reduce API calls. · `cache/linguist.php`

### UI Assets

Frontend and admin assets used to present and configure cards.

- [Admin i18n](https://github.com/naiemofficial/cards-for-github/blob/main/admin/localize.php): i18n bootstrap · Registers translated strings for the admin UI. · `admin/localize.php`
- [Card JS](https://github.com/naiemofficial/cards-for-github/blob/main/assets/js/github-card.js): frontend script · Public-facing JavaScript path for loading and rendering cards. · `assets/js/github-card.js`
- [Admin JS](https://github.com/naiemofficial/cards-for-github/blob/main/admin/assets/js/github-card-admin.js): admin script · JavaScript for the plugin configuration interface. · `admin/assets/js/github-card-admin.js`
- [Styles](https://github.com/naiemofficial/cards-for-github/blob/main/assets/css/styles.css): frontend styles · Public card styling for rendered output. · `assets/css/styles.css`
- [Admin styles](https://github.com/naiemofficial/cards-for-github/blob/main/admin/assets/css/styles.css): admin styles · Styling for the WordPress admin configuration UI. · `admin/assets/css/styles.css`

### Shared

Common settings, localization, and bootstrap helpers.

- [functions.php](https://github.com/naiemofficial/cards-for-github/blob/main/functions.php): helpers · Shared utility functions used across the plugin. · `functions.php`
- [Settings input](https://github.com/naiemofficial/cards-for-github/blob/main/includes/settings-input.php): settings model · Defines and processes plugin settings inputs. · `includes/settings-input.php`
- [Frontend settings](https://github.com/naiemofficial/cards-for-github/blob/main/includes/settings-frontend.php): settings bridge · Projects stored settings into frontend behavior. · `includes/settings-frontend.php`
- [Asset settings](https://github.com/naiemofficial/cards-for-github/blob/main/includes/settings-scripts-styles.php): asset bridge · Controls how scripts and styles are registered and loaded. · `includes/settings-scripts-styles.php`
- [Localization](https://github.com/naiemofficial/cards-for-github/blob/main/localize.php): i18n bootstrap · Registers shared translatable strings for the plugin. · `localize.php`

### Other components

- **GitHub API**: external service · Remote source for repository, user, and language data.

## Connections

- cards-for-github.php → github-card.php: bootstraps · Main entry initializes the plugin runtime.
- github-card.php → functions.php: uses · Shares common helper logic.
- github-card.php → Repo card: registers · Connects repo shortcode handling into WordPress.
- github-card.php → User card: registers · Connects user shortcode handling into WordPress.
- github-card.php → Linguist card: registers · Connects linguist shortcode handling into WordPress.
- Repo card → Template: renders · Uses shared template markup.
- User card → Template: renders · Uses shared template markup.
- Linguist card → Template: renders · Uses shared template markup.
- Repo card → Repo cache: reads · Checks repository cache before fetching live data.
- User card → User cache: reads · Checks user cache before fetching live data.
- Linguist card → Linguist cache: reads · Checks linguist cache before fetching live data.
- Repo cache → Repo API: falls back to · Misses route to live repository fetches.
- User cache → User API: falls back to · Misses route to live user fetches.
- Linguist cache → Linguist API: falls back to · Misses route to live linguist fetches.
- Repo API → GitHub API: calls · Repository fetcher talks to GitHub.
- User API → GitHub API: calls · User fetcher talks to GitHub.
- Linguist API → GitHub API: calls · Linguist fetcher talks to GitHub.
- Admin page → Settings input: uses · Admin UI is driven by plugin settings definitions.
- Settings input → Frontend settings: feeds · Stored settings are projected into frontend behavior.
- Frontend settings → Asset settings: feeds · Frontend settings influence asset loading.
- Admin page → Admin i18n: uses · Admin screen receives translated strings.
- Card JS → AJAX bridge: requests · Client-side loading can request card data asynchronously.
- Card JS → Frontend settings: uses · JavaScript rendering consumes frontend settings.
- Card JS → Styles: pairs with · Script relies on public card styling.
- Admin JS → Admin page: drives · Admin JavaScript powers the settings interface.
- Admin JS → Admin styles: pairs with · Admin script relies on admin styling.
- Localization → Card JS: localizes · Provides translatable strings to the public script.
- Admin i18n → Admin JS: localizes · Provides translatable strings to the admin script.