# harlan-zw/unlighthouse architecture

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

- Interactive diagram: https://gitdiagram.com/harlan-zw/unlighthouse
- Repository: https://github.com/harlan-zw/unlighthouse

## Overview

##### Main components

a. CLI Tools and Integrations
- The “packages/cli” and “packages/unlighthouse-ci” directories include command‐line utilities that drive scans from the terminal or as part of CI/CD pipelines.
- They serve as entry points to trigger the scanning process, pass configuration options, and report results back to the user.

b. Core Scanning Engine
- The “packages/core” folder holds the logic for the scanning process. This module is responsible for discovery, processing routes, using Puppeteer clusters, and communicating with Lighthouse to generate reports.

c. API and Server Layer
- The “crux-api” directory and “packages/server” represent the HTTP API endpoints. For example, the “crux-api/server/api/[domain]” structure indicates dynamic API routes serving different domains and history data.
- This layer exposes REST endpoints to trigger scans, fetch historical data/results, and may serve as a backend that the UI connects to.

d. UI Client and Documentation
- The “packages/client” and “docs” directories indicate a separate web application (likely built with Vue, given the .vue files) that serves both a user interface for viewing scan results and comprehensive documentation/demos.
- The docs site provides not only guides and integration instructions but also a modern, interactive UI (with components such as Header, NavBar, ShowcaseCard, etc.) and even 3D graphics (LighthouseThreeD) for visualizations.

e. Additional Integrations & Utilities
- Additional packages (like “packages/unlighthouse”) may provide wrappers, additional configs, or integrations with third-party systems.
- The project also contains test suites (“test” folder, vitest.config.ts) for ensuring quality across these components.

##### Relationships and interactions

- The CLI (or integrations like CI) trigger a scan by invoking core functionality.
- The Core engine (packages/core) orchestrates the scanning by spawning tasks using Puppeteer and processing the Lighthouse results.
- The processed scan data is served via the API/Server component (crux-api and packages/server) so that the UI client can retrieve detailed reports, view historical data (“crux/history.get.ts”), or trigger additional actions.
- The UI Client (packages/client) then consumes the API to render modern dashboards and charts for end-users.
- The Docs site (docs folder) ties it all together by offering explanations, configurations, and demos, and may even re-use some UI components or utilities from the client part.

##### Architectural patterns & design principles

- The project is organized in a modular, component-based manner. Separation of concerns is evident: CLI handling, core processing, API endpoint serving, and client-side rendering are all in distinct packages.
- A layered architecture is used where the user interaction layer (CLI/Client) is separate from the application logic (Core) and data/service interface (API/Server).

##### Relevant technologies, frameworks, and libraries

- Node.js is the underlying runtime (note Node>=18.x requirement).
- Google Lighthouse drives the auditing, while Puppeteer is used to manage headless browser interactions.
- The frontend likely leverages Vue.js and build tools such as Vite and Windi CSS (as seen in the “packages/client” configurations).
- Dynamic API routing is seen in the “crux-api/server/api/[domain]” folder structure, and server configuration files (nitro.config.ts) indicate usage of modern Node server frameworks.
- Integration tests using Vitest (vitest.config.ts) show an emphasis on robust testing.

– Clear labels for each key component or service (e.g., “CLI Tool (packages/cli)”, “Core Engine (packages/core)”, “API Server (crux-api, packages/server)”, “Web Client (packages/client)”, “Docs Site (docs)”).
- From CLI → Core Engine (initiating scans).
- From Core Engine → API Server (uploading/serving scan results).
- From API Server → Client UI (for rendering results).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Entry Layer
    subgraph "Entry Layer"
        A["CLI Tool (packages/cli)"]:::cli
        B["CI Integrations (packages/unlighthouse-ci)"]:::cli
    end

    %% Processing Layer
    subgraph "Processing Layer"
        C["Core Engine (packages/core)"]:::core
    end

    %% API / Backend
    subgraph "API / Backend"
        D["Crux API (crux-api)"]:::backend
        E["Server (packages/server)"]:::backend
        D -->|"DataProcessing"| E
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        F["Web Client (packages/client)"]:::frontend
        G["Docs Site (docs)"]:::frontend
    end

    %% Connections between layers
    A -->|"TriggerScan"| C
    B -->|"TriggerScan"| C
    C -->|"UploadResults"| D
    E -->|"HTTP_Response"| F
    E -->|"HTTP_Response"| G
    E -->|"Status/Error"| A

    %% Click Events
    click A "https://github.com/harlan-zw/unlighthouse/tree/main/packages/cli"
    click B "https://github.com/harlan-zw/unlighthouse/tree/main/packages/unlighthouse-ci"
    click C "https://github.com/harlan-zw/unlighthouse/tree/main/packages/core"
    click D "https://github.com/harlan-zw/unlighthouse/tree/main/crux-api"
    click E "https://github.com/harlan-zw/unlighthouse/tree/main/packages/server"
    click F "https://github.com/harlan-zw/unlighthouse/tree/main/packages/client"
    click G "https://github.com/harlan-zw/unlighthouse/tree/main/docs"

    %% Styles
    classDef cli fill:#fff4c2,stroke:#d79a00,stroke-width:2px;
    classDef core fill:#d7fcd4,stroke:#2ca02c,stroke-width:2px;
    classDef backend fill:#caf0f8,stroke:#0077b6,stroke-width:2px;
    classDef frontend fill:#f4c2c2,stroke:#d00000,stroke-width:2px;
```
