auto-claude: subtask-1-1 - Create CONTRIBUTING.md with project overview and development setup

2026-01-25 06:30:54 +01:00
parent eec1758827
commit 4ef3b4267d
1 changed files with 374 additions and 0 deletions
@@ -0,0 +1,374 @@
 # Contributing to Portfolio
 Thank you for your interest in contributing to this project! This guide will help you get started with development.
 ## Table of Contents
 - [Getting Started](#getting-started)
 - [Project Overview](#project-overview)
 - [Tech Stack](#tech-stack)
 - [Project Structure](#project-structure)
 - [Development Workflow](#development-workflow)
 - [Code Style & Standards](#code-style--standards)
 - [Testing](#testing)
 - [Commit Guidelines](#commit-guidelines)
 ## Getting Started
 ### Prerequisites
 - **Node.js** 18.x or higher
 - **npm** 9.x or higher
 - **Git** for version control
 ### Installation
 1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd portfolio
   ```
 2. **Install dependencies**
   ```bash
   npm install
   ```
 3. **Set up environment variables**
   Create a `.env.local` file in the root directory with the required environment variables:
   ```bash
   # Supabase Configuration
   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
   # Optional: OpenAI (for image generation scripts)
   OPENAI_API_KEY=your_openai_api_key
   ```
 4. **Start the development server**
   ```bash
   npm run dev
   ```
   The application will be available at `http://localhost:3000`
 ### Available Scripts
 | Command | Description |
 |---------|-------------|
 | `npm run dev` | Start development server with hot reload |
 | `npm run build` | Build production bundle |
 | `npm start` | Start production server (after build) |
 | `npm run lint` | Run ESLint with strict mode |
 | `npm test` | Run unit tests with Vitest |
 | `npm run test:coverage` | Run tests with coverage report |
 | `npm run build:images` | Optimize images using Sharp |
 | `npm run generate:images` | Generate blog images using OpenAI |
 | `npm run generate:images:dry` | Preview image generation without creating files |
 ## Project Overview
 This is a personal portfolio website for Damjan Savić, showcasing work as an AI & Automation Specialist. The site features:
 - **Multi-language support** - German, English, and Serbian with automatic language detection
 - **Progressive Web App** - Installable and offline-capable
 - **SEO optimized** - Structured data (Schema.org), sitemap generation
 - **Responsive Design** - Mobile-first approach with Tailwind CSS
 - **Blog System** - MDX-based content with frontmatter support
 - **Portfolio Gallery** - Dynamic project showcase with filtering
 - **Contact Form** - Integrated with Supabase backend
 ## Tech Stack
 ### Core Framework
 - **Next.js 15** - React framework with App Router
 - **React 19** - UI library with latest features
 - **TypeScript 5.5** - Type-safe development
 ### Styling & UI
 - **Tailwind CSS 3.4** - Utility-first CSS framework
 - **Framer Motion 11** - Animation library
 - **Lucide React** - Icon library
 - **Tailwind Merge** - Utility for merging Tailwind classes
 - **CVA (Class Variance Authority)** - Component variants management
 ### Content & Internationalization
 - **MDX** - Markdown + JSX for content pages
  - `@mdx-js/loader`, `@mdx-js/mdx`, `@mdx-js/react`
  - `@next/mdx`, `next-mdx-remote`
 - **next-intl 3.26** - Internationalization (i18n)
 - **gray-matter** - Frontmatter parsing
 ### Backend & Services
 - **Supabase** - Database, authentication, and backend services
  - `@supabase/supabase-js`
  - `@supabase/ssr`
 - **OpenAI 4.77** - AI integration for content generation
 ### Development Tools
 - **Vitest** - Unit testing framework
 - **ESLint 9** - Code linting with Next.js config
 - **PostCSS** - CSS processing
 - **Autoprefixer** - CSS vendor prefixes
 - **Sharp** - Image optimization
 ### Performance & Analytics
 - **web-vitals** - Performance metrics
 - **react-intersection-observer** - Lazy loading and scroll animations
 ## Project Structure
 ```
 portfolio/
 ├── public/                    # Static assets (images, fonts, etc.)
 ├── scripts/                   # Build and utility scripts
 │   ├── optimize-images.js     # Image optimization
 │   └── generate-blog-images.mjs # AI-powered image generation
 ├── src/
 │   ├── app/                   # Next.js App Router
 │   │   ├── [locale]/          # Internationalized routes
 │   │   │   ├── about/         # About page
 │   │   │   ├── blog/          # Blog listing & posts
 │   │   │   ├── contact/       # Contact form
 │   │   │   ├── dashboard/     # Admin dashboard
 │   │   │   ├── imprint/       # Legal imprint
 │   │   │   ├── leistungen/    # Services page
 │   │   │   ├── login/         # Authentication
 │   │   │   ├── portfolio/     # Portfolio gallery & projects
 │   │   │   ├── privacy/       # Privacy policy
 │   │   │   ├── terms/         # Terms of service
 │   │   │   ├── layout.tsx     # Locale-specific layout
 │   │   │   └── page.tsx       # Homepage
 │   │   ├── globals.css        # Global styles
 │   │   ├── layout.tsx         # Root layout
 │   │   ├── not-found.tsx      # 404 page
 │   │   ├── robots.ts          # Robots.txt generation
 │   │   └── sitemap.ts         # Sitemap generation
 │   ├── components/            # Reusable React components
 │   ├── components-vite/       # Legacy Vite components
 │   ├── data/                  # Static data and content
 │   ├── hooks/                 # Custom React hooks
 │   ├── i18n/                  # Internationalization config
 │   ├── lib/                   # Utility libraries and helpers
 │   ├── messages/              # Translation files (de, en, sr)
 │   ├── middleware.ts          # Next.js middleware (i18n routing)
 │   ├── pages-vite/            # Legacy Vite pages
 │   ├── services/              # API and service integrations
 │   ├── styles/                # Additional styles
 │   ├── types/                 # TypeScript type definitions
 │   └── utils/                 # Helper functions
 ├── .env.local                 # Environment variables (not in git)
 ├── .eslintrc.json             # ESLint configuration
 ├── docker-compose.yml         # Docker Compose setup
 ├── Dockerfile                 # Docker container config
 ├── next.config.ts             # Next.js configuration
 ├── package.json               # Dependencies and scripts
 ├── postcss.config.js          # PostCSS configuration
 ├── tailwind.config.js         # Tailwind CSS configuration
 └── tsconfig.json              # TypeScript configuration
 ```
 ### Key Directories Explained
 - **`src/app/`** - Next.js App Router pages and layouts using the new file-based routing system
 - **`src/app/[locale]/`** - All pages are nested under locale for multi-language support (de, en, sr)
 - **`src/components/`** - Reusable UI components (buttons, cards, forms, navigation, etc.)
 - **`src/hooks/`** - Custom React hooks for shared logic
 - **`src/lib/`** - Utility libraries (Supabase client, helpers, etc.)
 - **`src/messages/`** - Translation JSON files for each language
 - **`src/services/`** - API integrations and external service wrappers
 - **`src/types/`** - TypeScript interfaces and type definitions
 - **`src/utils/`** - Helper functions and utilities
 - **`public/`** - Static files served directly (images, fonts, favicons)
 - **`scripts/`** - Build automation and utility scripts
 ## Development Workflow
 ### 1. Create a New Feature Branch
 ```bash
 git checkout -b feature/your-feature-name
 ```
 ### 2. Make Your Changes
 - Follow the existing code patterns and structure
 - Use TypeScript for type safety
 - Write clean, readable code with appropriate comments
 - Test your changes locally
 ### 3. Test Your Changes
 ```bash
 # Run development server
 npm run dev
 # Run linter
 npm run lint
 # Run tests
 npm test
 ```
 ### 4. Build for Production
 ```bash
 npm run build
 ```
 Ensure the build completes without errors before submitting.
 ## Code Style & Standards
 ### TypeScript
 - Use TypeScript for all new files
 - Define proper types and interfaces
 - Avoid using `any` - use proper typing or `unknown`
 - Export types from a central `types/` directory when shared
 ### React Components
 - Use functional components with hooks
 - Follow the component structure:
  1. Imports
  2. Type definitions
  3. Component definition
  4. Helper functions (if needed)
  5. Exports
 Example:
 ```typescript
 import { useState } from 'react';
 import { Button } from '@/components/ui/Button';
 interface MyComponentProps {
  title: string;
  onSubmit: () => void;
 }
 export function MyComponent({ title, onSubmit }: MyComponentProps) {
  const [isLoading, setIsLoading] = useState(false);
  const handleClick = async () => {
    setIsLoading(true);
    await onSubmit();
    setIsLoading(false);
  };
  return (
    <div>
      <h2>{title}</h2>
      <Button onClick={handleClick} disabled={isLoading}>
        Submit
      </Button>
    </div>
  );
 }
 ```
 ### Styling
 - Use Tailwind CSS utility classes
 - Use `cn()` utility from `tailwind-merge` to merge classes
 - Follow the mobile-first responsive design approach
 - Use CSS variables for theme colors (defined in `globals.css`)
 ### File Naming
 - Components: PascalCase (e.g., `MyComponent.tsx`)
 - Utilities: camelCase (e.g., `formatDate.ts`)
 - Pages: lowercase (e.g., `page.tsx`, `layout.tsx`)
 - Types: PascalCase with `.types.ts` suffix (e.g., `User.types.ts`)
 ### Import Organization
 ```typescript
 // 1. External dependencies
 import { useState } from 'react';
 import { useTranslations } from 'next-intl';
 // 2. Internal components and utilities
 import { Button } from '@/components/ui/Button';
 import { formatDate } from '@/utils/date';
 // 3. Types
 import type { User } from '@/types/User.types';
 // 4. Styles (if any)
 import styles from './Component.module.css';
 ```
 ### Internationalization
 - All user-facing text must be internationalized
 - Use `useTranslations()` hook from `next-intl`
 - Add translation keys to all language files in `src/messages/`
 Example:
 ```typescript
 import { useTranslations } from 'next-intl';
 export function WelcomeMessage() {
  const t = useTranslations('home');
  return <h1>{t('welcome')}</h1>;
 }
 ```
 ## Testing
 ### Unit Tests
 - Write tests for utility functions and complex logic
 - Use Vitest as the testing framework
 - Place test files next to the code they test with `.test.ts` or `.test.tsx` extension
 Example:
 ```typescript
 // formatDate.test.ts
 import { describe, it, expect } from 'vitest';
 import { formatDate } from './formatDate';
 describe('formatDate', () => {
  it('formats date correctly', () => {
    const date = new Date('2024-01-15');
    expect(formatDate(date)).toBe('15.01.2024');
  });
 });
 ```
 ### Running Tests
 ```bash
 # Run tests in watch mode
 npm test
 # Run tests once with coverage
 npm run test:coverage
 ```
 ## Commit Guidelines
 ### Commit Message Format
 ```
 <type>: <subject>
 <body>
 ```
 ### Types
 - `feat` - New feature
 - `fix` - Bug fix
 - `docs` - Documentation changes
 - `style` - Code style changes (formatting, etc.)
 - `refactor` - Code refactoring
 - `test` - Adding or updating tests
 - `chore` - Maintenance tasks
 ### Examples
 ```bash
 git commit -m "feat: add contact form validation"
 git commit -m "fix: resolve mobile navigation menu bug"
 git commit -m "docs: update README with deployment instructions"
 ```
 ## Questions?
 If you have any questions or need help, please:
 - Check existing documentation
 - Review similar code in the codebase
 - Open an issue for discussion
 ---
 **Built with Next.js + TypeScript + Tailwind CSS**