TechPioneers

📖 About The Project

TechPioneers is a portfolio project demonstrating modern frontend development skills, professional workflows, and best practices. The website features:

• Featured Pioneers: Highlighting 4 key figures who revolutionized technology
• More Pioneers: Exploring 6 additional innovators with detailed modal views
• Historical Timeline: A visual journey through tech evolution milestones
• Curated Resources: External references for learning more about tech history

This project showcases expertise in vanilla JavaScript, responsive design, accessibility, and DevOps practices.

✨ Features

• 🎨 Dual Themes: Light and dark mode with seamless transitions
• 📱 Fully Responsive: Optimized for mobile, tablet, and desktop devices
• ♿ Accessible: WCAG 2.1 Level AA compliant with keyboard navigation
• 🎪 Custom Carousel: Vanilla JavaScript implementation with touch support
• 🎭 Modal System: Interactive pioneer details with focus management
• ✨ Smooth Animations: Scroll-triggered effects and micro-interactions
• 🚀 Performance Optimized: Lighthouse score 90+ across all metrics
• 🐳 Dockerized: Multi-stage builds for development and production

🛠️ Built With

Core Technologies

• HTML5 - Semantic markup with accessibility features
• CSS3 - Modern styling with BEM methodology
• JavaScript (ES6+) - Vanilla JavaScript (no frameworks)
• Vite - Next-generation frontend build tool

Development Tools

• ESLint - JavaScript linting and code quality
• Prettier - Code formatting
• Husky - Git hooks for pre-commit checks

DevOps & Deployment

• Docker - Containerization and environment management
• GitHub Actions - CI/CD pipelines
• Google Cloud Run - Serverless deployment platform

Design

• Figma - Custom design system and assets

🚀 Getting Started

Prerequisites

• Node.js (v24 or higher)
• npm (v9 or higher)
• Docker (v20 or higher) - for containerized development
• Git (v2.30 or higher)

Installation

1. Clone the repository

   git clone https://github.com/M-oliveda/tech-pioneers_web.git
   cd tech-pioneers_web
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   cp .env.example .env
   

4. Run the development server

   • Option A: Without Docker (Quick Start)

   npm run dev
   

   Open http://localhost:5173 in your browser.

   • Option B: With Docker (Recommended)

   docker compose up --build -d
   

   Open http://localhost:5173 in your browser.

---

💻 Development

Available Scripts

Command	Description
npm run dev	Start development server with hot reload
npm run build	Build production-ready bundle
npm run preview	Preview production build locally
npm run lint	Run ESLint to check code quality
npm run lint:fix	Fix auto-fixable ESLint errors
npm run format	Format code with Prettier
npm run format:check	Check code formatting without changes

Docker Commands

Note: Docker is used exclusively for local development. Cloud environments (Preview, Development, Staging, Production) are deployed directly to Google Cloud Run via GitHub Actions.

Local Development

Command	Description
docker compose up --build	Start development environment (foreground)
docker compose up -d	Start development environment (detached)
docker compose logs -f	View live logs
docker compose down	Stop and remove containers
docker compose restart web	Restart the web service
docker compose exec web sh	Open shell inside container

Environment File: Local development uses .env for environment variables

Building Production Image Locally (Testing Only)

To test the production build locally before deploying:

# Build production image
docker build --target production -t techpioneers:prod .

# Run production image locally
docker run -p 8080:80 techpioneers:prod

# Access at http://localhost:8080

Project Structure

