feat: simplify architecture by removing cache layer and centralizing routes

- Removed over-engineered cache system for static CV data that only changes on deployment - Extracted all route configuration to internal/routes/routes.go for better organization - Implemented rate limiting and cache control middleware for PDF endpoint protection
2025-11-12 17:53:24 +00:00
parent 927d257f2c
commit 211fd05462
18 changed files with 967 additions and 3042 deletions
@@ -148,15 +148,53 @@ For comprehensive documentation of each endpoint, request/response formats, and

 ---

+## Architecture
+
+### Route Organization
+
+All routes and middleware configuration are centralized in `internal/routes/routes.go` for clean separation of concerns:
+
+```go
+// internal/routes/routes.go
+func Setup(cvHandler *handlers.CVHandler, healthHandler *handlers.HealthHandler) http.Handler {
+    mux := http.NewServeMux()
+
+    // Public routes
+    mux.HandleFunc("/", cvHandler.Home)
+    mux.HandleFunc("/cv", cvHandler.CVContent)
+    mux.HandleFunc("/health", healthHandler.Check)
+
+    // Protected PDF endpoint (rate limited + origin checked)
+    // Static files with cache control
+    // Middleware chain (Recovery → Logger → SecurityHeaders)
+
+    return handler
+}
+```
+
+This architecture provides:
+- ✅ Single source of truth for routes
+- ✅ Clear middleware chain visibility
+- ✅ Easy route management and testing
+- ✅ Clean separation from main.go
+
+### Data Loading
+
+**Simplified Architecture** (cache removed as of v1.1.0):
+- JSON files loaded directly from disk on each request
+- No caching layer (over-engineering for static CV data)
+- Go's built-in file system caching is sufficient
+- Data only changes on deployment/restart
+
 ## Endpoints Overview

-| Method | Path | Description | HTMX Support |
-|--------|------|-------------|--------------|
-| GET | `/` | Full CV page (home) | ❌ No |
-| GET | `/cv` | CV content partial | ✅ Yes |
-| GET | `/export/pdf` | PDF export | ❌ No |
-| GET | `/health` | Health check | ❌ No |
-| GET | `/static/*` | Static files (CSS, JS, images) | ❌ No |
+| Method | Path | Description | HTMX Support | Protection |
+|--------|------|-------------|--------------|------------|
+| GET | `/` | Full CV page (home) | ❌ No | None |
+| GET | `/cv` | CV content partial | ✅ Yes | None |
+| GET | `/export/pdf` | PDF export | ❌ No | ✅ Rate Limited + Origin Check |
+| GET | `/health` | Health check | ❌ No | None |
+| GET | `/static/*` | Static files (CSS, JS, images) | ❌ No | Cache Control |

 ---

@@ -458,7 +496,7 @@ No special headers required.
 ```

 #### Schema
-
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `status` | string | Always `"ok"` if server is running |
@@ -471,6 +509,8 @@ No special headers required.

 **curl:**
 ```bash
+curl http://localhost:1999/health
+```

 **curl with pretty print:**
 ```bash
