chore: adding test and refactor sequence executor (#61)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Introduced a detailed UX structure map for a Spotify-like music web
application, outlining key components and navigation for various pages.
- Added structured documentation for the backend project, detailing
directory layouts and file purposes.
- Integrated new handlers for UX sitemap and data mapping
functionalities.
- Implemented a new `FileStructureHandler` to generate file structure
documents based on project context.

- **Bug Fixes**
- Ensured logging functionality is accessible throughout the
`BuilderContext` class.

- **Tests**
- Added test suites for validating build sequences and file architecture
generation.

- **Refactor**
- Converted instance methods to static methods in the
`BuildSequenceExecutor` class to enhance modularity.
- Updated interface properties in `BuildBase` and `BuildNode` to be
optional for greater flexibility.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: ZHallen122 <[email protected]>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

backend/.gitignore

@@ -48,3 +48,6 @@ pids
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# log files with timestamp
+log-*/

backend/package.json

@@ -77,4 +77,4 @@
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.1.3"
   }
-}
+}

backend/src/build-system/__tests__/datamap-structure.md

@@ -0,0 +1,275 @@
+# Detailed UX Structure Map: Spotify-like Music Web Application
+
+## **1. Home Page**
+
+### Page Purpose
+
+Provide users with quick access to featured playlists, personalized recommendations, new releases, and music genres.
+
+### Core Elements
+
+- **Header**:
+  - Logo: Navigate back to the home page.
+  - Search Bar: Quick access to search functionality.
+  - Navigation Links: Home, Search, Library, Account.
+- **Main Content Area**:
+  - **Featured Playlists**: Grid of curated playlists with cover images and titles.
+    - Interactions: Click to navigate to the playlist page.
+  - **Personalized Recommendations**: Horizontal scroll carousel of songs and albums tailored to the user.
+    - Dynamic Content: Updates based on user listening history.
+  - **New Releases**: Grid displaying recently released albums or singles.
+    - Interactions: Click to open album details.
+  - **Genres**: List of genres represented as clickable tiles.
+- **Footer**:
+  - Persistent music player bar with play/pause, skip, and volume controls.
+
+### Content Display
+
+- Visual hierarchy prioritizing featured content and recommendations.
+- Dynamic updates to reflect user preferences and real-time data.
+
+### Navigation and Routes
+
+- `/home`: Main route for the home page.
+- Links to `/playlist/:id`, `/album/:id`, `/genre/:id`.
+
+### Restrictions
+
+- Requires user login to display personalized recommendations.
+
+---
+
+## **2. Search Page**
+
+### Page Purpose
+
+Allow users to search for specific songs, albums, artists, or playlists and view categorized results.
+
+### Core Elements
+
+- **Header**:
+  - Logo, Navigation Links, and Search Bar (persistent from Home Page).
+- **Search Results Section**:
+  - **Songs**: List of matching songs with play buttons.
+  - **Albums**: Grid of albums with cover art and titles.
+  - **Artists**: Horizontal scroll carousel of artists.
+  - **Playlists**: List of curated and user-created playlists.
+- **No Results Message**: Display when no matching content is found.
+
+### Content Display
+
+- Results categorized and clearly separated.
+- Real-time search suggestions displayed as user types.
+
+### Navigation and Routes
+
+- `/search`: Search page route.
+- Links to `/song/:id`, `/album/:id`, `/artist/:id`, `/playlist/:id`.
+
+### Restrictions
+
+- Accessible without login but limited to generic content unless logged in.
+
+---
+
+## **3. Library Page**
+
+### Page Purpose
+
+Provide users access to their playlists, liked songs, and recently played music.
+
+### Core Elements
+
+- **Header**:
+  - Persistent header with navigation and search.
+- **Library Sections**:
+  - **My Playlists**: List of user-created playlists.
+    - Actions: Edit, delete, reorder.
+  - **Liked Songs**: List of favorited songs with play buttons.
+  - **Recently Played**: List of previously played songs and playlists.
+
+### Content Display
+
+- Organize content with clear sections and labels.
+- Show metadata (e.g., song duration, artist) for user context.
+
+### Navigation and Routes
+
+- `/library`: Library main page route.
+- Links to `/playlist/:id`, `/song/:id`.
+
+### Restrictions
+
+- Requires login to access user-specific content.
+
+---
+
+## **4. Playlist/Album/Genre Pages**
+
+### Page Purpose
+
+Allow users to view and play content within a specific playlist, album, or genre.
+
+### Core Elements
+
+- **Header**:
+  - Back Button: Navigate to the previous page.
+  - Playlist/Album/Genre Name: Display prominently.
+- **Content Section**:
+  - **Playlist/Album Info**: Cover art, title, creator name, description.
+  - **Track List**: List of songs with play buttons and metadata.
+  - **Action Buttons**:
+    - Play All: Start playing all tracks in order.
+    - Add to Library: Save playlist/album to user library (if applicable).
+- **Footer**:
+  - Persistent music player bar.
+
+### Content Display
+
+- Highlight album or playlist cover and metadata for context.
+- Easy access to play all tracks or individual songs.
+
+### Navigation and Routes
+
+- `/playlist/:id`, `/album/:id`, `/genre/:id`.
+
+### Restrictions
+
+- Accessible without login, but restricted to sample tracks if not logged in.
+
+---
+
+## **5. Player Page (Now Playing)**
+
+### Page Purpose
+
+Provide full controls for the currently playing track.
+
+### Core Elements
+
+- **Header**:
+  - Back Button: Navigate to the previous page.
+- **Main Player Controls**:
+  - Song Info: Display song title, artist, album cover.
+  - Play/Pause, Skip, Seek Bar, Volume Controls.
+- **Lyrics Section**:
+  - Toggle to view lyrics for the current track (if available).
+- **Queue Section**:
+  - List of upcoming tracks with reordering options.
+
+### Content Display
+
+- Centralized focus on the current track with controls easily accessible.
+
+### Navigation and Routes
+
+- `/player`.
+
+### Restrictions
+
+- Requires active playback session.
+
+---
+
+## **6. Account Page**
+
+### Page Purpose
+
+Allow users to manage profile settings and preferences.
+
+### Core Elements
+
+- **Header**:
+  - Persistent navigation and search.
+- **Profile Info Section**:
+  - Display user profile details (username, email).
+  - Edit button for updating profile.
+- **Preferences Section**:
+  - Toggle for dark mode/light mode.
+  - Audio quality selection.
+- **Logout Button**:
+  - Prominent button to securely log out.
+
+### Content Display
+
+- Clear sections for profile details and app preferences.
+- Easy access to frequently updated settings.
+
+### Navigation and Routes
+
+- `/account`.
+
+### Restrictions
+
+- Requires login.
+
+---
+
+## **7. Onboarding Pages**
+
+### Page Purpose
+
+Guide new users through account setup and app features.
+
+### Core Elements
+
+- **Welcome Screen**:
+  - Brief intro to the app.
+  - Buttons to log in or sign up.
+- **Sign-Up Page**:
+  - Fields for username, email, password.
+  - Option to sign up via Google or Facebook.
+- **Login Page**:
+  - Username and password fields.
+  - Forgot Password link.
+
+### Content Display
+
+- Minimal text to streamline onboarding.
+- Prominent call-to-action buttons.
+
+### Navigation and Routes
+
+- `/welcome`, `/signup`, `/login`.
+
+### Restrictions
+
+- Accessible to all users without restrictions.
+
+---
+
+## **8. Error and Offline Pages**
+
+### Page Purpose
+
+Provide feedback for errors and offline scenarios.
+
+### Core Elements
+
+- **404 Page**:
+  - Message indicating content not found.
+  - Button to return to Home.
+- **Offline Mode**:
+  - Notification about internet connectivity issues.
+  - Limited access to downloaded or cached content.
+
+### Content Display
+
+- Clear messaging and actionable steps for users.
+
+### Navigation and Routes
+
+- `/404`, `/offline`.
+
+### Restrictions
+
+- Accessible in all scenarios.
+
+---
+
+## **Dynamic Content and Restrictions Summary**
+
+- **Dynamic Content**:
+  - Recommendations, playlists, recently played, and search results update in real-time based on user activity.
+- **Restrictions**:
+  - Login required for personalized content, library access, and playback history.

