# loggerhead/json4u architecture

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

- Interactive diagram: https://gitdiagram.com/loggerhead/json4u
- Repository: https://github.com/loggerhead/json4u

## Overview

This project – “JSON For You” – is a full-stack web application built with Next.js, React, and several modern libraries (such as Tailwind CSS, Zustand, and Zod) that provides a rich JSON visualization and processing tool. The purpose of the project is to offer users interactive views (like graph and table modes) along with robust JSON comparison, parsing, and formatting capabilities.

##### Main Components
- Frontend (Client UI):
- Represented by the Next.js/React application contained in the “src/app” directory.
- Includes various UI components (from “src/components/”, “src/containers/”) such as the editor panels, landing page, login, and pricing views.
- Separate submodules include the Editor (with LeftPanel, MainPanel, RightPanel, StatusBar and specialized editor modules for graph and mode-specific inputs), Landing/FAQ/Features pages, and Login pages.
- API / Backend Endpoints:
- Found under “src/app/api” (authentication endpoints, billing webhook handlers, etc.).
- Acts as the server layer responsible for authentication callbacks and billing-related webhooks.
- Worker and Processing Modules:
- Located in “src/lib/worker” and related directories.
- Handle intensive operations such as JSON parsing, comparison, formatting, executing jq commands, and running other commands (e.g., CSV conversion).
- Utility Libraries and Core Functionality Modules:
- “src/lib/compare”, “src/lib/parser”, “src/lib/graph”, “src/lib/format”, and others provide core processing logic for JSON comparison, text formatting, graph layout calculations, and more.
- Database and External Service Integration:
- “src/lib/supabase” shows integration with Supabase, which is likely used to handle data storage and possibly authentication.
- Testing and CI/CD:
- The __tests__ and e2e directories (with Playwright, unit tests using Vitest, and GitHub workflow configurations) indicate automated testing and CI/CD pipelines.
- Infrastructure & Deployment:
- Files like Dockerfile, GitHub Actions workflows, and environment configuration files (e.g., .env, .dockerignore) show deployment and containerization concerns.

##### Relationships and Interactions
- The Frontend communicates directly with the Backend API endpoints (e.g., authentication and billing) via HTTP/REST.
- UI components call the Worker Modules (either directly or indirectly) when processing JSON data – for tasks such as parsing, comparison, and formatting.
- Utility libraries and core processing modules power the view components (for example, the graph view uses functions from “src/lib/graph” and “src/lib/worker/command/compare.ts”).
- The application may interact with external services (like Supabase) for data storage or additional processing.
- CI/CD pipelines (GitHub Actions) will build and deploy the application (as indicated by workflows for testing, building Docker images, etc.).

##### Architectural Patterns and Design Principles
- Modular Component Structure: The application modularizes UI (components and containers), API routes, and core logic (in “src/lib”) for better maintainability.
- Separation of Concerns: Clear separation between presentation (UI), business logic (worker modules and utility libraries), and API interactions.
- Asynchronous Processing: Usage of web workers (src/lib/worker/worker.ts) to offload heavy processing tasks.
- Micro-frontend patterns: Though built as a monolith, the segregation into modules (editor, landing, login) suggests logical micro-frontends within the overall application.
- Testing-Driven and CI/CD Enabled: A comprehensive testing setup with unit tests and end-to-end tests, along with automated GitHub workflows.

