116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```scss
|
|
// 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
|
|
|
|
```tsx
|
|
// 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
|