# dambor/bench-flow architecture

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

- Interactive diagram: https://gitdiagram.com/dambor/bench-flow
- Repository: https://github.com/dambor/bench-flow

## Overview

##### Project type and purpose
- This is a full-stack web application (“NoSQLBench Flow”) that provides a single interface for parsing Cassandra CQL schemas, generating NoSQLBench YAML, running data‐loading (via NoSQLBench and DSBulk), exporting data, and validating consistency.
- The frontend is built in React (Vite) and the backend is a FastAPI server in Python.

##### File structure
- Top-level Makefile coordinates install, start, build, and clean tasks for both frontend and backend.
- backend/
- main.py: FastAPI app entrypoint exposing `/api/*` endpoints
- dsbulk_utils.py, nb5_executor.py, read_yaml_generator.py, schema_parser.py: modules for JAR orchestration and YAML/schema handling
- requirements.txt, Dockerfile, logs/: build and runtime artifacts
- frontend/
- package.json, vite.config.js: React/Vite setup
- src/components, src/views: UI building blocks and pages (Dashboard, Migrate, ReadYaml, WriteYaml, etc.)
- src/context: React Context providers managing application state
- src/services/api.js: fetch wrappers for backend endpoints

##### README for additional insights
- Features list confirms key components: schema parsing, write-YAML generation, data load, DSBulk export, read-YAML generation, read validation, CDM migration prep.
- API endpoints:
- /api/parse-schema
- /api/generate-yaml
- /api/dsbulk/*
- /api/nb5/*
- /api/health
- Local dev ports: backend on 8000, frontend on 3000, with a proxy for `/api/*`.

a. Main components
- Frontend (React SPA)
- Backend (FastAPI server)
- External services and artifacts:
- NoSQLBench JAR (nb5.jar)
- DSBulk JAR (dsbulk-1.11.0.jar)
- Cassandra cluster (target for data load/read)
- File system (for generated YAML files and logs)
b. Relationships and interactions
1. User interacts with React UI → triggers action in a View component
2. View calls service layer (src/services/api.js) → sends HTTP request to FastAPI `/api/...`
3. FastAPI routes to corresponding handler in main.py
4. Handler invokes one or more modules:
- schema_parser.py → parse CQL schema files
- read_yaml_generator.py / write-YAML generator → produce YAML files
- nb5_executor.py → run NoSQLBench JAR (bench run)
- dsbulk_utils.py → run DSBulk JAR for export/import
5. Modules read/write files on disk and write logs under backend/logs/
6. NoSQLBench and DSBulk processes communicate with external Cassandra cluster
7. FastAPI returns operation results/status to frontend
8. React UI updates via Context/state and displays results or errors
c. Architectural patterns and design principles
- Clear separation of concerns:
- Presentation layer (React Views & Components)
- State management (React Contexts: AppContext, DSBulkContext, NB5Context, etc.)
- Service layer for API calls
- Backend modularization of business logic into parser/generator/executor utilities
- Micro-services-style separation (even though only one backend service) between frontend and backend via typed REST API
- External process orchestration: backend spawns and manages long-running jobs (NoSQLBench, DSBulk)
d. Technologies and frameworks
- Frontend: React, Vite, Context API, ESLint
- Backend: Python 3.8+, FastAPI, Uvicorn, pip dependencies
- External: NoSQLBench JAR, DSBulk JAR, Cassandra
- DevOps: Docker for containerization, Makefile for task automation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Browser / UI Layer"
        direction TB
        SPA["React App"]:::frontend
        Entry["Entry Point (main.jsx)"]:::frontend
        Components["UI Components"]:::frontend
        Views["Views (Pages)"]:::frontend
        Context["Context Providers"]:::frontend
        APIService["API Service Layer"]:::frontend
    end

    %% API Layer
    subgraph "Backend / API Layer"
        direction TB
        API["FastAPI Server"]:::backend
        SchemaParser["Schema Parser Module"]:::backend
        YAMLGen["Read-YAML Generator"]:::backend
        NB5Exec["NoSQLBench Executor"]:::backend
        DSBulk["DSBulk Orchestration"]:::backend
        Requirements["Dependencies (requirements.txt)"]:::backend
        DockerfileNode["Dockerfile"]:::backend
        LogsDir["Logs Directory"]:::datastore
    end

    %% External Dependencies & Data Stores
    subgraph "External Dependencies & Data Stores"
        direction TB
        NBJar["NoSQLBench JAR"]:::external
        DSBulkJar["DSBulk JAR"]:::external
        Cassandra["Cassandra Cluster"]:::datastore
        FileSystem["File System"]:::datastore
    end

    %% Project Automation
    Makefile["Makefile"]:::backend

    %% Connections - UI flow
    SPA --> Entry
    Entry --> Components
    Components --> Views
    Views --> Context
    Context --> APIService
    APIService -->|HTTP /api/*| API
    APIService <--|JSON response| API
    API --> SchemaParser
    API --> YAMLGen
    API --> NB5Exec
    API --> DSBulk

    %% Backend modules interactions
    SchemaParser -->|write schema| FileSystem
    YAMLGen -->|generate YAML| FileSystem
    NB5Exec -->|spawn process| NBJar
    NB5Exec -->|read/write| Cassandra
    NB5Exec -->|log output| LogsDir
    DSBulk -->|spawn process| DSBulkJar
    DSBulk -->|read/write| Cassandra
    DSBulk -->|log output| LogsDir

    %% Data Store responses
    FileSystem --> API
    Cassandra --> API

    %% Automation
    Makefile -.-> SPA
    Makefile -.-> API

    %% Click Events
    click SPA "https://github.com/dambor/bench-flow/tree/main/frontend/"
    click Entry "https://github.com/dambor/bench-flow/blob/main/frontend/src/main.jsx"
    click Components "https://github.com/dambor/bench-flow/tree/main/frontend/src/components/"
    click Views "https://github.com/dambor/bench-flow/tree/main/frontend/src/views/"
    click Context "https://github.com/dambor/bench-flow/tree/main/frontend/src/context/"
    click APIService "https://github.com/dambor/bench-flow/blob/main/frontend/src/services/api.js"
    click API "https://github.com/dambor/bench-flow/blob/main/backend/main.py"
    click SchemaParser "https://github.com/dambor/bench-flow/blob/main/backend/schema_parser.py"
    click YAMLGen "https://github.com/dambor/bench-flow/blob/main/backend/read_yaml_generator.py"
    click NB5Exec "https://github.com/dambor/bench-flow/blob/main/backend/nb5_executor.py"
    click DSBulk "https://github.com/dambor/bench-flow/blob/main/backend/dsbulk_utils.py"
    click Requirements "https://github.com/dambor/bench-flow/blob/main/backend/requirements.txt"
    click DockerfileNode "https://github.com/dambor/bench-flow/tree/main/backend/Dockerfile"
    click LogsDir "https://github.com/dambor/bench-flow/tree/main/backend/logs/"
    click Makefile "https://github.com/dambor/bench-flow/tree/main/Makefile"

    %% Styles
    classDef frontend fill:#D6EAFE,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E2F5D6,stroke:#22863a,color:#22863a
    classDef external fill:#E0E0E0,stroke:#6a737d,color:#6a737d
    classDef datastore fill:#FBE8A6,stroke:#d73a49,color:#d73a49
```
