# anipr2002/npz-web-viewer architecture

> Architecture diagram of the GitHub repository anipr2002/npz-web-viewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anipr2002/npz-web-viewer
- Repository: https://github.com/anipr2002/npz-web-viewer

## Overview

##### Project Type and Purpose
- A React/Next.js frontend for UI and interactive charts
- A FastAPI backend for file handling, data processing, and ML routines
- No persistent database—data flows in memory from upload to visualization

##### File Structure Analysis
- Top level
- `docker-compose.yml` & `docker-compose.dev.yml`—container orchestration for frontend and backend
- `docs/images`—screenshots used in the README
- Backend (`npz_viewer_backend`)
- `Dockerfile`, `pyproject.toml`, `app/main.py`—FastAPI service entrypoint
- `tests/upload_test.py`—unit tests for upload endpoints
- Frontend (`npz_viewer_client`)
- Next.js app under `app/`, with `api/upload/route.ts` calling backend
- `components/`—UI building blocks: charts, file uploader, ML panels
- `lib/`, `utils/`—helper functions (e.g., CSV export, array parsing)
- Configs: `package.json`, `next.config.ts`, Tailwind, PostCSS, TypeScript

##### README Insights
- Confirms technology stack: FastAPI + Python (NumPy, scikit-learn) on the backend; Next.js + React + TypeScript on the frontend
- Describes features (upload, multiple chart types, clustering, PCA) and Docker setup
- Notes environment variables for CORS (`ALLOWED_ORIGINS`) and API URL (`NEXT_PUBLIC_API_URL`)

##### Essential Detail Checklist
- Explicitly show containers and network links from docker-compose
- Call out key modules: `app/main.py`, `app/api/upload/route.ts`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Orchestration
    Dev["Developer Workstation"]:::dev
    DockerCompose["Docker Compose"]:::docker
    Dev -->|"runs\"docker-compose up\""| DockerCompose

    %% Containers
    DockerCompose --> FrontendContainer["Frontend Container\n(Next.js @ :3000)"]:::frontend
    DockerCompose --> BackendContainer["Backend Container\n(FastAPI @ :8000)"]:::backend

    %% Browser to Frontend
    Browser["Client Browser"]:::frontend
    Browser -->|"HTTP GET /"| FrontendContainer

    %% Frontend Subgraph
    subgraph "Frontend Container" 
        direction TB
        NextApp["Next.js App"]:::frontend
        ApiRoute["API Route\nPOST /api/upload"]:::frontend
        Visualization["Visualization Components"]:::frontend
        FileUploader["File Uploader\nComponents"]:::frontend
        MLPanels["ML Panels"]:::frontend
        UIPrimitives["UI Primitives & Theme"]:::frontend
        Utils["Utility Functions"]:::frontend
        Configs["Config Files"]:::frontend

        NextApp --> Visualization
        NextApp --> FileUploader
        NextApp --> MLPanels
        NextApp --> UIPrimitives
        NextApp --> Utils
        NextApp --> Configs
        NextApp --> ApiRoute
    end

    FrontendContainer --> NextApp
    Browser -->|"Upload .npz/.npy"| FileUploader
    FileUploader --> ApiRoute
    ApiRoute -->|"Proxy POST /upload"| BackendContainer

    %% Backend Subgraph
    subgraph "Backend Container"
        direction TB
        FastAPI["FastAPI Service\napp/main.py"]:::backend
        MLModule["ML & Data Processing"]:::backend
        Dependencies["pyproject.toml"]:::backend
        Tests["Upload Endpoint Tests"]:::backend

        FastAPI --> MLModule
        FastAPI --> Dependencies
        FastAPI --> Tests
    end

    BackendContainer --> FastAPI
    BackendContainer --> Dependencies
    BackendContainer --> Tests

    %% Response Flow
    FastAPI -->|"JSON metadata or CSV link"| ApiRoute
    ApiRoute -->|"Response data"| Visualization
    Visualization --> Browser

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#2d7f2d,color:#000
    classDef backend fill:#e0f0ff,stroke:#2471a3,color:#000
    classDef docker fill:#f0f0f0,stroke:#888,color:#000
    classDef dev fill:#f0e0ff,stroke:#8d24a3,color:#000

    %% Click Events - Frontend
    click DockerCompose "https://github.com/anipr2002/npz-web-viewer/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/anipr2002/npz-web-viewer/blob/main/docker-compose.dev.yml"
    click FrontendContainer "https://github.com/anipr2002/npz-web-viewer/tree/main/npz_viewer_client/Dockerfile"
    click NextApp "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/app/layout.tsx"
    click ApiRoute "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/app/api/upload/route.ts"
    click Visualization "https://github.com/anipr2002/npz-web-viewer/tree/main/npz_viewer_client/components/dashboard/charts/"
    click Visualization "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/charts/chart.tsx"
    click Visualization "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/charts/scatterplot.tsx"
    click Visualization "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/charts/scatter3d.tsx"
    click Visualization "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/charts/surface3d.tsx"
    click Visualization "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/charts/greyscale.tsx"
    click FileUploader "https://github.com/anipr2002/npz-web-viewer/tree/main/npz_viewer_client/components/dashboard/file-uploader/"
    click FileUploader "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/file-uploader/FileUploader.tsx"
    click FileUploader "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/file-uploader/FileDropzone.tsx"
    click FileUploader "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/file-uploader/UploadButton.tsx"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/tree/main/npz_viewer_client/components/dashboard/ml/"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/ml/MLPanel.tsx"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/ml/ClusteringPanel.tsx"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/ml/DimensionalityReductionPanel.tsx"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/ml/ClusteringVisualization.tsx"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/ml/DimensionalityVisualization.tsx"
    click MLPanels "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/dashboard/ml/index.ts"
    click UIPrimitives "https://github.com/anipr2002/npz-web-viewer/tree/main/npz_viewer_client/components/ui/"
    click UIPrimitives "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/components/theme-provider.tsx"
    click Utils "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/lib/utils.ts"
    click Utils "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/utils/csv-utils.ts"
    click Configs "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/next.config.ts"
    click Configs "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/tailwind.config.ts"
    click Configs "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/postcss.config.mjs"
    click Configs "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_client/tsconfig.json"

    %% Click Events - Backend
    click FastAPI "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_backend/npz_viewer_backend/app/main.py"
    click Dependencies "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_backend/pyproject.toml"
    click Tests "https://github.com/anipr2002/npz-web-viewer/blob/main/npz_viewer_backend/tests/upload_test.py"
    click BackendContainer "https://github.com/anipr2002/npz-web-viewer/tree/main/npz_viewer_backend/Dockerfile"
    click Docs["docs/images/"] "docs/images/"
    click ProjectReadme["README.md"] "README.md"
    click BackendReadme["npz_viewer_backend/README.md"] "npz_viewer_backend/README.md"
    click FrontendReadme["npz_viewer_client/README.md"] "npz_viewer_client/README.md"
```
