# jharilela/excel-to-json-converter architecture

> Architecture diagram of the GitHub repository jharilela/excel-to-json-converter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jharilela/excel-to-json-converter
- Repository: https://github.com/jharilela/excel-to-json-converter

## Overview

1. **Overall shape**
   - This is a **single-page, client-only React application** built with **Vite**.
   - There is **no backend service** in the repo; all file parsing, conversion, previewing, and downloading happen **in the browser**.

2. **Bootstrap and app shell**
   - `index.html` is the Vite entry page.
   - `src/main.jsx` mounts the React app.
   - `src/App.jsx` is likely the main orchestration layer, with `src/App.css` and `src/index.css` handling the UI styling.

3. **Core user workflow**
   - The user uploads or drag-drops one or more files.
   - The app reads files via browser file APIs, converts them to JSON, shows a preview, and lets the user download the result.
   - The README’s “single JSON vs multiple JSON files” and header options suggest the app supports **conversion settings** that affect how parsed data is shaped and exported.

4. **Conversion pipeline boundary**
   - The key architectural boundary is between:
     - **UI/state management** in React
     - **file parsing / transformation logic** in the browser
   - Excel parsing is handled with **SheetJS (`xlsx`)**; CSV parsing with **PapaParse**.
   - Download generation is client-side, likely using **FileSaver.js** or an equivalent browser download mechanism.

5. **Data flow through the app**
   - Input files come from the local filesystem into the browser.
   - File contents are parsed into in-memory row/object structures.
   - Those structures are normalized into JSON output.
   - The app then produces a downloadable JSON blob/file and a preview for the user.
   - Because processing is local, there is no persistence layer or server-side storage.

6. **Analytics as an optional side channel**
   - `src/hooks/useAnalytics.js` is a separate concern from conversion.
   - The README indicates optional **Google Analytics 4** tracking via `VITE_GOOGLE_ANALYTICS_ID` from `.env`.
   - This hook likely reports UI events such as page views, uploads, conversions, downloads, settings changes, and errors.
   - Architecturally, analytics is an **external telemetry boundary**, not part of the conversion path.

7. **Static/public assets and SEO**
   - The `public/` folder contains `manifest.webmanifest`, `robots.txt`, and `sitemap.xml`.
   - This indicates the app is deployed as a **static site** with SEO-oriented metadata and crawl configuration.
   - The manifest suggests installable/PWA-adjacent browser metadata, but the primary product is still a browser tool, not an app with offline sync or server state.

8. **Development and build tooling**
   - **Vite** is the build/dev server layer.
   - **ESLint** provides code quality checks.
   - `package-lock.json` and `package.json` indicate a standard npm-managed frontend build.
   - Production output is a static bundle in `dist/`, suitable for deployment to static hosting like Vercel.

9. **Testing and sample data**
   - `test_samples/` contains sample CSV/JSON/XLSX files and Node scripts such as `create_sample_excel.cjs` and `test-convert.cjs`.
   - This looks like a lightweight **validation fixture set** for conversion behavior rather than a formal test framework.
   - It provides known inputs/outputs for verifying parser correctness across formats.

10. **Operational and privacy model**
   - The app is explicitly designed for **privacy-first, local processing**.
   - That means the architectural trust boundary is the user’s browser: uploaded files never need to leave the client.
   - The only external dependency implied by the architecture is optional analytics; otherwise the app is self-contained.

11. **What to show in an architecture diagram**
   - A good diagram would show:
     - **Browser UI (React app)** at the center
     - **File input/drag-drop** on the left
     - **Parsing/transformation layer** using SheetJS/PapaParse in the middle
     - **Preview + download output** on the right
     - **Optional Google Analytics** as a side integration
     - **Static hosting/public metadata** as the delivery layer
   - There should be **no server database or API box**, because the app does not use one.

12. **Repo structure summary**
   - `src/` contains the runtime application.
   - `public/` contains static deployment assets.
   - `test_samples/` supports local verification.
   - The rest of the repository is mostly packaging, linting, and licensing metadata around a browser-native conversion tool.