techpioneers/
├── .github/
│   └── workflows/
│       ├── pr-test.yml              # PR validation workflow
│       ├── deploy-preview.yml       # Auto-deploy to preview (PR environments)
│       ├── cleanup-preview.yml      # Cleanup preview environments on PR close
│       ├── deploy-development.yml   # Auto-deploy to development (develop branch)
│       ├── deploy-staging.yml       # Auto-deploy to staging (release/* branches)
│       └── deploy-production.yml    # Deploy to production (main + manual approval)
├── .husky/
│   ├── pre-commit                   # Pre-commit hooks
│   └── commit-msg                   # Commit message validation
├── public/
│   ├── icon.svg                     # Modern icon (light/dark mode)
│   ├── apple-icon.png               # Apple touch icon
│   ├── favicon.ico                  # Fallback favicon
│   └── assets/
│       ├── images/                  # Pioneer photos, hero background
│       └── icons/                   # Timeline, resources icons
├── src/
│   ├── css/
│   │   ├── main.css                 # Main stylesheet entry
│   │   ├── base/
│   │   │   ├── reset.css            # CSS reset
│   │   │   ├── typography.css       # Font styles
│   │   │   └── variables.css        # CSS custom properties (themes)
│   │   ├── components/
│   │   │   ├── header.css           # Header styles
│   │   │   ├── hero.css             # Hero section
│   │   │   ├── pioneer-card.css     # Card component (BEM)
│   │   │   ├── carousel.css         # Carousel component
│   │   │   ├── modal.css            # Modal component
│   │   │   ├── timeline.css         # Timeline component
│   │   │   ├── resources.css        # Resources section
│   │   │   ├── footer.css           # Footer styles
│   │   │   └── theme-switcher.css   # Theme toggle button
│   │   ├── layout/
│   │   │   ├── grid.css             # Grid system
│   │   │   └── container.css        # Container utilities
│   │   └── utilities/
│   │       ├── animations.css       # Animation classes
│   │       └── responsive.css       # Media queries
│   ├── js/
│   │   ├── main.js                  # Main JavaScript entry
│   │   ├── modules/
│   │   │   ├── carousel.js          # Carousel functionality
│   │   │   ├── modal.js             # Modal system
│   │   │   ├── theme-switcher.js    # Theme management
│   │   │   ├── animations.js        # Scroll animations
│   │   │   └── navigation.js        # Mobile navigation
│   │   └── utils/
│   │       ├── dom.js               # DOM utilities
│   │       └── helpers.js           # Helper functions
│   └── index.html                   # Main HTML file
├── .dockerignore                    # Docker ignore patterns
├── .env.example                     # Environment variables template
├── eslint.config.js                 # ESLint configuration
├── .gitignore                       # Git ignore patterns
├── .prettierrc.json                 # Prettier configuration
├── AGENTS.md                        # AI agent development guide
├── docker-compose.yml               # Local development configuration
├── Dockerfile                       # Multi-stage Dockerfile (dev & prod targets)
├── nginx.conf                       # Nginx configuration for production
├── LICENSE                          # Project license
├── MASTERPLAN.md                    # Comprehensive project blueprint
├── package.json                     # NPM dependencies
├── package-lock.json                # NPM lock file
├── README.md                        # This file
└── vite.config.js                   # Vite configuration

---

🎨 Design System

The project uses a custom Figma design system created by Mauricio Oliveda, featuring:

• Typography: Carefully selected font families and scales
• Color Palettes: Light and dark theme color systems
• Components: Reusable UI components (cards, buttons, modals)
• Responsive Layouts: Mobile (< 768px), Tablet (768px - 1024px), Desktop (> 1024px)
• Assets: Optimized images, icons, and illustrations

CSS Architecture (BEM)

All styles follow the Block Element Modifier (BEM) naming convention:

/* Block */
.pioneer-card {
}

/* Element */
.pioneer-card__image {
}
.pioneer-card__title {
}

/* Modifier */
.pioneer-card--featured {
}
.pioneer-card--clickable {
}

---

🔄 Git Workflow

This project follows GitFlow workflow with semantic versioning.

Branch Structure

• main - Production-ready code
• develop - Integration branch for features
• feature/* - Feature development branches
• release/* - Release candidate branches
• hotfix/* - Emergency production fixes

Commit Convention

We use Gitmoji for commit messages with the following structure:

<emoji> <short message (max 50 characters)>

Gitmoji Reference:

Emoji	Code	Description	Use Case
🎉	:tada:	Initial commit	First commit of the project
✨	:sparkles:	New feature	Introducing new features
🐛	:bug:	Bug fix	Fixing a bug
📝	:memo:	Documentation	Add or update documentation
🎨	:art:	Code structure/format	Improve structure/format of code
⚡️	:zap:	Performance	Improve performance
🔥	:fire:	Remove code/files	Remove code or files
🚀	:rocket:	Deploy	Deploy stuff
💄	:lipstick:	UI/style	Add or update UI and style files
✅	:white_check_mark:	Tests	Add, update, or pass tests
🔒️	:lock:	Security	Fix security issues
🔧	:wrench:	Configuration	Add or update configuration files
🚨	:rotating_light:	Linter	Fix compiler/linter warnings
🚧	:construction:	Work in progress	Work in progress
♻️	:recycle:	Refactor	Refactor code
⬆️	:arrow_up:	Dependencies	Upgrade dependencies
⬇️	:arrow_down:	Dependencies	Downgrade dependencies
🔀	:twisted_rightwards_arrows:	Merge	Merge branches
➕	:heavy_plus_sign: