# nbslabs/difflense architecture

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

- Interactive diagram: https://gitdiagram.com/nbslabs/difflense
- Repository: https://github.com/nbslabs/difflense

## Overview

1. **Project type and hosting**
   - DiffLens is a **static, client-side-only web app** designed to run entirely in the browser.
   - It is structured for **GitHub Pages** deployment: no backend, no database, no server-side rendering, and no analytics/tracking layer.

2. **Top-level page layout**
   - The repository is mostly a small set of **HTML entry points**:
     - `index.html` for the landing/home experience
     - `diff-view.html` for the actual diff viewer
     - `about.html`, `contact.html`, and `contribute.html` for supporting content
   - This makes the site more like a static product site plus a dedicated app page than a traditional SPA.

3. **Core application boundary**
   - The main functional boundary is the **diff viewer page**.
   - That page appears to load the JavaScript modules in `assets/js/` and the shared styling in `assets/css/main.css`.
   - The rest of the HTML pages are informational and do not appear to participate in diff processing.

4. **Diff processing pipeline**
   - The app follows a straightforward flow:
     - user pastes raw `git diff` text or uploads a diff file
     - the diff is parsed in-browser
     - the parsed representation is rendered into a structured diff view
   - The key architectural principle from the README is that **all parsing and rendering happen locally**, so the diff content never leaves the browser.

5. **Parsing subsystem**
   - `assets/js/diff-parser.js` is the likely core of the domain logic.
   - Its role is to convert raw diff text into a structured model of files, hunks, additions, deletions, and metadata that the UI can consume.
   - This is the main “business logic” layer of the repository.

6. **Rendering and interaction subsystem**
   - `assets/js/diff-viewer.js` appears to own the UI rendering of parsed diffs.
   - It likely handles:
     - unified vs side-by-side display modes
     - collapsible file sections
     - file statistics such as additions/deletions
     - navigation between files in multi-file diffs
   - This is the main presentation/controller layer for the app.

7. **GitHub-related integration**
   - `assets/js/github-integration.js` is a separate concern from parsing/rendering and likely handles GitHub-specific input or linking behavior.
   - In architecture terms, this is an **integration boundary** for GitHub-oriented workflows, distinct from the core diff viewer logic.
   - It is not a backend integration in the server sense; it remains browser-side.

8. **State and persistence**
   - The README mentions settings such as expanded/collapsed file state being saved in **browser local storage**.
   - That means the app uses lightweight client-side persistence for preferences, not for the diff data itself.
   - This is an important boundary: **preferences persist locally, diff content is transient**.

9. **Navigation and multi-page structure**
   - The site uses ordinary HTML navigation rather than a heavy client-side router.
   - The home page and auxiliary pages are separate documents, while the diff viewer is the interactive app surface.
   - This is relevant for diagramming because there is no central application server or route controller.

10. **Styling and presentation layer**
   - `assets/css/main.css` is the shared styling layer and likely defines the clean visual system described in the README.
   - The README’s mention of TailwindCSS suggests the design may be utility-driven, but from the file tree the important architectural point is that styling is centralized in a single shared CSS asset.
   - The UI emphasis is on readability, responsive layout, and diff-specific visual cues like line numbers and highlights.

11. **User input boundaries**
   - There are two primary input paths: **paste text** and **file upload**.
   - Both are handled locally, then normalized into the same parsing/rendering pipeline.
   - This keeps the architecture simple: multiple input sources, one internal diff model.

12. **Deployment and operational model**
   - Because the app is static, deployment is effectively **asset hosting** rather than application hosting.
   - `CNAME` indicates a custom domain setup, reinforcing that the production runtime is just browser + static files.
   - No queues, APIs, authentication services, or external compute services are part of the core architecture.