Main entry points: [`src/App.jsx`](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx) (App shell), [`vite.config.js`](https://github.com/jharilela/excel-to-json-converter/blob/main/vite.config.js) (Vite build), [`index.html`](https://github.com/jharilela/excel-to-json-converter/blob/main/index.html) (Entry page), [`src/main.jsx`](https://github.com/jharilela/excel-to-json-converter/blob/main/src/main.jsx) (Mount app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime app"]
  node_index_html["Entry page<br/>Vite entry<br/>[index.html]"]
  node_main_jsx["Mount app<br/>React bootstrap<br/>[main.jsx]"]
  node_app_shell["App shell<br/>React orchestrator<br/>[App.jsx]"]
  node_app_css["App styles<br/>UI stylesheet<br/>[App.css]"]
  node_global_css["Global styles<br/>base stylesheet<br/>[index.css]"]
  node_file_input["File input<br/>browser ingest<br/>[App.jsx]"]
  node_parse_core["Parser core<br/>transform pipeline<br/>[App.jsx]"]
  node_excel_parse["Excel parse<br/>SheetJS adapter"]
  node_csv_parse["CSV parse<br/>PapaParse adapter"]
  node_json_shape["JSON shape<br/>normalizer<br/>[App.jsx]"]
  node_preview_ui["Preview<br/>result view<br/>[App.jsx]"]
  node_download_out["Download<br/>client export<br/>[App.jsx]"]
  node_analytics_hook["Analytics<br/>telemetry hook<br/>[useAnalytics.js]"]
end

subgraph group_delivery["Delivery"]
  node_manifest["Manifest<br/>pwa metadata"]
  node_robots["Robots<br/>crawl policy<br/>[robots.txt]"]
  node_sitemap["Sitemap<br/>seo map<br/>[sitemap.xml]"]
end

subgraph group_tooling["Tooling"]
  node_vite_build["Vite build<br/>bundler<br/>[vite.config.js]"]
  node_lint["ESLint<br/>code quality<br/>[eslint.config.js]"]
  node_samples[("Samples<br/>fixtures")]
  node_package["Package<br/>npm metadata<br/>[package.json]"]
end

node_index_html -->|"loads"| node_main_jsx
node_main_jsx -->|"mounts"| node_app_shell
node_app_shell -->|"starts"| node_file_input
node_file_input -->|"files"| node_parse_core
node_parse_core -->|"xlsx"| node_excel_parse
node_parse_core -->|"csv"| node_csv_parse
node_excel_parse -->|"rows"| node_json_shape
node_csv_parse -->|"rows"| node_json_shape
node_json_shape -->|"renders"| node_preview_ui
node_json_shape -->|"exports"| node_download_out
node_app_shell -->|"shows"| node_preview_ui
node_app_shell -->|"triggers"| node_download_out
node_app_shell -.->|"events"| node_analytics_hook
node_analytics_hook -.->|"reports"| node_app_shell
node_vite_build -->|"serves"| node_index_html
node_vite_build -->|"scripts"| node_package
node_lint -->|"checks"| node_package
node_manifest -->|"ships"| node_vite_build
node_robots -->|"ships"| node_vite_build
node_sitemap -->|"ships"| node_vite_build
node_samples -.->|"verifies"| node_parse_core

click node_index_html "https://github.com/jharilela/excel-to-json-converter/blob/main/index.html"
click node_main_jsx "https://github.com/jharilela/excel-to-json-converter/blob/main/src/main.jsx"
click node_app_shell "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx"
click node_app_css "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.css"
click node_global_css "https://github.com/jharilela/excel-to-json-converter/blob/main/src/index.css"
click node_file_input "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx"
click node_parse_core "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx"
click node_json_shape "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx"
click node_preview_ui "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx"
click node_download_out "https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx"
click node_analytics_hook "https://github.com/jharilela/excel-to-json-converter/blob/main/src/hooks/useAnalytics.js"
click node_manifest "https://github.com/jharilela/excel-to-json-converter/blob/main/public/manifest.webmanifest"
click node_robots "https://github.com/jharilela/excel-to-json-converter/blob/main/public/robots.txt"
click node_sitemap "https://github.com/jharilela/excel-to-json-converter/blob/main/public/sitemap.xml"
click node_vite_build "https://github.com/jharilela/excel-to-json-converter/blob/main/vite.config.js"
click node_lint "https://github.com/jharilela/excel-to-json-converter/blob/main/eslint.config.js"
click node_samples "https://github.com/jharilela/excel-to-json-converter/tree/main/test_samples"
click node_package "https://github.com/jharilela/excel-to-json-converter/blob/main/package.json"

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_index_html,node_main_jsx,node_app_shell,node_app_css,node_global_css,node_file_input,node_parse_core,node_excel_parse,node_csv_parse,node_json_shape,node_preview_ui,node_download_out,node_analytics_hook toneBlue
class node_manifest,node_robots,node_sitemap toneAmber
class node_vite_build,node_lint,node_samples,node_package toneMint
```

## Components

### Runtime app

Client-side React application and browser processing pipeline

- [Entry page](https://github.com/jharilela/excel-to-json-converter/blob/main/index.html): Vite entry · HTML bootstrap for the single-page app · `index.html`
- [Mount app](https://github.com/jharilela/excel-to-json-converter/blob/main/src/main.jsx): React bootstrap · Creates the React root and renders the app · `src/main.jsx`
- [App shell](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx): React orchestrator · Main UI state and workflow coordination · `src/App.jsx`
- [App styles](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.css): UI stylesheet · Component-level visual styling · `src/App.css`
- [Global styles](https://github.com/jharilela/excel-to-json-converter/blob/main/src/index.css): base stylesheet · Application-wide CSS foundation · `src/index.css`
- [File input](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx): browser ingest · Upload and drag-drop entry for local files · `src/App.jsx`
- [Parser core](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx): transform pipeline · Coordinates file reading, normalization, and conversion · `src/App.jsx`
- **Excel parse**: SheetJS adapter · Reads spreadsheet data from XLSX files
- **CSV parse**: PapaParse adapter · Parses CSV rows into structured data
- [JSON shape](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx): normalizer · Maps parsed rows into exportable JSON structures · `src/App.jsx`
- [Preview](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx): result view · Displays converted output before export · `src/App.jsx`
- [Download](https://github.com/jharilela/excel-to-json-converter/blob/main/src/App.jsx): client export · Generates a browser-side JSON download · `src/App.jsx`
- [Analytics](https://github.com/jharilela/excel-to-json-converter/blob/main/src/hooks/useAnalytics.js): telemetry hook · Optional GA4 event reporting from the UI · `src/hooks/useAnalytics.js`

### Delivery

Static site assets and deployment metadata

- [Manifest](https://github.com/jharilela/excel-to-json-converter/blob/main/public/manifest.webmanifest): pwa metadata · Static web app metadata for installability · `public/manifest.webmanifest`
- [Robots](https://github.com/jharilela/excel-to-json-converter/blob/main/public/robots.txt): crawl policy · Search engine crawl directives · `public/robots.txt`
- [Sitemap](https://github.com/jharilela/excel-to-json-converter/blob/main/public/sitemap.xml): seo map · Indexable site URL list · `public/sitemap.xml`

### Tooling

Build, lint, and validation support

- [Vite build](https://github.com/jharilela/excel-to-json-converter/blob/main/vite.config.js): bundler · Development server and production bundle pipeline · `vite.config.js`
- [ESLint](https://github.com/jharilela/excel-to-json-converter/blob/main/eslint.config.js): code quality · Static linting rules and checks · `eslint.config.js`
- [Samples](https://github.com/jharilela/excel-to-json-converter/tree/main/test_samples): fixtures · Reference inputs and outputs for local conversion checks · `test_samples`
- [Package](https://github.com/jharilela/excel-to-json-converter/blob/main/package.json): npm metadata · Dependencies and scripts for the frontend toolchain · `package.json`

## Connections

- Entry page → Mount app: loads · Vite serves the HTML entry, which loads the React bootstrap
- Mount app → App shell: mounts · The bootstrap renders the main application shell
- App shell → File input: starts · UI exposes upload and drag-drop entry points
- File input → Parser core: files · Selected local files are handed into the conversion pipeline
- Parser core → Excel parse: xlsx · Spreadsheet inputs are parsed with SheetJS
- Parser core → CSV parse: csv · Delimited text inputs are parsed with PapaParse
- Excel parse → JSON shape: rows · Parsed spreadsheet data is normalized into exportable records
- CSV parse → JSON shape: rows · Parsed CSV data is normalized into exportable records
- JSON shape → Preview: renders · Converted data is shown in the preview panel
- JSON shape → Download: exports · Normalized JSON is packaged for browser download
- App shell → Preview: shows · The shell coordinates preview state and display
- App shell → Download: triggers · The shell exposes export actions to the user
- App shell → Analytics: events · UI interactions can be reported to optional telemetry
- Analytics → App shell: reports · Telemetry observes page views and conversion interactions
- Vite build → Entry page: serves · Vite uses the HTML entry during dev and build
- Vite build → Package: scripts · Package scripts and dependencies drive the build toolchain
- ESLint → Package: checks · ESLint configuration is part of the npm workflow
- Manifest → Vite build: ships · Static metadata is included in the built site
- Robots → Vite build: ships · Crawl directives are deployed with the static bundle
- Sitemap → Vite build: ships · SEO sitemap is deployed with the static bundle
- Samples → Parser core: verifies · Fixture inputs exercise the conversion pipeline