# sebastien-sq/flip-a-scale architecture

> Architecture diagram of the GitHub repository sebastien-sq/flip-a-scale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebastien-sq/flip-a-scale
- Repository: https://github.com/sebastien-sq/flip-a-scale

## Overview

##### Project Overview and Type
- The project is a full-stack Next.js web application, although it is primarily client-focused with no dedicated backend server component.
- Its purpose is to help musicians improve improvisation by generating random musical scales using a flip-card interface.
- The README and file structure emphasize UI interactivity (flip cards), random generation features, and handling of musical specifics (flats, sharps, etc.).

##### Main Components
a. UI Layer (Frontend):
- Next.js App Layer: Represented by the “src/app” directory containing layout.tsx, page.tsx, and global styling files. This defines the overall page structure and routing.
- Components: Under “src/components”, divide further into submodules:
- Card Components: BackfrontCard.tsx, FrontCard.tsx, CardContainer.tsx, and StartingCard.tsx implementing the flip card user interface.
- Checkbox Components: CheckboxContainer.tsx, FlatCheckbox.tsx, SharpCheckbox.tsx for toggling flats and sharps.
- Scales Components: ScalesContainer.tsx, generateScale.ts, orderScale.ts that handle scale generation and manipulation.
b. Utility and Business Logic Layer:
- Utility Functions: Under “src/utils/functions”, the functions like getRandomRootNote.ts and getRandomScale.ts encapsulate the core logic for generating random musical scale data.
- Types Definition: “src/utils/types.ts” that standardizes data models.
c. Static Data and Public Assets:
- Public Folder: Contains assets and JSON files (flats.json, naturals.json, sharps.json) used to store scale/note data.
d. Configuration & Tooling:
- Configuration Files: ESLint (.eslintrc.json), Prettier (.prettierc), Tailwind (tailwind.config.ts), and Next.js configuration (next.config.mjs) show the tech stack and styling system.
- Build and Dependency Management: Package.json, package-lock.json, and TS configuration files that are fundamental to project setup.