@@ -1253,9 +1293,11 @@ For comprehensive protection documentation, see [SECURITY.md](SECURITY.md#api-pr

 | Endpoint | Recommended Limit | Burst |
 |----------|-------------------|-------|
-| `/export/pdf` | 5 req/min | 2 |
+| `/` | 20 req/min | 10 |
 | `/cv` | 30 req/min | 15 |
-| `/static/*` | 100 req/min | 50 |
+| `/export/pdf` | 5 req/min | 2 |
+| `/health` | Unlimited | - |
+| `/static/*` | 100 req/min | 50 |

 #### Implementation Options

@@ -1925,6 +1967,7 @@ go tool trace trace.out
 - [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guides

 ### Support
+
 **Issues:** [GitHub Issues](https://github.com/juanatsap/cv-site/issues)
 **Email:** [juan.a.moreno.rubio@gmail.com](mailto:juan.a.moreno.rubio@gmail.com)

@@ -1940,6 +1983,6 @@ go tool trace trace.out

 ---

-**Last Updated:** November 9, 2025
-**API Version:** 1.0.0
-**Documentation Version:** 1.0.0
+**Last Updated:** November 12, 2025
+**API Version:** 1.1.0
+**Documentation Version:** 1.1.0
@@ -0,0 +1,633 @@
+# User Guide - CV Website Features
+
+This guide provides comprehensive documentation for all interactive features of the CV website.
+
+## Table of Contents
+
+- [Zoom Feature](#zoom-feature)
+- [Language Switching](#language-switching)
+- [CV Customization](#cv-customization)
+- [PDF Export](#pdf-export)
+- [Navigation](#navigation)
+- [Accessibility](#accessibility)
+
+---
+
+## Zoom Feature
+
+The CV includes an intelligent zoom control for comfortable viewing at any size.
+
+### Overview
+
+The zoom feature allows you to adjust the CV display size from 25% (bird's-eye view) to 175% (enhanced readability) while keeping navigation controls at a consistent, accessible size.
+
+### How to Use
+
+#### Visual Control
+
+The zoom control appears as a draggable widget near the bottom of the screen (desktop only).
+
+**Components:**
+- **Slider**: Drag anywhere between 25% and 175% zoom
+- **Min/Max Labels**: Show the range (25% and 175%)
+- **Reset Button**: Circular button showing current zoom percentage
+- **Close Button**: Small X button (top-right corner) to hide the control
+
+**Interaction:**
+1. **Adjust Zoom**: Click and drag the slider to your preferred zoom level
+2. **Reset to Default**: Click the circular button (shows current %) to return to 100%
+3. **Reposition Control**: Click and drag the control itself (not the slider/buttons) to move it anywhere on screen
+4. **Hide Control**: Click the X button to hide the control
+5. **Show Control**: Access from hamburger menu (☰) → Select "Zoom"
+
+#### Keyboard Shortcuts
+
+The zoom feature supports standard browser-style keyboard shortcuts:
+
+| Shortcut | Action | Increment |
+|----------|--------|-----------|
+| `Ctrl/Cmd + Plus (+)` | Zoom In | +10% |
+| `Ctrl/Cmd + Minus (-)` | Zoom Out | -10% |
+| `Ctrl/Cmd + 0` | Reset to Default | 100% |
+
+**Note**: These shortcuts work regardless of whether the zoom control is visible.
+
+#### Menu Access
+
+1. Click the **hamburger menu (☰)** in the top-left corner
+2. Hover or click **"Zoom"** menu item
+3. The zoom control will appear
+4. Use the control as described above
+
+### What Zooms vs. What Stays Fixed
+
+#### Elements That Zoom (Content)
+
+The following elements scale according to the zoom level:
+- All CV content (text, headings, paragraphs)
+- Images and icons within the CV
+- CV paper and layout structure
+- Section spacing and margins
+- All typography and line heights
+
+**Behavior at >100% zoom:**
+- Content extends beyond viewport width
+- Horizontal scrollbar appears
+- Natural overflow allows full-size viewing
+- Matches browser zoom behavior
+
+#### Elements That Stay Fixed (UI Controls)
+
+The following elements maintain consistent size regardless of zoom:
+- **Action Bar**: Top black bar with all buttons
+- **Hamburger Menu**: Navigation menu and all menu items
+- **Zoom Control**: The zoom widget itself
+- **Back-to-Top Button**: Bottom-right corner button
+- **Info Button**: Information modal trigger
+- **Footer**: Bottom footer remains at normal size
+
+**Why fixed UI?**
+- **Accessibility**: Controls stay at standard touch target size (44x44px)
+- **Usability**: Buttons never become too large or too small
+- **Consistency**: Predictable interaction at any zoom level
+- **Navigation**: Always accessible regardless of content zoom state
+
+### Design Rationale
+
+#### Zoom Range: 25-175%
+
+**25% - Bird's Eye View:**
+- See entire CV structure at once
+- Great for navigation and overview
+- Check layout balance and spacing
+- Quick section location
+- Ideal for presentations or large screens
+
+**100% - Optimal Reading:**
+- Default and recommended setting
+- Calibrated for comfortable reading
+- Optimal font rendering and line length
+- Balanced for most screen sizes
+- Professional presentation view
+
+**175% - Enhanced Readability:**
+- Enhanced readability for detailed review
+- Accessibility support for vision needs
+- Close inspection of specific content
+- Better for small or high-DPI screens
+- Reduced eye strain for long reading sessions
+
+#### Fixed UI Elements (Inverse Zoom Technique)
+
+**Technical Implementation:**
+Fixed buttons use `zoom: 1/zoomLevel` to counteract content zoom.
+
+**Example:**
+- Content zoom: 150% (`zoom: 1.5`)
+- Button inverse: 67% (`zoom: 0.67`)
+- Result: Button stays at original size
+
+**Benefits:**
+- Buttons remain at accessibility-compliant size (44x44px)
+- Prevents unusably large buttons at 175% zoom
+- Prevents unusably small buttons at 25% zoom
+- Maintains muscle memory for button positions
+- Consistent visual hierarchy
+
+#### Horizontal Scroll Behavior
+
+**Why horizontal scroll appears:**
+- Content naturally extends beyond viewport at >100% zoom
+- Allows viewing full-size content without compression
+- Matches expected browser zoom behavior
+- Prevents text reflow issues
+- Maintains layout integrity
+
+**User Experience:**
+- Smooth scrolling on all devices
+- Keyboard navigation supported (arrow keys)
+- Mouse wheel scrolling (shift + wheel)
+- Trackpad gestures work naturally
+- Does not interfere with vertical scrolling
+
+### Optimal Viewing Tips
+
+#### Quick Overview (25-75% Zoom)
+
+**Best For:**
+- Getting familiar with CV structure
+- Locating specific sections quickly
+- Checking overall layout balance
+- Comparing multiple sections
+- Presentation mode on large screens
+
+**Recommended Settings:**
+- Zoom: 50-75%
+- View: Full screen
+- Navigation: Use section links
+
+#### Comfortable Reading (100% Zoom)
+
+**Best For:**
+- Primary reading experience
+- Professional presentation
+- Standard review and evaluation
+- Sharing with others
+- PDF export preparation
+
+**Recommended Settings:**
+- Zoom: 100% (default)
+- View: Full screen or windowed
+- Font rendering: Optimal
+
+#### Detailed Review (125-175% Zoom)
+
+**Best For:**
+- Enhanced readability needs
+- Close inspection of content
+- Accessibility requirements
+- Small screen viewing
+- Detailed proofreading
+
+**Recommended Settings:**
+- Zoom: 125-150%
+- Use horizontal scroll to navigate
+- Focus on one section at a time
+- Combine with section navigation
+
+### Persistence and Storage
+
+**Automatic Save:**
+- Your zoom level is automatically saved to browser's localStorage
+- Returns to your preferred zoom when you revisit
+- No manual save required
+
+**Per-Device Storage:**
+- Each device/browser remembers its own zoom preference
+- Desktop and mobile can have different settings
+- Private/Incognito mode does not persist zoom
+
+**Storage Keys:**
+- `cv-zoom`: Current zoom percentage (25-175)
+- `cv-zoom-position`: Custom position if dragged
+- `cv-zoom-visible`: Whether control is shown/hidden
+
+**Clear Storage:**
+To reset zoom preferences:
+1. Browser DevTools → Application → Local Storage
+2. Find keys starting with `cv-zoom`
+3. Delete to reset to defaults
+
+### Mobile Behavior
+
+**Automatic Handling:**
+- Zoom control is **hidden on mobile devices** (screens ≤768px)
+- Mobile browsers have native pinch-to-zoom
+- Native zoom works better on small screens
+- Touch gestures are more intuitive on mobile
+
+**Why hidden on mobile?**
+- Limited screen space for controls
+- Native pinch-to-zoom is superior
+- Touch targets would be too small
+- Desktop-oriented feature
+- Mobile viewport already optimized
+
+**Mobile Alternatives:**
+- Use browser's native pinch-to-zoom
+- Double-tap to zoom sections
+- Use browser zoom in/out buttons
+
+### Accessibility Features
+
+#### Keyboard Support
+
+**Full Keyboard Navigation:**
+- `Tab`: Navigate to zoom control
+- `Space`/`Enter`: Activate reset button
+- `Arrow Keys`: Adjust slider (when focused)
+- `Ctrl/Cmd + Plus/Minus/0`: Global shortcuts
+- `Esc`: Close menu/modals
+
+#### Screen Reader Support
+
+**ARIA Attributes:**
+```html
+<input
+  type="range"
+  aria-label="Adjust CV zoom level"
+  aria-valuemin="25"
+  aria-valuemax="175"
+  aria-valuenow="100"
+  aria-valuetext="100%"
+>
+```
+
+**Announcements:**
+- Current zoom level announced on change
+- Reset button announces "Reset zoom to 100%"
+- Slider range clearly communicated
+- Interactive elements properly labeled
+
+#### Visual Accessibility
+
+**High Contrast:**
+- Slider track: Clear contrast ratio
+- Button borders: Visible in all modes
+- Text labels: White on semi-transparent background
+- Focus indicators: 2px white outline
+
+**Focus Indicators:**
+- All interactive elements have visible focus
+- Keyboard navigation clearly indicated
+- Tab order follows logical flow
+
+**Touch Targets:**
+- All buttons meet 44x44px minimum
+- Slider thumb: 18px diameter
+- Close button: 24px diameter
+- Reset button: 44px diameter
+
+### Troubleshooting
+
+#### Zoom Not Working
+
+**Symptoms:**
+- Slider moves but nothing happens
+- Keyboard shortcuts don't work
+- Page doesn't zoom
+
+**Solutions:**
+1. Check browser console for JavaScript errors
+2. Ensure JavaScript is enabled
+3. Try hard refresh: `Ctrl/Cmd + Shift + R`
+4. Clear browser cache and reload
+5. Check if browser zoom is interfering (reset to 100%)
+
+#### Zoom Control Not Visible
+
+**Symptoms:**
+- Can't find zoom control on page
+- Control disappeared
+
+**Solutions:**
+1. Check if you're on mobile (control hidden <768px)
+2. Open hamburger menu → Click "Zoom" to show
+3. Check localStorage: `cv-zoom-visible` should be `true`
+4. Control may be positioned off-screen (drag from edge)
+5. Refresh page to reset position
+
+#### Zoom Resets on Refresh
+
+**Symptoms:**
+- Zoom goes back to 100% every time
+- Preference not saving
+
+**Solutions:**
+1. Check if localStorage is enabled in browser
+2. Ensure you're not in Private/Incognito mode
+3. Check browser privacy settings
+4. Try a different browser to isolate issue
+
+#### Horizontal Scroll Issues
+
+**Symptoms:**
+- Can't scroll horizontally when zoomed
+- Content cut off at edges
+
+**Solutions:**
+1. Ensure body overflow-x is set to auto
+2. Try Shift + Mouse Wheel for horizontal scroll
+3. Use keyboard arrow keys
+4. Check if browser extensions are interfering
+
+#### Fixed Buttons Look Wrong
+
+**Symptoms:**
+- Buttons too large or too small
+- Buttons scaling with content
+
+**Solutions:**
+1. Check if CSS zoom property is supported
+2. Verify browser compatibility (all modern browsers)
+3. Check for conflicting CSS from extensions
+4. Try disabling browser themes/extensions
+
+### Technical Details
+
+#### Implementation
+
+**CSS Zoom Property:**
+```css
+.zoom-wrapper {
+  zoom: 1.25; /* 125% zoom example */
+}
+```
+
+**Inverse Zoom for Fixed Elements:**
+```css
+.fixed-button {
+  zoom: 0.8; /* 1/1.25 = 0.8 to counteract 125% */
+}
+```
+
+**Horizontal Overflow:**
+```css
+body {
+  overflow-x: auto; /* Allow horizontal scroll */
+}
+
+.zoom-wrapper {
+  min-width: 100vw; /* When zoomed > 100% */
+}
+```
+
+#### JavaScript API
+
+**Key Functions:**
+```javascript
+// Apply zoom level
+applyZoom(zoomValue, saveToStorage)
+
+// Increment/decrement zoom
+incrementZoom(step)
+
+// Update display
+updateZoomDisplay(zoomValue)
+
+// Check mobile view
+isMobileView()
+```
+
+**Event Listeners:**
+- `input`: Real-time slider updates
+- `click`: Reset button handler
+- `keydown`: Global keyboard shortcuts
+- `resize`: Handle viewport changes
+
+#### Browser Compatibility
+
+**Supported Browsers:**
+- Chrome/Edge 90+ (Full support)
+- Firefox 90+ (Full support)
+- Safari 13+ (Full support)
+- Opera 76+ (Full support)
+
+**CSS Zoom Support:**
+- Webkit/Blink: Native support
+- Firefox: Supported since Firefox 90
+- All modern browsers support CSS zoom
+
+**Fallback:**
+- No fallback needed (all modern browsers)
+- For older browsers, zoom would simply not work
+- Page remains fully functional without zoom
+
+---
+
+## Language Switching
+
+The CV supports instant language switching between English and Spanish without page reload.
+
+### How to Use
+
+**From Action Bar:**
+1. Click language flag icon in top bar
+2. Select English or Spanish
+3. Content swaps instantly via HTMX
+
+**From Menu:**
+1. Open hamburger menu (☰)
+2. Hover over "Language" item
+3. Select preferred language
+
+**Via URL:**
+- English: `?lang=en`
+- Spanish: `?lang=es`
+
+**Persistence:**
+- Language preference saved to localStorage
+- Returns to your preferred language on next visit
+- Works across all pages
+
+---
+
+## CV Customization
+
+### CV Length Toggle
+
+**Short Version:**
+- Concise overview
+- Key highlights only
+- 1-2 pages when printed
+- Quick review
+
+**Long Version:**
+- Complete details
+- Full project descriptions
+- Comprehensive experience
+- In-depth review
+
+**Toggle:**
+1. Action bar toggle switch
+2. Hamburger menu → "Long Version"
+3. Preference persisted to localStorage
+
+### Logo Visibility
+
+**Show Logos:**
+- Company and technology logos visible
+- Visual brand recognition
+- More engaging presentation
+
+**Hide Logos:**
+- Text-only presentation
+- Cleaner, more formal look
+- Better for print
+
+**Toggle:**
+1. Action bar toggle switch
+2. Hamburger menu → "Show Logos"
+3. Preference persisted to localStorage
+
+### Theme Switching
+
+**Default Theme:**
+- Gray background with paper texture
+- Sidebars with contact info
+- Header and footer visible
+- Full visual design
+
+**Clean Theme:**
+- White background
+- No sidebars
+- Minimal chrome
+- Print-optimized
+
+**Toggle:**
+1. Action bar toggle switch
+2. Hamburger menu → "Clean Theme"
+3. Preference persisted to localStorage
+
+---
+
+## PDF Export
+
+### Server-Side Generation
+
+**Recommended Method:**
+1. Click "Download as PDF" in action bar
+2. Server generates PDF using headless Chrome
+3. File downloads automatically
+4. Filename: `CV-Juan-Andres-Moreno-Rubio-{lang}.pdf`
+
+**Advantages:**
+- Consistent rendering across platforms
+- Perfect font rendering
+- No browser compatibility issues
+- Professional quality output
+
+### Browser Print
+
+**Alternative Method:**
+1. Click "Print Friendly" in action bar
+2. Browser print dialog opens
+3. Select "Save as PDF"
+4. Configure print settings
+
+**Settings:**
+- Switches to clean theme
+- Forces short version
+- Removes interactive elements
+- Optimized for printing
+
+---
+
+## Navigation
+
+### Section Navigation
+
+**Table of Contents:**
+- Auto-generated from CV sections
+- Click any section to scroll smoothly
+- Header stays visible during navigation
+
+**Hamburger Menu:**
+- Mobile-friendly navigation
+- Hover to open on desktop
+- Click to open on mobile
+- Automatic closing after selection
+
+**Back to Top:**
+- Appears after scrolling 300px
+- Smooth scroll to top
+- Always accessible
+- Bottom-right position
+
+### Collapsible Sections
+
+**Details/Summary:**
+- Click section headers to expand/collapse
+- Mobile accordion style
+- Desktop always expanded
+
+**Expand/Collapse All:**
+- Action bar buttons
+- Hamburger menu options
+- Affects all collapsible sections
+
+---
+
+## Accessibility
+
+### Keyboard Navigation
+
+**Tab Order:**
+- Logical flow through all interactive elements
+- Visible focus indicators
+- Skip links for main content
+- All features accessible via keyboard
+
+### Screen Readers
+
+**ARIA Labels:**
+- All interactive elements labeled
+- Form controls properly described
+- Dynamic content announcements
+- Semantic HTML structure
+
+### Visual Accessibility
+
+**Color Contrast:**
+- WCAG AA compliant
+- High contrast mode support
+- Focus indicators visible
+
+**Font Scaling:**
+- Responsive typography
+- Works with browser zoom
+- Readable at all sizes
+
+**Motion Preferences:**
+- Respects prefers-reduced-motion
+- Smooth scrolling optional
+- Animations can be disabled
+
+### Touch Targets
+
+**Minimum Sizes:**
+- All buttons: 44x44px
+- Touch-friendly spacing
+- No overlapping targets
+- Adequate margins
+
+---
+
+## Support
+
+For issues, questions, or feedback:
+- GitHub Issues: https://github.com/txemac/cv/issues
+- Documentation: See /doc folder
+- Live Demo: https://juan.andres.morenorub.io/
+
+**Last Updated:** 2025-11-12