# nasa-impact/veda-ui architecture

> Architecture diagram of the GitHub repository nasa-impact/veda-ui, 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/nasa-impact/veda-ui
- Repository: https://github.com/nasa-impact/veda-ui

## Overview

##### Project type and purpose
- VEDA Dashboard UI is a front-end, React-based single-page application for browsing and exploring NASA-IMPACT datasets (MDX-driven content, geospatial layers, charts). This repo contains only the UI; content configuration lives in a separate “veda-config” repo.

##### File structure
- Top-level:
- Dot-files and config (.babelrc, .parcelrc, .env, ESLint/Prettier)
- GitHub Actions workflows under .github/workflows
- README’s and ADRs under docs/ (including docs/development/ARCHITECTURE.md)
- app/
- app/index.html template
- app/graphics for static graphics
- scripts/
- main.tsx and entry points (redirects.tsx, instance.ts)
- context providers (veda-ui-provider, react-query)
- data-layer (fetch abstraction, dataset definitions)
- components grouped by domain (common, home, catalog, exploration, stories, sandbox, user-pages, uhoh)
- styles and USWDS wrappers under scripts/styles and scripts/uswds
- utils and custom parcel resolvers/transformers for MDX frontmatter
- static/public/geo-data – geojson state boundaries and other static assets
- mock/ – sample MDX content for local testing
- parcel-resolver-veda & parcel-transformer-mdx-frontmatter – custom build plugins
- tests/
- Jest unit tests alongside components
- Playwright E2E under test/playwright

##### README for additional insights
- Confirms UI-only focus, points to content/config docs elsewhere
- Directs to ARCHITECTURE.md for more background

##### Main components and their interactions
a. Developer Environment
- Local machine with Node.js, Yarn/NPM, .env for local overrides
b. Source Control & CI/CD
- GitHub repository → GitHub Actions pipelines (lint, test, build, release)
c. Build Layer
- Parcel bundler + Babel compile TSX/JS, MDX frontmatter transformer, parcel-resolver-veda for content resolution
d. Hosting/Deployment
- Static artifact (index.html + JS/CSS bundles + static assets) deployed to a CDN or static host (e.g. S3/Netlify/CloudFront)
e. Browser Runtime
1. Loader (index.html) pulls in the JS bundle
2. React Root mounts (main.tsx)
3. Context Providers wrap the app (veda-ui-provider, react-query)
4. Router (redirects.tsx) directs to feature pages: Home, Data Catalog, Exploration, Stories, Sandbox, User Pages, About, Uhoh
5. Each page composes domain components (from scripts/components/…) which in turn use common UI primitives (header, footer, cards, tables, charts, map controls)
6. Data layer hooks (use-stac-metadata-datasets, react-query, custom fetch utilities) call out to:
– veda-config server (JSON content)
– NASA STAC/geospatial APIs (tile servers, geojson)
– Static assets under /static/public
7. Components use Mapbox GL (scripts/components/common/map)

