# kalyanchakravarthyv/equilibrium-react architecture

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

- Interactive diagram: https://gitdiagram.com/kalyanchakravarthyv/equilibrium-react
- Repository: https://github.com/kalyanchakravarthyv/equilibrium-react

## Overview

##### Project Type and Purpose
- This is a single-page, frontend-focused web application built on Next.js 13’s App Router.
- It uses React and the Carbon Design System to teach UI best practices.
- There is no in-repo backend or database—data is fetched by client modules (`finderClient.js`, `scriptClient.js`, `dataExportClient.js`) from external services/APIs.

##### File Structure
Top-Level:
- next.config.js, package.json, .env → configuration & environment
- .circleci/config.yml → CI/CD pipeline
- public/ → static assets (index.html, manifest.json)
- src/app/ → Next.js routing (App Router pages, layouts, global styles, providers)
- src/components/ → reusable UI components
Patterns:
- App Router: each folder under src/app (finder, home, script, sql, test) is a route
- layout.js & providers.js at src/app root define global layout and context providers
- SCSS modules alongside pages/components for styling
- Client modules in each route folder handle external data communication

##### Key README Insights
- Bootstrapped with Create React App originally, but structure indicates a Next.js upgrade
- Standard npm scripts: start, build, test, etc.
- Progressive enhancement, bundling, and Carbon components

##### Main Components & Interactions
a. Frontend Runtime (Next.js Server + React Client)
– Next.js Server (Node.js)
- Hosts SSR/SSG endpoints for each route in src/app
- Serves static files from public/
- Reads configurations (next.config.js, .env)
– Browser Client
- Hydrates React components
- Manages client-side routing via Next.js
- Loads component SCSS, global styles
b. Routes (Logical Pages)
– /home → Landing page
– /finder → Search UI (uses finderClient)
– /script → Script editor (uses scriptClient)
– /sql → SQL editor/data export (uses dataExportClient)
– /test → Test harness page
c. Shared UI Components
– GlobalHeader, Info, SQLEditor, ScriptEditor
– Carbon Design System library as a peer dependency
d. External Services
– API endpoints consumed by client modules
– Potentially authentication, data storage, or analytic services outside this repo
e. CI/CD Pipeline
– CircleCI config runs linting, testing, and deploy steps
– npm scripts invoked in the pipeline

##### Architectural Patterns & Design Principles
- “Separation of Concerns”:
– Pages/routes vs. shared components vs. data-access clients vs. styles
- “Single Source of Truth” for global state (in providers.js)
- CSS-in-SCSS modularity for encapsulated styling
- Data fetching encapsulated in per‐feature client modules
- Next.js App Router conventions for SSR/SSG

##### Final Checklist
- Components grouped by layer (CI/CD, Server, Routes, Components, Browser, External APIs)
- Annotations for key technologies (Next.js 13, React, SCSS, Carbon)
- A note on build tools (Webpack/Babel via Next.js, npm scripts)

## Diagram (Mermaid)

