# julian-mostbauer/linuxricingguide architecture

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

- Interactive diagram: https://gitdiagram.com/julian-mostbauer/linuxricingguide
- Repository: https://github.com/julian-mostbauer/linuxricingguide

## Overview

##### Project type and purpose
- This is a full‑stack, single‑page web application (“Linux Ricing Guide”) built with Nuxt.js (Vue) on the frontend and a minimal built‑in API on the backend.
- Purpose: serve an interactive guide to “ricing” (customizing) Linux distributions, with searchable content pulled from local JSON files.

##### File structure
- Top level:
- .github/workflows – CI pipeline (build-frontend.yml)
- backend – placeholder Node project (package.json)
- linux-ricing-guide – core Nuxt.js project (assets, components, layouts, pages, public, server/api, server-data, tests)
- serve.py – simple Python HTTP server for local demo or static‑site serving
- Key patterns:
- MVCish separation in Nuxt: pages → layouts → components
- server/api routes for backend logic (search.ts)
- server-data JSON files as the data store
- GitHub Actions to install, build, and potentially deploy the frontend

##### README for additional insights
- Confirms single‑app purpose (“Guide to ricing linux systems”)
- No external hosting or managed database – all data lives locally

##### Components
a. Main components:
- Client (Browser)
- Nuxt.js server (Node.js)
- API Layer (server/api/search.ts)
- Data Store (JSON files under server-data/histories)
- Static Asset Server (public/ and built assets)
- CI/CD pipeline (GitHub Actions)
- Local dev/demo server (serve.py)
b. Relationships & interactions:
1. Browser → HTTP requests for pages/routes → Nuxt.js server
2. Nuxt.js SSR renders pages using components and may fetch JSON data
3. Client‑side search calls `/api/search` → search.ts → utilities → returns filtered JSON
4. Browser fetches static assets (JS bundles, CSS, images) from public/ or built output
5. CI/CD (GitHub Actions) automatically runs on commits to build/test the frontend
6. Optionally, serve.py can be used to serve the built directory for demo/local hosting
c. Architectural patterns & design principles:
- Server-Side Rendering (SSR) + Static Generation (Nuxt)
- File-based routing and API endpoints
- Utility modules (caseUtils, dateUtils, iconUtils) for separation of concerns
- JSON‑based data store avoids external DB complexity
d. Key technologies/frameworks:
- Nuxt.js (Vue 3) for SSR and SPA features
- TypeScript for type safety in server/api and utilities
- Node.js / npm for build and runtime
- Python (serve.py) for lightweight static hosting
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime components
    Browser["Browser"]:::runtime
    Serve["serve.py"]:::runtime

    %% Infrastructure
    CI["GitHub Actions"]:::infra

    %% Repo boundary
    subgraph "linux-ricing-guide (repo)" 
        style linux-ricing-guide stroke-dasharray: 5 5

        subgraph "Frontend (Nuxt.js Server)"
            Nuxt["Nuxt.js Server"]:::runtime
            Config["nuxt.config.ts"]:::runtime
            Pages["Pages"]:::frontend
            Layouts["default.vue"]:::frontend
            Components["Components"]:::frontend
        end

        subgraph "Utilities"
            CaseUtil["caseUtils.ts"]:::utility
            DateUtil["dateUtils.ts"]:::utility
            IconUtil["iconUtils.ts"]:::utility
            SiteSearch["siteWideSearch.ts"]:::utility
        end

        subgraph "API Layer"
            API["/api/search"]:::api
        end

        subgraph "Data Store"
            JSONStore[(JSON Histories)]:::data
        end

        StaticCode["public"]:::static
    end

    %% Client interactions
    Browser -->|"HTTP GET pages"| Nuxt
    Browser -->|"Fetch JS/CSS/images"| StaticCode
    Browser -->|"HTTP GET /api/search"| API

    %% Server internal flows
    Nuxt -->|"Load config"| Config
    Nuxt -->|"Render pages"| Pages
    Pages --> Layouts
    Layouts --> Components
    Nuxt --> CaseUtil
    Nuxt --> DateUtil
    Nuxt --> IconUtil
    Nuxt --> SiteSearch
    Nuxt -->|"SSR fetch JSON"| JSONStore
    API -->|"Fetch JSON data"| JSONStore

    %% CI/CD and serving
    CI -->|"build/test"| Nuxt
    CI -->|"artifact"| StaticCode
    Serve -->|"Serve static site"| StaticCode

    %% Click events
    click Config "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/nuxt.config.ts"
    click Pages "https://github.com/julian-mostbauer/linuxricingguide/tree/master/linux-ricing-guide/pages"
    click Layouts "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/layouts/default.vue"
    click Components "https://github.com/julian-mostbauer/linuxricingguide/tree/master/linux-ricing-guide/components"
    click CaseUtil "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/assets/utils/caseUtils.ts"
    click DateUtil "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/assets/utils/dateUtils.ts"
    click IconUtil "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/assets/utils/iconUtils.ts"
    click SiteSearch "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/assets/utils/siteWideSearch.ts"
    click API "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/server/api/search.ts"
    click JSONStore "https://github.com/julian-mostbauer/linuxricingguide/blob/master/linux-ricing-guide/server-data/histories/*.json"
    click StaticCode "https://github.com/julian-mostbauer/linuxricingguide/tree/master/linux-ricing-guide/public"
    click CI "https://github.com/julian-mostbauer/linuxricingguide/blob/master/.github/workflows/build-frontend.yml"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef infra fill:#FFE8A0,stroke:#333,stroke-width:1px
    classDef frontend fill:#E8F0FF,stroke:#333,stroke-width:1px
    classDef utility fill:#F0E8FF,stroke:#333,stroke-width:1px
    classDef api fill:#FFD8D8,stroke:#333,stroke-width:1px
    classDef data fill:#D8FFD8,stroke:#333,stroke-width:1px
    classDef static fill:#F0FFF0,stroke:#333,stroke-width:1px
```