##### Architectural patterns & design principles
- Component-driven, domain-organized React modules
- Custom Parcel plugins for frontmatter-based MDX content inclusion
- Hook-based data fetching and state management via react-query
- Static SPA build – no backend code in this repo
- Separation of concerns: content config external, UI focuses on rendering

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Environment"
        Dev["Developer Local Machine"]
    end

    subgraph "Source Control & CI/CD"
        GH["GitHub Repo"]
        CI["GitHub Actions Pipelines"]:::build
    end

    subgraph "Build Layer"
        Babel["Babel (.babelrc)"]:::build
        ParcelCfg["Parcel (.parcelrc)"]:::build
        Resolv["parcel-resolver-veda"]:::build
        Transformer["parcel-transformer-mdx-frontmatter"]:::build
        Build["Parcel Bundler"]:::build
    end

    subgraph "Hosting/Deployment"
        CDN["CDN / Static Host"]:::external
    end

    subgraph "Browser Runtime"
        Loader["HTML Loader (app/index.html)"]:::runtime
        ReactRoot["React Root (main.tsx)"]:::runtime
        Providers["Context Providers"]:::runtime
        Router["Router (redirects.tsx)"]:::runtime

        subgraph "Feature Pages"
            Home["Home Module"]:::runtime
            Catalog["Data Catalog Module"]:::runtime
            Explor["Exploration Module"]:::runtime
            StoriesHub["Stories Hub Module"]:::runtime
            StoriesSingle["Stories Single Module"]:::runtime
            Sandbox["Sandbox Module"]:::runtime
            UserPages["User Pages Module"]:::runtime
            About["About Page Module"]:::runtime
            Uhoh["Uhoh Page Module"]:::runtime
        end

        subgraph "UI Components & Data"
            Common["Common UI Primitives"]:::runtime
            DataLayer["Data Layer (datasets)"]:::runtime
            MapComp["Map Components"]:::runtime
        end
    end

    subgraph "External Services"
        Config["veda-config Server"]:::external
        STAC["NASA STAC/Geo APIs"]:::external
        StaticGeo["Static GeoJSON Assets"]:::external
    end

    Dev --> GH
    GH --> CI
    CI --> Build
    Build --> Babel
    Build --> ParcelCfg
    Build --> Resolv
    Build --> Transformer
    Build --> CDN
    CDN --> Loader
    Loader --> ReactRoot
    ReactRoot --> Providers
    Providers --> Router
    Router --> Home
    Router --> Catalog
    Router --> Explor
    Router --> StoriesHub
    Router --> StoriesSingle
    Router --> Sandbox
    Router --> UserPages
    Router --> About
    Router --> Uhoh
    Home --> Common
    Catalog --> Common
    Explor --> Common
    StoriesHub --> Common
    StoriesSingle --> Common
    Sandbox --> Common
    UserPages --> Common
    About --> Common
    Uhoh --> Common
    Home --> DataLayer
    Catalog --> DataLayer
    Explor --> DataLayer
    StoriesHub --> DataLayer
    StoriesSingle --> DataLayer
    Sandbox --> DataLayer
    UserPages --> DataLayer
    About --> DataLayer
    Uhoh --> DataLayer
    DataLayer --> Config
    DataLayer --> STAC
    DataLayer --> StaticGeo
    Common --> MapComp
    MapComp --> STAC

    click CI "https://github.com/nasa-impact/veda-ui/tree/main/.github/workflows/"
    click Babel "https://github.com/nasa-impact/veda-ui/blob/main/.babelrc"
    click ParcelCfg "https://github.com/nasa-impact/veda-ui/blob/main/.parcelrc"
    click Resolv "https://github.com/nasa-impact/veda-ui/tree/main/parcel-resolver-veda/"
    click Transformer "https://github.com/nasa-impact/veda-ui/tree/main/parcel-transformer-mdx-frontmatter/"
    click Loader "https://github.com/nasa-impact/veda-ui/blob/main/app/index.html"
    click ReactRoot "https://github.com/nasa-impact/veda-ui/blob/main/scripts/main.tsx"
    click Router "https://github.com/nasa-impact/veda-ui/blob/main/scripts/redirects.tsx"
    click Providers "https://github.com/nasa-impact/veda-ui/blob/main/scripts/context/veda-ui-provider.tsx"
    click Providers "https://github.com/nasa-impact/veda-ui/blob/main/scripts/context/react-query.tsx"
    click DataLayer "https://github.com/nasa-impact/veda-ui/blob/main/scripts/data-layer/datasets.tsx"
    click Common "https://github.com/nasa-impact/veda-ui/tree/main/scripts/components/common/"
    click Home "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/home/index.tsx"
    click Catalog "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/data-catalog/container.tsx"
    click Explor "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/exploration/index.tsx"
    click StoriesHub "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/stories/hub/container.tsx"
    click StoriesSingle "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/stories/single/index.tsx"
    click Sandbox "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/sandbox/index.js"
    click UserPages "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/user-pages/index.tsx"
    click About "https://github.com/nasa-impact/veda-ui/blob/main/app/scripts/components/about/index.tsx"
    click Uhoh "https://github.com/nasa-impact/veda-ui/blob/main/scripts/components/uhoh/index.js"
    click StaticGeo "https://github.com/nasa-impact/veda-ui/tree/main/static/public/geo-data/"

    classDef build fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef runtime fill:#a2d4f9,stroke:#333,stroke-width:1px
    classDef external fill:#f9d39f,stroke:#333,stroke-width:1px
    classDef tools fill:#e2e2e2,stroke:#333,stroke-width:1px
```
