# floguo/giftbox architecture

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

- Interactive diagram: https://gitdiagram.com/floguo/giftbox
- Repository: https://github.com/floguo/giftbox

## Overview

##### Main System Components

A. Client-Side (Browser)
- Next.js Frontend Application
- Interactive Components Layer
- Media Processing Layer
- State Management
- Browser APIs Integration

B. External Services
- Spotify Integration
- File Storage (for photos)

##### Component Organization

A. Core Application Layer
- Layout Component (src/app/layout.tsx)
- Main Page Component (src/app/page.tsx)
- Global Styles (src/app/globals.css)

B. Interactive Components Layer (Group these functionally):
1. Media Components:
- PhotoUploader & PhotoItem
- VoiceRecorder & VoiceNote
- SpotifyPlayer
- DoodleDrawer

2. Text & Note Components:
- LetterNote
- LetterCanvas
- NotePaper

3. UI Components:
- Toolbar
- DraggableItem (wrapper component)
- Basic UI elements (button, dialog, input, etc.)

##### Technical Integration Points

Integration with browser APIs:
- Web Audio API (for voice recording)
- Canvas API (for drawing)
- Drag and Drop API
- File System API (for photo uploads)

##### Data Flow Visualization

- User interaction flows
- Media processing paths
- State updates
- External service communications

**🟦 Core Application Components**
**🟨 Interactive Elements**
**🟩 Browser APIs**
**🟪 External Services**
**⟶  Data Flow**
**⟲  State Updates**

##### Implementation Details to Highlight

- Component hierarchy starting from layout.tsx
- Where global styles and utilities are applied
- Demonstrate how DraggableItem wraps other components
- Toolbar's relationship with other components

##### Key Architectural Patterns to Emphasize

- Component Composition
- Event-Driven Interactions
- Media Processing Pipeline
- Responsive State Management

##### Create three main sections
- Core Components (top)
- Interactive Components (middle)
- Browser APIs & External Services (bottom)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Browser
        subgraph "Core Application Layer"
            Layout["Layout Component"]:::core
            MainPage["Main Page Component"]:::core
            GlobalStyles["Global Styles"]:::core
            Layout --> MainPage
            GlobalStyles -.-> Layout
        end

        subgraph "Interactive Components Layer"
            subgraph "Media Components"
                PhotoUp["PhotoUploader"]:::media
                PhotoItem["PhotoItem"]:::media
                VoiceRec["VoiceRecorder"]:::media
                VoiceNote["VoiceNote"]:::media
                Spotify["SpotifyPlayer"]:::media
                Doodle["DoodleDrawer"]:::media
                Waveform["WaveformVisualizer"]:::media
            end

            subgraph "Text & Note Components"
                LetterN["LetterNote"]:::text
                LetterC["LetterCanvas"]:::text
                NoteP["NotePaper"]:::text
            end

            subgraph "UI Components"
                Toolbar["Toolbar"]:::ui
                Draggable["DraggableItem"]:::ui
                
                subgraph "Basic UI Elements"
                    Button["Button"]:::ui
                    Dialog["Dialog"]:::ui
                    Input["Input"]:::ui
                    Label["Label"]:::ui
                    Popover["Popover"]:::ui
                    Textarea["Textarea"]:::ui
                end
            end

            subgraph "Utility Components"
                Utils["Utilities"]:::util
                CD["CD Component"]:::util
                Mic["Microphone"]:::util
                Pencil["Pencil"]:::util
                Polaroid["Polaroid"]:::util
                DottedBg["Dotted Background"]:::util
            end
        end

        subgraph "Technical Integration"
            WebAudio["Web Audio API"]:::api
            CanvasAPI["Canvas API"]:::api
            DragDropAPI["Drag & Drop API"]:::api
            FileAPI["File System API"]:::api
        end

        subgraph "External Services"
            SpotifyAPI["Spotify Integration"]:::external
            FileStorage["File Storage"]:::external
        end
    end

    %% Component Interactions
    VoiceRec --> WebAudio
    Doodle --> CanvasAPI
    Draggable --> DragDropAPI
    PhotoUp --> FileAPI
    Spotify --> SpotifyAPI
    PhotoUp --> FileStorage

    %% Click Events
    click Layout "https://github.com/floguo/giftbox/blob/main/src/app/layout.tsx"
    click MainPage "https://github.com/floguo/giftbox/blob/main/src/app/page.tsx"
    click GlobalStyles "https://github.com/floguo/giftbox/blob/main/src/app/globals.css"
    click PhotoUp "https://github.com/floguo/giftbox/blob/main/src/components/photo-uploader.tsx"
    click PhotoItem "https://github.com/floguo/giftbox/blob/main/src/components/photo-item.tsx"
    click VoiceRec "https://github.com/floguo/giftbox/blob/main/src/components/voice-recorder.tsx"
    click VoiceNote "https://github.com/floguo/giftbox/blob/main/src/components/voice-note.tsx"
    click Spotify "https://github.com/floguo/giftbox/blob/main/src/components/spotify-player.tsx"
    click Doodle "https://github.com/floguo/giftbox/blob/main/src/components/doodle-drawer.tsx"
    click Waveform "https://github.com/floguo/giftbox/blob/main/src/components/waveform-visualizer.tsx"
    click LetterN "https://github.com/floguo/giftbox/blob/main/src/components/letter-note.tsx"
    click LetterC "https://github.com/floguo/giftbox/blob/main/src/components/letter-canvas.tsx"
    click NoteP "https://github.com/floguo/giftbox/blob/main/src/components/note-paper.tsx"
    click Toolbar "https://github.com/floguo/giftbox/blob/main/src/components/toolbar.tsx"
    click Draggable "https://github.com/floguo/giftbox/blob/main/src/components/draggable-item.tsx"
    click Button "https://github.com/floguo/giftbox/blob/main/src/components/ui/button.tsx"
    click Dialog "https://github.com/floguo/giftbox/blob/main/src/components/ui/dialog.tsx"
    click Input "https://github.com/floguo/giftbox/blob/main/src/components/ui/input.tsx"
    click Label "https://github.com/floguo/giftbox/blob/main/src/components/ui/label.tsx"
    click Popover "https://github.com/floguo/giftbox/blob/main/src/components/ui/popover.tsx"
    click Textarea "https://github.com/floguo/giftbox/blob/main/src/components/ui/textarea.tsx"
    click Utils "https://github.com/floguo/giftbox/blob/main/src/lib/utils.ts"
    click CD "https://github.com/floguo/giftbox/blob/main/src/components/cd.tsx"
    click Mic "https://github.com/floguo/giftbox/blob/main/src/components/microphone.tsx"
    click Pencil "https://github.com/floguo/giftbox/blob/main/src/components/pencil.tsx"
    click Polaroid "https://github.com/floguo/giftbox/blob/main/src/components/polaroid.tsx"
    click DottedBg "https://github.com/floguo/giftbox/blob/main/src/components/dotted-background.tsx"

    %% Styling
    classDef core fill:#2196F3,color:white
    classDef media fill:#FFC107,color:black
    classDef text fill:#4CAF50,color:white
    classDef ui fill:#9C27B0,color:white
    classDef util fill:#FF5722,color:white
    classDef api fill:#795548,color:white
    classDef external fill:#607D8B,color:white
```