Main entry points: [`diff-view.html`](https://github.com/nbslabs/difflense/blob/main/diff-view.html) (Diff viewer), [`assets/css/main.css`](https://github.com/nbslabs/difflense/blob/main/assets/css/main.css) (Main styles), [`assets/js/diff-viewer.js`](https://github.com/nbslabs/difflense/blob/main/assets/js/diff-viewer.js) (Diff viewer), [`assets/js/diff-parser.js`](https://github.com/nbslabs/difflense/blob/main/assets/js/diff-parser.js) (Diff parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pages["HTML pages"]
  node_index["Home<br/>entry page<br/>[index.html]"]
  node_diff_view["Diff viewer<br/>app page<br/>[diff-view.html]"]
  node_about["About<br/>content page<br/>[about.html]"]
  node_contact["Contact<br/>content page<br/>[contact.html]"]
  node_contribute["Contribute<br/>content page<br/>[contribute.html]"]
end

subgraph group_app["Client app"]
  node_parser{{"Diff parser<br/>[diff-parser.js]"}}
  node_viewer["Diff viewer<br/>renderer/controller<br/>[diff-viewer.js]"]
  node_github_int["GitHub integration"]
  node_styles["Main styles<br/>presentation<br/>[main.css]"]
end

subgraph group_hosting["Hosting"]
  node_static_host["Static host<br/>deployment"]
end

node_index -->|"uses"| node_styles
node_diff_view -->|"uses"| node_styles
node_about -->|"uses"| node_styles
node_contact -->|"uses"| node_styles
node_contribute -->|"uses"| node_styles
node_diff_view -->|"loads"| node_parser
node_diff_view -->|"loads"| node_viewer
node_diff_view -->|"loads"| node_github_int
node_viewer -->|"consumes"| node_parser
node_parser -->|"produces"| node_viewer
node_viewer -->|"styled by"| node_styles
node_diff_view -.->|"served via"| node_static_host

click node_index "https://github.com/nbslabs/difflense/blob/main/index.html"
click node_diff_view "https://github.com/nbslabs/difflense/blob/main/diff-view.html"
click node_about "https://github.com/nbslabs/difflense/blob/main/about.html"
click node_contact "https://github.com/nbslabs/difflense/blob/main/contact.html"
click node_contribute "https://github.com/nbslabs/difflense/blob/main/contribute.html"
click node_parser "https://github.com/nbslabs/difflense/blob/main/assets/js/diff-parser.js"
click node_viewer "https://github.com/nbslabs/difflense/blob/main/assets/js/diff-viewer.js"
click node_github_int "https://github.com/nbslabs/difflense/blob/main/assets/js/github-integration.js"
click node_styles "https://github.com/nbslabs/difflense/blob/main/assets/css/main.css"
click node_static_host "https://github.com/nbslabs/difflense/tree/main/CNAME"

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,node_diff_view,node_about,node_contact,node_contribute toneBlue
class node_parser,node_viewer,node_github_int,node_styles toneAmber
class node_static_host toneMint
```

## Components

### HTML pages

Static entry points and informational pages

- [Home](https://github.com/nbslabs/difflense/blob/main/index.html): entry page · Landing page for the product · `index.html`
- [Diff viewer](https://github.com/nbslabs/difflense/blob/main/diff-view.html): app page · Interactive diff experience in the browser · `diff-view.html`
- [About](https://github.com/nbslabs/difflense/blob/main/about.html): content page · Project overview and background · `about.html`
- [Contact](https://github.com/nbslabs/difflense/blob/main/contact.html): content page · Contact information and outreach · `contact.html`
- [Contribute](https://github.com/nbslabs/difflense/blob/main/contribute.html): content page · Contribution guidance and project participation · `contribute.html`

### Client app

Browser-only diff parsing and viewing

- [Diff parser](https://github.com/nbslabs/difflense/blob/main/assets/js/diff-parser.js): parser · Converts raw git diff text into structured diff data · `assets/js/diff-parser.js`
- [Diff viewer](https://github.com/nbslabs/difflense/blob/main/assets/js/diff-viewer.js): renderer/controller · Renders parsed diffs and manages viewing interactions · `assets/js/diff-viewer.js`
- [GitHub integration](https://github.com/nbslabs/difflense/blob/main/assets/js/github-integration.js): integration · GitHub-oriented browser-side helpers and workflows · `assets/js/github-integration.js`
- [Main styles](https://github.com/nbslabs/difflense/blob/main/assets/css/main.css): presentation · Shared site styling for pages and diff UI · `assets/css/main.css`

### Hosting

Static deployment and domain setup

- [Static host](https://github.com/nbslabs/difflense/tree/main/CNAME): deployment · Browser-hosted static site configuration · `CNAME`

## Connections

- Home → Main styles: uses · Home page uses shared styling
- Diff viewer → Main styles: uses · Viewer page uses shared styling
- About → Main styles: uses · Content page uses shared styling
- Contact → Main styles: uses · Content page uses shared styling
- Contribute → Main styles: uses · Content page uses shared styling
- Diff viewer → Diff parser: loads · Diff viewer loads the parsing logic
- Diff viewer → Diff viewer: loads · Diff viewer loads the rendering logic
- Diff viewer → GitHub integration: loads · Diff viewer loads GitHub-specific helpers
- Diff viewer → Diff parser: consumes · Renderer consumes structured diff data from parser
- Diff parser → Diff viewer: produces · Parser feeds the structured model used by the viewer
- Diff viewer → Main styles: styled by · Viewer presentation is driven by shared CSS
- Diff viewer → Static host: served via · App is deployed as static files on a custom domain