# waleedhkhan/blog architecture

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

- Interactive diagram: https://gitdiagram.com/waleedhkhan/blog
- Repository: https://github.com/waleedhkhan/blog

## Overview

##### Main Components
- Frontend Website – Represent the Astro-based static site that renders pages using MDX content, incorporates layouts and styling (with Tailwind CSS), and uses components across frameworks (React, Vue, and Astro components). The “src” directory (with its subdirectories for components, layouts, styles, and pages) is the heart of this part.
- Bookmarks Management CLI – Include a separate block for the Node.js CLI tool (located within the “scripts” folder and invoked from the command line). This tool interacts with the bookmarks JSON file (found in “src/data/bookmarks.json”) by adding, categorizing, and updating bookmark records.

##### Relationships & Interactions
- CLI Tool → Bookmarks Data: Show that the CLI tool (bookmarks-cli.js) updates the bookmarks JSON file, which is then used by the website to display categorized bookmarks.
- Plugin and Transformation Pipelines: Demonstrate how custom remark plugins (in “src/plugins/remark”) transform MDX content during the build process.

##### Architectural Patterns & Design Principles
- Islands Architecture: Clearly separate static content rendering from interactive islands (React/Vue components) that hydrate on the client side.
- Separation of Concerns: Segregate the API endpoints, content, layout components, and utility libraries into distinct blocks.
- Build-Time vs. Run-Time: Emphasize that much of the site is statically generated (for performance), while dynamic functionalities like theme switching and music integration are handled at runtime.

##### Technologies, Frameworks, and Libraries
- Astro (static site generator)
- React & Vue (UI interactivity)
- Tailwind CSS (styling and responsive design)
- MDX with custom plugins (content processing)
- Node.js (CLI tool for bookmarks management)
- Last.fm API (music integration)
- Sharp, Fontaine, and other performance optimization tools

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Web Client)"
        FWebsite["Frontend Website (Astro)"]:::frontend
        Styling["Tailwind CSS Styling"]:::frontend
        MDXContent["MDX Content Repository"]:::content
        RemarkPlugins["Remark Plugins"]:::content
        AstroBuild["Astro Build Process"]:::build
        StaticAssets["Public Static Assets"]:::build
        InteractiveModules["React/Vue Interactive Modules"]:::interactive
        BookmarksDisplay["Bookmarks Display Component"]:::interactive
    end

    subgraph "Backend / CLI Tools"
        APIEndpoints["API Endpoints"]:::backend
        RecentlyPlayed["Recently Played Endpoint"]:::backend
        LastfmAPIEndpoint["Last.fm Data Endpoint"]:::backend
        CLITool["Bookmarks CLI Tool"]:::cli
        BookmarksJSON["Bookmarks JSON"]:::cli
    end

    ExternalLastfm["External Last.fm API"]:::external

    %% Frontend Content Processing Flow
    MDXContent -->|"process"| AstroBuild
    RemarkPlugins -->|"transform"| AstroBuild
    AstroBuild -->|"generate"| StaticAssets
    FWebsite -->|"serves"| StaticAssets
    FWebsite --> Styling

    %% Interactive Elements & API Communication
    InteractiveModules <-->|"data_fetch"| APIEndpoints
    InteractiveModules -->|"render_bookmarks"| BookmarksDisplay

    %% CLI and Bookmark Data Flow
    CLITool -->|"update"| BookmarksJSON
    BookmarksJSON -->|"load"| BookmarksDisplay

    %% API Endpoints and External Integration
    APIEndpoints --> RecentlyPlayed
    APIEndpoints --> LastfmAPIEndpoint
    APIEndpoints -->|"fetch"| ExternalLastfm

    %% Click Events
    click FWebsite "https://github.com/waleedhkhan/blog/tree/main/src"
    click Styling "https://github.com/waleedhkhan/blog/tree/main/src/assets/styles"
    click Styling "https://github.com/waleedhkhan/blog/tree/main/src/styles"
    click MDXContent "https://github.com/waleedhkhan/blog/tree/main/content"
    click MDXContent "https://github.com/waleedhkhan/blog/tree/main/src/content"
    click RemarkPlugins "https://github.com/waleedhkhan/blog/tree/main/src/plugins/remark"
    click RecentlyPlayed "https://github.com/waleedhkhan/blog/blob/main/functions/api/recently-played.js"
    click LastfmAPIEndpoint "https://github.com/waleedhkhan/blog/blob/main/src/pages/api/lastfm/recent.js"
    click CLITool "https://github.com/waleedhkhan/blog/blob/main/scripts/bookmarks-cli.js"
    click BookmarksJSON "https://github.com/waleedhkhan/blog/blob/main/src/data/bookmarks.json"
    click ExternalLastfm "https://github.com/waleedhkhan/blog/blob/main/src/lib/lastfm.js"

    %% Styles
    classDef frontend fill:#ccf,stroke:#036,stroke-width:2px;
    classDef content fill:#eee,stroke:#999,stroke-width:2px;
    classDef build fill:#fcf,stroke:#933,stroke-width:2px;
    classDef interactive fill:#cfc,stroke:#393,stroke-width:2px;
    classDef backend fill:#fdd,stroke:#933,stroke-width:2px;
    classDef cli fill:#f9c,stroke:#960,stroke-width:2px;
    classDef external fill:#ffd,stroke:#aa0,stroke-width:2px;
```