backend/src/build-system/__tests__/file-structure-document.md

@@ -0,0 +1,77 @@
+src/
+├── api/ # API logic for interacting with backend services
+│ ├── auth.ts # Authentication API logic
+│ ├── music.ts # API for music-related actions (e.g., fetching playlists, songs)
+│ ├── user.ts # API for user-related actions (e.g., profile updates)
+│ └── index.ts # Exports all API modules for centralized access
+├── components/ # Reusable UI components
+│ ├── common/ # Generic components used across the app
+│ │ ├── Button/ # Button component folder
+│ │ │ ├── index.tsx # Main Button component file
+│ │ │ └── index.css # Button-specific styles
+│ │ ├── Input/ # Input field component folder
+│ │ │ ├── index.tsx # Main Input component file
+│ │ │ └── index.css # Input-specific styles
+│ │ ├── Modal/ # Modal component folder
+│ │ │ ├── index.tsx # Main Modal component file
+│ │ │ └── index.css # Modal-specific styles
+│ ├── layout/ # Components for layout and structure
+│ │ ├── Header/ # Header component folder
+│ │ │ ├── index.tsx # Main Header component file
+│ │ │ └── index.css # Header-specific styles
+│ │ ├── Footer/ # Footer component folder
+│ │ │ ├── index.tsx # Main Footer component file
+│ │ │ └── index.css # Footer-specific styles
+│ ├── specific/ # Page-specific components
+│ │ ├── Home/ # Components specific to the Home page
+│ │ │ ├── FeaturedPlaylists.tsx # Component for featured playlists section
+│ │ │ ├── Recommendations.tsx # Component for personalized recommendations
+│ │ │ └── NewReleases.tsx # Component for new releases
+│ │ ├── Search/ # Components specific to the Search page
+│ │ │ ├── SearchResults.tsx # Component for displaying search results
+│ │ │ └── Autocomplete.tsx # Component for search suggestions
+│ │ ├── Library/ # Components specific to the Library page
+│ │ │ ├── MyPlaylists.tsx # Component for user playlists
+│ │ │ ├── LikedSongs.tsx # Component for liked songs
+│ │ │ └── RecentlyPlayed.tsx # Component for recently played songs
+├── contexts/ # Context providers for global state
+│ ├── AuthContext.tsx # Provides user authentication state
+│ ├── ThemeContext.tsx # Provides theme (dark/light mode) state
+│ ├── PlayerContext.tsx # Provides music player state and controls
+│ └── index.ts # Centralized export for contexts
+├── hooks/ # Custom hooks for data fetching and state management
+│ ├── useAuth.ts # Hook for user authentication logic
+│ ├── usePlayer.ts # Hook for controlling the music player
+│ ├── useTheme.ts # Hook for managing theme preferences
+│ └── useFetch.ts # Generic hook for data fetching
+├── pages/ # Route-specific views
+│ ├── Home/ # Home page folder
+│ │ ├── index.tsx # Main Home page component
+│ │ └── index.css # Home page-specific styles
+│ ├── Search/ # Search page folder
+│ │ ├── index.tsx # Main Search page component
+│ │ └── index.css # Search page-specific styles
+│ ├── Library/ # Library page folder
+│ │ ├── index.tsx # Main Library page component
+│ │ └── index.css # Library page-specific styles
+│ ├── Playlist/ # Playlist page folder
+│ │ ├── index.tsx # Main Playlist page component
+│ │ └── index.css # Playlist page-specific styles
+│ ├── Account/ # Account page folder
+│ │ ├── index.tsx # Main Account page component
+│ │ └── index.css # Account page-specific styles
+│ ├── Player/ # Player page folder
+│ │ ├── index.tsx # Main Player page component
+│ │ └── index.css # Player page-specific styles
+│ ├── Error/ # Error and Offline pages folder
+│ │ ├── NotFound.tsx # 404 Page component
+│ │ ├── Offline.tsx # Offline mode page component
+│ │ └── index.css # Styles for error pages
+├── utils/ # Utility functions
+│ ├── constants.ts # Application-wide constants
+│ ├── helpers.ts # Helper functions
+│ ├── validators.ts # Validation logic
+│ └── index.ts # Centralized export for utilities
+├── router.ts # Central routing configuration
+├── index.tsx # Application entry point
+└── App.tsx # Main application component