##### Relevant Technologies and Frameworks
- Frameworks/Libraries: Next.js (for SSR and routing), React (for UI components), Tailwind CSS (styling), Zustand (state management), Zod (schema validation), React Flow (for interactive graphs).
- Testing: Vitest, Playwright for end-to-end tests.
- Build / Deployment Tools: PNPM, Docker, GitHub Actions.
- External Tools: Supabase for database or authentication integration, jq support via the “src/lib/jq” modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client (Frontend) Subgraph
    subgraph "Client (Frontend)"
        A["Next.js/React App"]:::client
        B["UI Components"]:::client
        C["UI Containers"]:::client
        D["Editor Layout (App)"]:::client
        E["Editor Layout (Containers)"]:::client
        F["LeftPanel"]:::client
        G["MainPanel"]:::client
        H["RightPanel"]:::client
        I["StatusBar"]:::client
        J["Graph Components"]:::client
        K["Mode Components"]:::client
        L["Landing/FAQ/Features Pages"]:::client
        M["Login Page (App)"]:::client
        N["Login Page (Containers)"]:::client
    end

    %% Server/API Subgraph
    subgraph "Server/API"
        O["Auth API"]:::api
        P["Billing Webhook"]:::api
    end

    %% Worker & Utilities Subgraph
    subgraph "Worker & Utilities"
        Q["Worker Module"]:::worker
        R["JSON Compare Utility"]:::worker
        S["JSON Parser Utility"]:::worker
        T["JSON Formatter Utility"]:::worker
        U["Graph Utility"]:::worker
        V["jq Support Module"]:::worker
        W["Table Functions"]:::worker
    end

    %% External Services Subgraph
    subgraph "External Services"
        X["Supabase Integration"]:::external
    end

    %% Testing & CI/CD Subgraph
    subgraph "Testing & CI/CD"
        Y["Unit Tests"]:::test
        Z["End-to-End Tests"]:::test
        AA["CI/CD Workflows"]:::test
        AB["GitHub Actions"]:::test
    end

    %% Infrastructure & Deployment Subgraph
    subgraph "Infrastructure & Deployment"
        AC["Docker & Config"]:::infra
    end

    %% Connections - Client to Server/API
    A -->|"calls"| O
    A -->|"calls"| P

    %% Connections - UI and Editor components interactions
    B --> D
    C --> E
    D --> F
    D --> G
    E --> H
    E --> I
    D --> J
    E --> K
    %% Editor panels initiate JSON processing
    D -->|"processes"| Q
    E -->|"processes"| Q
    %% Landing and Login pages also trigger API calls
    L -->|"navigates"| A
    M -->|"triggers"| A
    N -->|"triggers"| A

    %% Connections - API endpoints to Worker Module
    O -->|"processes"| Q
    P -->|"processes"| Q

    %% Connections - Worker Module to Utility Libraries
    Q --> R
    Q --> S
    Q --> T
    Q --> U
    Q --> V
    Q --> W

    %% Connections - Worker Module to External Service
    Q -->|"stores/queries"| X

    %% CI/CD and Infrastructure connections (supporting the system)
    AA -->|"deploys via"| AC
    AB -->|"runs on"| AC
    AC -->|"hosts/deploys"| A
    AC -->|"hosts/deploys"| O

    %% Click Events for Client Components
    click A "https://github.com/loggerhead/json4u/tree/main/src/app"
    click B "https://github.com/loggerhead/json4u/tree/main/src/components"
    click C "https://github.com/loggerhead/json4u/tree/main/src/containers"
    click D "https://github.com/loggerhead/json4u/tree/main/src/app/editor"
    click E "https://github.com/loggerhead/json4u/tree/main/src/containers/editor"
    click F "https://github.com/loggerhead/json4u/blob/main/src/containers/editor/LeftPanel.tsx"
    click G "https://github.com/loggerhead/json4u/blob/main/src/containers/editor/MainPanel.tsx"
    click H "https://github.com/loggerhead/json4u/blob/main/src/containers/editor/RightPanel.tsx"
    click I "https://github.com/loggerhead/json4u/blob/main/src/containers/editor/StatusBar.tsx"
    click J "https://github.com/loggerhead/json4u/tree/main/src/containers/editor/graph"
    click K "https://github.com/loggerhead/json4u/tree/main/src/containers/editor/mode"
    click L "https://github.com/loggerhead/json4u/tree/main/src/containers/landing"
    click M "https://github.com/loggerhead/json4u/tree/main/src/app/(home)/login"
    click N "https://github.com/loggerhead/json4u/tree/main/src/containers/login"

    %% Click Events for API Components
    click O "https://github.com/loggerhead/json4u/tree/main/src/app/api/auth"
    click P "https://github.com/loggerhead/json4u/tree/main/src/app/api/billing/webhook"

    %% Click Events for Worker & Utility Modules
    click Q "https://github.com/loggerhead/json4u/tree/main/src/lib/worker"
    click R "https://github.com/loggerhead/json4u/tree/main/src/lib/compare"
    click S "https://github.com/loggerhead/json4u/tree/main/src/lib/parser"
    click T "https://github.com/loggerhead/json4u/tree/main/src/lib/format"
    click U "https://github.com/loggerhead/json4u/tree/main/src/lib/graph"
    click V "https://github.com/loggerhead/json4u/tree/main/src/lib/jq"
    click W "https://github.com/loggerhead/json4u/tree/main/src/lib/table"

    %% Click Event for External Services
    click X "https://github.com/loggerhead/json4u/tree/main/src/lib/supabase"

    %% Click Events for Testing & CI/CD
    click Y "https://github.com/loggerhead/json4u/tree/main/__tests__"
    click Z "https://github.com/loggerhead/json4u/tree/main/e2e"
    click AA "https://github.com/loggerhead/json4u/tree/main/.github/workflows"
    click AB "https://github.com/loggerhead/json4u/tree/main/.github/actions"

    %% Click Event for Infrastructure & Deployment
    click AC "https://github.com/loggerhead/json4u/tree/main/Dockerfile"

    %% Class Definitions for styling
    classDef client fill:#CFF9FF,stroke:#333,stroke-width:2px;
    classDef api fill:#FFEBB7,stroke:#333,stroke-width:2px;
    classDef worker fill:#D1FEEB,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD6E7,stroke:#333,stroke-width:2px;
    classDef test fill:#ECE2F0,stroke:#333,stroke-width:2px;
    classDef infra fill:#F7D6E0,stroke:#333,stroke-width:2px;
```