```mermaid
graph TB
    %% CI/CD Layer
    subgraph "CI/CD Pipeline"
        CI_CircleCI["CircleCI\n.config.yml"]:::ci
    end

    %% Configuration Files
    subgraph "Configuration Files"
        Env[".env"]:::config
        NextConfig["next.config.js"]:::config
        Package["package.json"]:::config
    end

    %% Server Layer
    subgraph "Server Runtime"
        NextServer["Next.js Server\n(Node.js + SSR)"]:::server
    end

    %% Static Assets
    subgraph "Public CDN / Static"
        IndexHTML["index.html"]:::static
        Manifest["manifest.json"]:::static
    end

    %% App Entry & Global Providers
    subgraph "Root App Entry & Global Layout"
        AppPage["page.js"]:::client
        Layout["layout.js"]:::client
        Providers["providers.js"]:::client
        GlobalsSCSS["globals.scss"]:::static
    end

    %% Routes Layer
    subgraph "Routes"
        Home["/home page\npage.js"]:::client
        HomeStyles["_landing-page.scss"]:::static
        MixinsHome["_mixins.scss"]:::static
        OverridesHome["_overrides.scss"]:::static

        Finder["/finder page\npage.js"]:::client
        FinderStyles["_finder-page.scss"]:::static
        FinderClient["finderClient.js"]:::client

        ScriptRoute["/script page\npage.js"]:::client
        ScriptStyles["_script-editor-page.scss"]:::static
        ScriptClient["scriptClient.js"]:::client

        SQL["/sql page\npage.js"]:::client
        SQLStyles["_sql-editor-page.scss"]:::static
        DataExport["dataExportClient.js"]:::client

        Test["/test page\npage.js"]:::client
    end

    %% Shared Components
    subgraph "Shared UI Components"
        GlobalHeader["GlobalHeader.js"]:::component
        GHStyles["_global-header.scss"]:::static

        InfoComp["Info.js"]:::component
        InfoStyles["_info.scss"]:::static

        SQLEditorComp["SQLEditor.js"]:::component
        SQLEditorIndex["index.js"]:::component
        SQLEdinStyles["_sql-editor.scss"]:::static
        SQLEdinMixins["_mixins.scss"]:::static
        SQLEdinOverrides["_overrides.scss"]:::static

        ScriptEditorComp["ScriptEditor.js"]:::component
        ScriptEditorIndex["index.js"]:::component
        SEStyles["_script-editor.scss"]:::static
        SEMixins["_mixins.scss"]:::static
        SEOverrides["_overrides.scss"]:::static
    end

    %% Browser Layer
    subgraph "Browser (React CSR)"
        Browser["Browser Client"]:::client
    end

    %% External APIs
    subgraph "External Services / APIs"
        ExternalAPI["External APIs"]:::external
    end

    %% Connections
    CI_CircleCI -->|deploys| NextServer
    Env --> NextServer
    NextConfig --> NextServer
    Package --> NextServer

    NextServer -->|serves static| IndexHTML
    NextServer -->|serves static| Manifest

    NextServer -->|SSR page| Browser
    Browser -->|initial request| NextServer

    Browser --> Home
    Browser --> Finder
    Browser --> ScriptRoute
    Browser --> SQL
    Browser --> Test

    Browser --> GlobalHeader
    Browser --> InfoComp
    Browser --> SQLEditorComp
    Browser --> ScriptEditorComp

    Home -->|styles| HomeStyles
    Home -->|styles| MixinsHome
    Home -->|styles| OverridesHome

    Finder --> FinderStyles
    Finder --> FinderClient
    FinderClient -->|fetch data| ExternalAPI

    ScriptRoute --> ScriptStyles
    ScriptRoute --> ScriptClient
    ScriptClient -->|fetch data| ExternalAPI

    SQL --> SQLStyles
    SQL --> DataExport
    DataExport -->|fetch data| ExternalAPI

    Test -->|static page| NextServer

    AppPage --> NextServer
    Layout --> NextServer
    Providers --> NextServer
    GlobalsSCSS --> NextServer

    CI_CircleCI -->|runs lint/test| Package

    %% Click Events
    click CI_CircleCI "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/.circleci/config.yml"
    click Env "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/.env"
    click NextConfig "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/next.config.js"
    click Package "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/package.json"
    click IndexHTML "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/public/index.html"
    click Manifest "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/public/manifest.json"
    click Layout "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/layout.js"
    click Providers "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/providers.js"
    click GlobalsSCSS "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/globals.scss"
    click AppPage "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/page.js"
    click Home "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/home/page.js"
    click HomeStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/home/_landing-page.scss"
    click MixinsHome "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/home/_mixins.scss"
    click OverridesHome "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/home/_overrides.scss"
    click Finder "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/finder/page.js"
    click FinderStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/finder/_finder-page.scss"
    click FinderClient "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/finder/finderClient.js"
    click ScriptRoute "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/script/page.js"
    click ScriptStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/script/_script-editor-page.scss"
    click ScriptClient "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/script/scriptClient.js"
    click SQL "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/sql/page.js"
    click SQLStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/sql/_sql-editor-page.scss"
    click DataExport "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/sql/dataExportClient.js"
    click Test "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/app/test/page.js"
    click GlobalHeader "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/GlobalHeader/GlobalHeader.js"
    click GHStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/GlobalHeader/_global-header.scss"
    click InfoComp "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/Info/Info.js"
    click InfoStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/Info/_info.scss"
    click SQLEditorComp "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/SQLEditor/SQLEditor.js"
    click SQLEditorIndex "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/SQLEditor/index.js"
    click SQLEdinStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/SQLEditor/_sql-editor.scss"
    click SQLEdinMixins "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/SQLEditor/_mixins.scss"
    click SQLEdinOverrides "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/SQLEditor/_overrides.scss"
    click ScriptEditorComp "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/ScriptEditor/ScriptEditor.js"
    click ScriptEditorIndex "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/ScriptEditor/index.js"
    click SEStyles "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/ScriptEditor/_script-editor.scss"
    click SEMixins "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/ScriptEditor/_mixins.scss"
    click SEOverrides "https://github.com/kalyanchakravarthyv/equilibrium-react/blob/main/src/components/ScriptEditor/_overrides.scss"

    %% Styles
    classDef server fill:#D0E6FF,stroke:#4D90FE,color:#000
    classDef client fill:#E6F7E6,stroke:#2D8A2D,color:#000
    classDef component fill:#E6F7E6,stroke:#2D8A2D,color:#000
    classDef external fill:#FFE5CC,stroke:#FF8C00,color:#000
    classDef static fill:#F2F2F2,stroke:#A6A6A6,color:#000
    classDef config fill:#F2F2F2,stroke:#A6A6A6,color:#000
    classDef ci fill:#D0E6FF,stroke:#4D90FE,color:#000
```