##### Relationships and Interactions
- That the Next.js App Layer calls upon the UI components.
- Connections from UI components to static data in the public folder, especially when the components use JSON datasets (flats, naturals, sharps) for their logic.
- Integration points of configuration files that influence behavior (e.g., Tailwind for styling, TypeScript for type checking).

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Emphasize the modular, reusable design of React components.
- Separation of Concerns: Divide the application into presentation (UI), business logic (util functions and scales generation), and static data layers.
- Standard Configurations: Represent the role of configuration files that govern development, styling, and linting practices.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Nodes
    user["User Interaction"]:::user

    subgraph "UI Layer"
        NextApp["Next.js App"]:::ui
        subgraph "Components"
            subgraph "Card Components"
                backfrontCard["BackfrontCard"]:::component
                frontCard["FrontCard"]:::component
                cardContainer["CardContainer"]:::component
                startingCard["StartingCard"]:::component
            end
            subgraph "Checkbox Components"
                checkboxContainer["CheckboxContainer"]:::component
                flatCheckbox["FlatCheckbox"]:::component
                sharpCheckbox["SharpCheckbox"]:::component
            end
            subgraph "Scales Components"
                scalesContainer["ScalesContainer"]:::component
                generateScale["generateScale"]:::component
                orderScale["orderScale"]:::component
            end
        end
    end

    subgraph "Utility Functions"
        getRandomRootNote["getRandomRootNote"]:::util
        getRandomScale["getRandomScale"]:::util
        typesDef["Types Definition"]:::util
    end

    subgraph "Static Data"
        flatsData["Flats Data"]:::data
        naturalsData["Naturals Data"]:::data
        sharpsData["Sharps Data"]:::data
    end

    subgraph "Configuration & Tooling"
        eslint["ESLint (.eslintrc.json)"]:::config
        prettier["Prettier (.prettierc)"]:::config
        nextConfig["Next.js Config (next.config.mjs)"]:::config
        tailwind["Tailwind Config (tailwind.config.ts)"]:::config
        packageJson["Package.json"]:::config
        packageLock["Package-lock.json"]:::config
        tsConfig["TSConfig (tsconfig.json)"]:::config
    end

    %% Arrows for interactions
    user -->|"initiates"| NextApp
    NextApp -->|"renders"| cardContainer
    NextApp -->|"renders"| checkboxContainer
    NextApp -->|"renders"| scalesContainer

    cardContainer -->|"flipTriggers"| generateScale
    generateScale -->|"calls"| getRandomScale
    scalesContainer -->|"calls"| orderScale
    orderScale -->|"uses"| getRandomRootNote
    scalesContainer -->|"retrieves"| flatsData
    scalesContainer -->|"retrieves"| naturalsData
    scalesContainer -->|"retrieves"| sharpsData

    checkboxContainer -->|"toggles"| flatCheckbox
    checkboxContainer -->|"toggles"| sharpCheckbox

    NextApp -->|"integrates"| eslint
    NextApp -->|"integrates"| prettier
    NextApp -->|"integrates"| nextConfig
    NextApp -->|"integrates"| tailwind
    NextApp -->|"integrates"| packageJson
    NextApp -->|"integrates"| packageLock
    NextApp -->|"integrates"| tsConfig

    cardContainer -->|"updates"| typesDef
    cardContainer -->|"contains"| backfrontCard
    cardContainer -->|"contains"| frontCard
    cardContainer -->|"communicates"| startingCard
    scalesContainer -->|"uses"| generateScale
    scalesContainer -->|"uses"| orderScale
    flatCheckbox -->|"influences"| scalesContainer
    sharpCheckbox -->|"influences"| scalesContainer

    %% Click Events
    click NextApp "https://github.com/sebastien-sq/flip-a-scale/tree/master/src/app"
    click backfrontCard "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/card/BackfrontCard.tsx"
    click frontCard "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/card/FrontCard.tsx"
    click cardContainer "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/card/CardContainer.tsx"
    click startingCard "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/card/StartingCard.tsx"
    click checkboxContainer "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/checkboxes/CheckboxContainer.tsx"
    click flatCheckbox "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/checkboxes/FlatCheckbox.tsx"
    click sharpCheckbox "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/checkboxes/SharpCheckbox.tsx"
    click scalesContainer "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/scales/ScalesContainer.tsx"
    click generateScale "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/scales/generateScale.ts"
    click orderScale "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/components/scales/orderScale.ts"
    click getRandomRootNote "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/utils/functions/getRandomRootNote.ts"
    click getRandomScale "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/utils/functions/getRandomScale.ts"
    click typesDef "https://github.com/sebastien-sq/flip-a-scale/blob/master/src/utils/types.ts"
    click flatsData "https://github.com/sebastien-sq/flip-a-scale/blob/master/public/data/flats.json"
    click naturalsData "https://github.com/sebastien-sq/flip-a-scale/blob/master/public/data/naturals.json"
    click sharpsData "https://github.com/sebastien-sq/flip-a-scale/blob/master/public/data/sharps.json"
    click eslint "https://github.com/sebastien-sq/flip-a-scale/blob/master/.eslintrc.json"
    click prettier "https://github.com/sebastien-sq/flip-a-scale/blob/master/.prettierc"
    click nextConfig "https://github.com/sebastien-sq/flip-a-scale/blob/master/next.config.mjs"
    click tailwind "https://github.com/sebastien-sq/flip-a-scale/blob/master/tailwind.config.ts"
    click packageJson "https://github.com/sebastien-sq/flip-a-scale/blob/master/package.json"
    click packageLock "https://github.com/sebastien-sq/flip-a-scale/blob/master/package-lock.json"
    click tsConfig "https://github.com/sebastien-sq/flip-a-scale/blob/master/tsconfig.json"

    %% Styles
    classDef ui fill:#a2d9ce,stroke:#333,stroke-width:2px;
    classDef component fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef util fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef data fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef config fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef user fill:#fad7a0,stroke:#333,stroke-width:2px;
```
