portfolio-page/.github/copilot-instructions.md

Portfolio Codebase Instructions

Architecture Overview

This is a React + TypeScript portfolio website with a unique modular SCSS theme system and full-stack contact functionality. The project follows a strict separation between presentation (React components), styling (SCSS modules), configuration (TypeScript configs), and data models.

Key Architectural Patterns

• Theme-driven SCSS: All styling uses CSS custom properties via @include t.theme-vars() in src/scss/themes/. Never hardcode colors - use theme variables.
• Configuration-driven content: Personal info, texts, and data models live in src/config/ and src/data/ - modify these instead of components for content changes.
• Hash-based navigation: Uses React Router with hash fragments (#about, #projects) for smooth scrolling between sections on the homepage.
• Centralized personal data: All contact info, social links, and professional details in src/config/personal.ts.

Critical Development Workflows

Development Setup

npm run dev          # Start Vite dev server
npm run build        # TypeScript compile + Vite build
npm run deploy       # Build + custom SFTP deployment via deploy.js

Theme System Workflow

1. Define theme variables in src/scss/themes/_base.scss (light) and corresponding dark theme
2. Import themes via src/scss/themes/_index.scss
3. Apply themes with @include t.theme-vars(t.$light-theme) in components
4. Theme switching handled by AppRouter.tsx via data-theme attribute

Backend Integration

• Contact form uses Node.js/Express backend in backend/ directory
• GDPR-compliant with rate limiting, validation, and email obfuscation
• Email service via Nodemailer with Gmail SMTP (configured via .env)

Project-Specific Conventions

File Organization

• Components: src/components/sections/ for page sections, src/components/layout/ for navigation/footer
• Styling: Mirror component structure in src/scss/sections/ and src/scss/layout/
• Data Models: TypeScript interfaces in src/data/ (Project.ts, Skill.ts, etc.)
• Configuration: All content configuration in src/config/ (personal.ts, texts.ts, api.ts)

SCSS Architecture

// Always use theme variables - example from any component:
@use '../../scss/themes/index' as t;

.component {
  background: var(--background);
  color: var(--text);
  box-shadow: var(--shadow-card);
}

Data Model Pattern

• All content interfaces defined in src/data/
• Use src/config/texts.ts for all displayable text (i18n preparation)
• Personal/contact data centralized in src/config/personal.ts with helper functions

Component Props Pattern

// All sections follow this pattern for text overrides:
interface SectionProps {
  title?: string; // Allow text overrides
  subtitle?: string; // for customization
}

export default function Section(props: SectionProps = {}) {
  const texts = getTexts().sectionName;
  const { title = texts.title, subtitle = texts.subtitle } = props;
}

Integration Points

Theme System Integration

• AppRouter.tsx manages global theme state and localStorage persistence
• Theme switching via CSS custom properties, not CSS-in-JS
• All components must use theme variables, never hardcoded colors

Contact Form Flow

1. Frontend form in ContactSection.tsx
2. Validates and posts to /api/contact endpoint
3. Backend in backend/routes/contact.js handles GDPR compliance, rate limiting, validation
4. Email sent via backend/services/emailService.js using Nodemailer

Deployment Process

• Custom SFTP deployment via deploy.js script
• Prompts for credentials, uploads dist/ contents
• Vercel config available as alternative in vercel.json

Common Pitfalls

• Never bypass theme variables - always use CSS custom properties from theme system
• Don't edit component text directly - update src/config/texts.ts instead
• Personal data changes - modify src/config/personal.ts, not component files
• SCSS imports - use @use not @import for better performance and scoping
• Hash navigation - remember hash-based routing for section navigation on homepage

Key Files for AI Context

• src/app/AppRouter.tsx - Theme management and routing logic
• src/config/personal.ts - All personal/professional data
• src/scss/themes/_base.scss - Theme variable definitions
• backend/routes/contact.js - Contact form API with GDPR compliance
• deploy.js - Custom deployment automation