chore: initial commit

.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

.prettierrc.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  semi: true,
+  trailingComma: 'all',
+  singleQuote: true,
+  printWidth: 80,
+  tabWidth: 2,
+};

CONTRIBUTING.md

@@ -0,0 +1,266 @@
+# Project Development Guidelines
+
+**Version**: 1.0  
+**Last Updated**: July 1, 2025
+
+## 1\. Introduction
+
+This document provides the official guidelines for developing this application. Its purpose is to ensure a consistent, maintainable, and high-quality codebase. Adhering to these standards is mandatory for all contributors.
+
+---
+
+## 2\. Project Structure
+
+We use a **feature-based structure** to ensure modularity and scalability.
+
+```
+/
+├── src/
+│   ├── assets/
+│   ├── components/        # Only for shared components (e.g., App Layout, Button)
+│   ├── config/
+│   ├── contexts/
+│   ├── features/          # Main directory for all application features
+│   │   ├── authentication/
+│   │   │   ├── api/
+│   │   │   │   └── authAPI.ts
+│   │   │   ├── components/
+│   │   │   │   └── LoginForm.tsx
+│   │   │   ├── hooks/
+│   │   │   │   └── useAuth.ts
+│   │   │   ├── routes/
+│   │   │   │   └── LoginPage.tsx  # The main entry point for this feature's route
+│   │   │   └── types.ts
+│   │   │
+│   │   └── products/
+│   │       ├── api/
+│   │       │   └── productsAPI.ts
+│   │       ├── components/
+│   │       │   ├── ProductCard.tsx
+│   │       │   └── ProductGrid.tsx
+│   │       ├── routes/
+│   │       │   └── ProductListPage.tsx
+│   │       └── index.ts
+│   │
+│   ├── hooks/             # Only for global hooks
+│   ├── lib/               # For external library configurations (e.g., axios instance)
+│   ├── providers/         # A single place for all context providers
+│   ├── routes/            # Central route configuration
+│   │   └── index.tsx
+│   ├── types/             # Only for global types
+│   ├── App.tsx
+│   └── main.tsx
+│
+```
+
+- **`src/features/`**: All code related to a specific business feature (e.g., `authentication`, `products`, `user-profile`) resides within its own folder here. Each feature folder should contain its own `components`, `hooks`, `api`, `types`, and `routes`.
+- **`src/components/`**: This directory is **only** for truly generic, shared UI components that are used across multiple features (e.g., `Button`, `Layout`, `Logo`).
+- **`src/lib/`**: For configuring and exporting instances of third-party libraries (e.g., an `axios` client).
+- **`src/providers/`**: A single location to compose all React Context providers (`AuthProvider`, `ThemeProvider`, etc.).
+- **`src/routes/`**: The central routing configuration, which lazy-loads page components from the `features` directory.
+- **`src/theme/`**: Contains the MUI theme definition and global styles.
+
+---
+
+## 3\. Naming Conventions
+
+Consistent naming is critical for readability.
+
+- **Files**:
+  - **Components**: **`PascalCase.tsx`** (e.g., `ProductCard.tsx`)
+  - **Hooks**: **`useCamelCase.ts`** (e.g., `useDebounce.ts`)
+  - **All other `.ts` files**: **`camelCase.ts`** (e.g., `authService.ts`)
+
+- **Components**: **`PascalCase`**. The component function name must match the filename.
+
+  ```tsx
+  // src/components/SubmitButton.tsx
+  function SubmitButton() {
+    // ...
+  }
+  ```
+
+- **Variables and Functions**: **`camelCase`**.
+
+  ```typescript
+  const userCount = 10;
+  function getUserProfile() {
+    /* ... */
+  }
+  ```
+
+- **Constants**: **`UPPER_SNAKE_CASE`**. For constant values that are hardcoded and reused.
+
+  ```typescript
+  const MAX_LOGIN_ATTEMPTS = 5;
+  ```
+
+- **Types and Interfaces**: **`PascalCase`**.
+
+  ```typescript
+  interface UserProfile {
+    userId: string;
+    displayName: string;
+  }
+  ```
+
+---
+
+## 4\. Coding Best Practices
+
+- **Functional Components**: All components **must** be functional components using React Hooks. Class components are not permitted.
+- **TypeScript**: Use TypeScript's features to your advantage. Avoid `any` whenever possible. Define clear types and interfaces for props, API responses, and complex objects.
+- **Props**: Always define props with a `type` or `interface`. Use destructuring in the component signature for clarity.
+
+  ```tsx
+  interface UserCardProps {
+    name: string;
+    avatarUrl: string;
+  }
+
+  function UserCard({ name, avatarUrl }: UserCardProps) {
+    // ...
+  }
+  ```
+
+- **Imports**: Use absolute paths with the `@/` alias for cleaner imports.
+- **DRY (Don't Repeat Yourself)**: If you use a piece of logic more than twice, abstract it into a custom hook. If you use a piece of JSX more than twice, create a reusable component.
+
+---
+
+## 5\. State Management
+
+- **Local State**: `useState` and `useReducer` are the default choices for component-level state.
+- **Shared State**: For state that needs to be shared across the application (e.g., user authentication, theme), use the **React Context API**.
+
+---
+
+## 6\. Styling
+
+Styling is handled by **Material-UI (MUI)**.
+
+- For creating new, reusable, styled components, use the **`styled()` utility** from MUI.
+- For one-off style adjustments or layout overrides, use the **`sx` prop**.
+
+---
+
+## 7\. Component Documentation (Storybook)
+
+All shared UI components in the `src/components` directory **must** be documented using **Storybook**. This creates a living style guide, allows for isolated component development, and makes it easy for all developers to discover and use existing components.
+
+Each component folder should contain a `*.stories.tsx` file.
+
+---
+
+## 8\. Code Comments
+
+- **Comment the _Why_, Not the _What_**: Your code should be self-documenting. Use comments to explain _why_ a complex or non-obvious piece of code exists.
+
+  ```typescript
+  // Bad comment
+  // Increment the counter
+  counter++;
+
+  // Good comment
+  // We need to pre-increment the counter to account for the zero-based index of the array.
+  ++preemptiveCounter;
+  ```
+
+- **JSDoc**: Use JSDoc blocks for all exported functions and custom hooks to enable better editor IntelliSense.
+  ```typescript
+  /**
+   * Fetches a user profile from the API.
+   * @param userId - The ID of the user to fetch.
+   * @returns The user profile object or null if not found.
+   */
+  ```
+
+---
+
+## 9\. Git Workflow
+
+We use a simplified GitFlow model.
+
+1.  **Create a Branch**: All work must be done on a feature branch, named descriptively (e.g., `feat/login-page`, `fix/header-bug`).
+2.  **Commit Often**: Make small, logical commits. Commit messages **must** follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (e.g., `feat:`, `fix:`, `docs:`, `chore:`).
+3.  **Create a Pull Request (PR)**: When the feature is complete, create a PR against the `main` branch.
+4.  **Code Review**: At least one other team member must review and approve the PR.
+5.  **Merge**: Once approved and all checks pass, the PR can be merged.
+
+---
+
+## 10\. Pre-Commit Checklist
+
+Before creating a Pull Request, ensure you have:
+
+- ✅ Formatted the entire codebase: `npm run format`
+- ✅ Passed all linter checks: `npm run lint`
+- ✅ Documented any new shared components in Storybook.
+
+---
+
+## 11\. Design Patterns
+
+Design patterns are reusable solutions to common problems within a given context. Here are the key patterns we will use in this React project.
+
+### Component Design Patterns
+
+- **Container/Presentational Pattern (Smart/Dumb Components)**
+  - **Concept**: Separate the "how things work" from the "how things look."
+  - **Container (Smart) Component**: Manages state, fetches data, and contains business logic. It doesn't have many styles.
+  - **Presentational (Dumb) Component**: Receives data via props and simply renders UI. It contains no business logic.
+  - **Example**: A `UserProfilePage` (container) fetches user data and passes it to a `UserProfileCard` (presentational) to display.
+
+- **Composition Pattern**
+  - **Concept**: Build complex components by combining simpler, more generic ones. This is React's core philosophy.
+  - **Example**: Using the `children` prop to create a generic `Card` component that can wrap any content:
+  ```tsx
+  <Card>
+    <h2>Title</h2>
+    <p>Content</p>
+  </Card>
+  ```
+
+### State Management Patterns
+
+- **Provider Pattern**
+  - **Concept**: Make data available to a deep tree of components without having to pass props down manually at every level.
+  - **How we use it**: This is the pattern that powers the React Context API. Our `AuthProvider`, `ThemeProvider`, and `CustomThemeProvider` all use this pattern to provide authentication status and theme information to any component that needs it.
+
+### Reusable Logic Patterns
+
+- **Custom Hooks**
+  - **Concept**: The modern, standard way to share stateful logic between components.
+  - **How we use it**: By extracting logic into a function whose name starts with `use` (e.g., `useAuth`, `useTheme`), we can reuse that logic in any component without repeating code. This is the preferred replacement for older patterns like HOCs and Render Props.
+
+### Memoization Pattern
+
+  * **Concept**: A performance optimization technique to prevent unnecessary re-renders and expensive re-calculations by caching results. React provides three main tools for this.
+
+  * **Best For**: Improving the performance of applications with complex components, large lists, or frequent state updates.
+
+  * **The Tools**:
+
+      * **`React.memo`**: A higher-order component that prevents a component from re-rendering if its props haven't changed.
+      * **`useMemo`**: A hook that caches the result of an expensive calculation. It only re-computes the value when its dependencies change.
+      * **`useCallback`**: A hook that caches a function definition. This is useful for preventing child components from re-rendering when you pass functions down as props.
+
+
+### Custom Data Fetching Hook
+
+  * **Concept**: A custom hook that abstracts all the logic for fetching data from an API. It typically manages the loading, error, and data states internally.
+
+  * **Best For**: Simplifying data fetching in your components, eliminating repetitive `useEffect` logic, and creating a consistent way to handle API requests across your app.
+
+  * **How it looks**: Components become much cleaner and focused on displaying the data.
+
+    ```tsx
+    function UserProfile({ userId }) {
+      const { data: user, isLoading, error } = useFetch(`/api/users/${userId}`);
+
+      if (isLoading) return <div>Loading...</div>;
+      if (error) return <div>Error fetching data!</div>;
+
+      return <div>{user.name}</div>;
+    }
+    ```

eslint.config.js

@@ -0,0 +1,65 @@
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import prettier from 'eslint-plugin-prettier';
+import prettierConfig from 'eslint-config-prettier';
+
+export default tseslint.config(
+  {
+    ignores: ['dist/', 'node_modules/'],
+  },
+
+  // Configuration for your React application source code
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        // This is the most critical fix: point to the config that INCLUDES the src files.
+        project: './tsconfig.app.json',
+        ecmaFeatures: { jsx: true },
+      },
+      globals: {
+        ...globals.browser,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint.plugin,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+      prettier: prettier,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      ...reactHooks.configs.recommended.rules,
+      ...prettierConfig.rules,
+      'prettier/prettier': 'error',
+      'react-refresh/only-export-components': 'warn',
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+
+  // Configuration for project-level config files
+  {
+    files: ['eslint.config.ts', 'vite.config.ts'],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        project: './tsconfig.node.json',
+      },
+      globals: {
+        ...globals.node,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint.plugin,
+      prettier: prettier,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      ...prettierConfig.rules,
+      'prettier/prettier': 'error',
+    },
+  },
+);

index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <!-- <link rel="icon" type="image/svg+xml" href="/vite.svg" /> -->
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Harmony club</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package.json

@@ -0,0 +1,35 @@
+{
+  "name": "harmony-club",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
+    "@vitejs/plugin-react": "^4.5.2",
+    "eslint": "^9.30.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.5.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.2.0",
+    "prettier": "^3.6.2",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "vite": "^7.0.0"
+  }
+}

src/App.tsx

@@ -0,0 +1,7 @@
+import './App.css';
+
+function App() {
+  return <div>PlaceHolder</div>;
+}
+
+export default App;

src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './index.css';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

tsconfig.app.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    /* Base Options */
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+
+    /* Bundler & Module Resolution */
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+
+    /* Strictness & Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    /* Path Aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}

tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

tsconfig.node.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    /* Base Options */
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler & Module Resolution */
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+
+    /* Strictness & Linting */
+    "strict": true
+  },
+  "include": ["vite.config.ts", "eslint.config.ts"]
+}

vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+});