# luislavena/crystal-vite architecture

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

- Interactive diagram: https://gitdiagram.com/luislavena/crystal-vite
- Repository: https://github.com/luislavena/crystal-vite

## Overview

Based on our analysis of the file tree and the README, this project is an integration library (“shard”) intended to bridge Crystal-based backend applications with Vite.js as the frontend build tool. Its core purpose is to simplify development by proxying front-end requests (and handling HMR in development) and to ease production deployments by using a manifest file for asset loading.

##### Core Components
- Crystal Application (Backend): This is your main application written in Crystal. It utilizes the Vite integration via the provided shard.
- Vite.js Development Server: When in development mode, the Vite server runs separately but is transparently proxied through the Crystal app. It provides services like Hot Module Replacement (HMR).
- Vite Plugin for Crystal: This is a specialized module (found in the “vite-plugin-crystal” directory) that helps configure Vite’s behavior according to the needs of Crystal applications.
- Frontend Assets: These are the files (JavaScript, CSS, etc.) located in the “src/frontend” folder (and its subdirectories, such as “entrypoints” and “styles”) which are built and served either directly by Vite in development or loaded via a manifest in production.
- Proxy Handler within Crystal (“src/vite/proxy_handler.cr”): This module is crucial when proxying the front-end asset requests during development.

##### Out Relationships and Dataflows
- One path goes to “Vite.js Development Server” (via the proxy handler) – representing the development mode data flow and enabling HMR.
- A separate path represents production mode: “Crystal Application” reads the static “manifest.json” (generated by Vite in production) and serves the hashed assets from the “public/build” directory.
- That the “Vite Plugin for Crystal” is used during build and configuration time to align frontend code (from “src/frontend”) with the expected configuration of the Crystal integration.
- That the tag helper methods in the library (script_tag, style_tag, etc. used in views) work to dynamically include the proper asset URLs (either direct URLs to the dev server or hashed filenames from the manifest).

##### Architectural Patterns and Design Principles
- “Convention over Configuration”: Emphasize that the project assumes, by default, specific directories like “src/frontend” and “entrypoints”, reducing custom configuration.
- Transparent Proxying: In development, the responsibility for simplifying the connection between the Crystal application and the Vite server is handled by the “dev_handler”. Ensure that this proxying component is clearly marked.

##### Technologies and Frameworks
- Crystal Programming Language (backend)
- Vite.js (frontend build tool and dev server)
- Node Package Ecosystem (for Vite plugin and package.json scripts)
- Docker/Compose files are present, so optionally note that containerized workflows for demos can be represented as deployment environments, although the primary focus is on the runtime integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Interaction"
        A["Client/Browser"]:::client
    end

    subgraph "Backend Application"
        B["Crystal Application (Backend)"]:::backend
        D["Proxy Handler"]:::backend
        E["Tag Helpers (script_tag, style_tag)"]:::backend
    end

    subgraph "Development Mode"
        C["Vite.js Development Server"]:::external
    end

    subgraph "Production Mode"
        F["Static Assets (manifest.json & public/build)"]:::external
    end

    subgraph "Build Configuration"
        G["Vite Plugin for Crystal"]:::config
        H["Frontend Assets"]:::frontend
    end

    A -->|"asset_request"| B
    B -->|"dev_mode_proxy"| D
    D -->|"proxy_HMR"| C
    B -->|"manifest_resolution"| F
    B -->|"uses_Tag_Helpers"| E
    E -->|"includes_assets"| H
    G -->|"build_configuration"| H
    G -->|"integration_with_backend"| B

    click B "https://github.com/luislavena/crystal-vite/blob/main/demo/src/app.cr"
    click C "https://github.com/luislavena/crystal-vite/blob/main/demo/vite.config.js"
    click G "https://github.com/luislavena/crystal-vite/blob/main/vite-plugin-crystal/src/crystal.js"
    click H "https://github.com/luislavena/crystal-vite/tree/main/demo/src/frontend/"
    click D "https://github.com/luislavena/crystal-vite/blob/main/src/vite/proxy_handler.cr"

    classDef client fill:#f9e79f,stroke:#D35400,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#2471A3,stroke-width:2px;
    classDef external fill:#abebc6,stroke:#28B463,stroke-width:2px;
    classDef config fill:#f7dc6f,stroke:#B7950B,stroke-width:2px;
    classDef frontend fill:#d5f5e3,stroke:#1E8449,stroke-width:2px;
```
