cv-site/doc/README.md

# CV Site — Documentation Master Index v2.0.0

> Modern, minimal curriculum vitae website for Juan Andrés Moreno Rubio.
> Go + HTMX + Hyperscript | Bilingual (ES/EN) | Server-Side PDF | Paper Design Aesthetic

🔗 **Live:** [juan.andres.morenorub.io](https://juan.andres.morenorub.io/)

---

## Quick Start

```bash
cp .env.example .env          # Configure environment
make dev                       # Dev server with hot reload (GO_ENV=development)
make test                      # Go unit tests (fast, no Chrome)
make test-all                  # All tests including PDF/Chrome integration
make lint                      # golangci-lint
make check                     # lint + unit tests
make build                     # Build binary → cv-server
```

---

## Documentation Map

### 1. Core Project Docs

| File | Description | Location |
|------|-------------|----------|
| `README.md` | Project overview, features, demo, security highlights | Root |
| `CLAUDE.md` | AI development guidance, quick commands, tech stack | Root |
| `PROJECT-MEMORY.md` | Critical patterns, rules, lessons learned — **read first** | Root |
| `Makefile` | Build targets (dev, test, lint, build, sprites, css) | Root |
| `.env.example` | Environment configuration template | Root |
| `CODE_OF_CONDUCT.md` | Code of conduct | Root |
| `CONTRIBUTING.md` | Contributing guidelines | Root |
| `LICENSE` | MIT License | Root |

### 2. Core Technical Documentation (`doc/`)

28 numbered docs covering every aspect of the system.

| # | File | Description |
|---|------|-------------|
| 00 | [GO-DOCUMENTATION-INDEX](00-GO-DOCUMENTATION-INDEX.md) | Go system documentation index |
| 01 | [ARCHITECTURE](01-ARCHITECTURE.md) | System design, Go backend architecture |
| 02 | [MODERN-WEB-TECHNIQUES](02-MODERN-WEB-TECHNIQUES.md) | Frontend architecture (HTMX, Hyperscript, CSS) ⭐ |
| 03 | [API](03-API.md) | Complete API reference with endpoints and responses |
| 04 | [HYPERSCRIPT-RULES](04-HYPERSCRIPT-RULES.md) | Hyperscript conventions and best practices |
| 05 | [ZOOM-IMPLEMENTATION](05-ZOOM-IMPLEMENTATION.md) | Custom zoom feature (25%-300%) |
| 06 | [USER-GUIDE](06-USER-GUIDE.md) | End-user guide |
| 07 | [CUSTOMIZATION](07-CUSTOMIZATION.md) | Customization guide |
| 08 | [DEPLOYMENT](08-DEPLOYMENT.md) | Complete deployment guide |
| 09 | [SECURITY](09-SECURITY.md) | Security features, CSP, XSS, headers |
| 10 | [PRIVACY](10-PRIVACY.md) | Privacy & analytics policy |
| 11 | [PDF-EXPORT](11-PDF-EXPORT.md) | Server-side PDF generation (chromedp) |
| 12 | [CSS-ARCHITECTURE](12-CSS-ARCHITECTURE.md) | Modular CSS, ITCSS organization ⭐ |
| 13 | [TOAST-NOTIFICATIONS](13-TOAST-NOTIFICATIONS.md) | Toast notification system |
| 14 | [BACKEND-HANDLERS](14-BACKEND-HANDLERS.md) | Handler architecture, type safety, middleware ⭐ |
| 15 | [SEO](15-SEO.md) | SEO optimization |
| 16 | [CMD-K-API](16-CMD-K-API.md) | Command palette API (ninja-keys) ⭐ |
| 17 | [CONTACT-FORM](17-CONTACT-FORM.md) | Contact form with SMTP |
| 18 | [SECURITY-AUDIT](18-SECURITY-AUDIT.md) | OWASP Top 10 audit report |
| 19 | [SECURITY-IMPLEMENTATION](19-SECURITY-IMPLEMENTATION.md) | Detailed security controls |
| 20 | [HTMX-LEARNING](20-HTMX-LEARNING.md) | HTMX patterns and learning notes |
| 21 | [ACCESSIBILITY](21-ACCESSIBILITY.md) | Accessibility (a11y) implementation |
| 22 | [SPRITES](22-SPRITES.md) | SVG sprite system |
| 23 | [DATA-CACHE](23-DATA-CACHE.md) | Data caching system |
| 24 | [GO-VALIDATION-SYSTEM](24-GO-VALIDATION-SYSTEM.md) | Input validation framework |
| 25 | [GO-TEMPLATE-SYSTEM](25-GO-TEMPLATE-SYSTEM.md) | Go template rendering system |
| 26 | [GO-ROUTES-API](26-GO-ROUTES-API.md) | Route definitions and API structure |
| 27 | [GO-TESTING](27-GO-TESTING.md) | Testing strategy and coverage analysis |

**Additional docs:**

| File | Description |
|------|-------------|
| [DECISIONS.md](DECISIONS.md) | Architectural Decision Records (ADRs) |
| [HTMX-ANALYSIS-COMPLETE.md](HTMX-ANALYSIS-COMPLETE.md) | HTMX implementation analysis |
| [cleanup-report-2025-12-02.md](cleanup-report-2025-12-02.md) | Codebase cleanup report |
| `_go-learning/` | Go learning resources directory |

### 3. Deployment & CI/CD

| File | Description | Location |
|------|-------------|----------|
| `scripts/deploy.sh` | Deployment script | `scripts/` |
| `scripts/healthcheck.sh` | Health check script | `scripts/` |
| `scripts/rollback.sh` | Rollback script | `scripts/` |
| `config/systemd/` | Systemd service configuration | `config/` |
| `.github/workflows/deploy.yml` | GitHub Actions deploy workflow | `.github/` |
| `.github/workflows/test.yml` | GitHub Actions test workflow | `.github/` |
| `.github/workflows/README.md` | Workflows documentation | `.github/` |
| `.github/ISSUE_TEMPLATE/` | Issue templates | `.github/` |

### 4. Testing

**Test Framework Documentation:**

| File | Description | Location |
|------|-------------|----------|
| `tests/README.md` | Testing overview | `tests/` |
| `tests/TEST-SUMMARY.md` | Test suite summary | `tests/` |
| `tests/mjs/README.md` | Playwright test docs | `tests/mjs/` |
| `tests/security/README.md` | Security tests docs | `tests/security/` |

**Security Tests:**

| File | Description |
|------|-------------|
| `tests/security/contact_security_test.go` | Contact form security tests |
| `tests/security/security_tests.sh` | Security test shell scripts |

**Integration Tests:**

| File | Description |
|------|-------------|
| `tests/integration/email_test.go` | Email integration tests |

**E2E Test Suite (`tests/mjs/`) — 83 Playwright Tests:**

| Range | Tests | Coverage |
|-------|-------|----------|
| 0-9 | `0-zoom` `1-toggles` `2-keyboard-shortcuts` `3-hyperscript` `4-htmx` `5-language` `6-modals` `7-mobile-responsive` `8-hover-sync` `9-hyperscript-def-limit` | Core functionality |
| 10-19 | `10-zoom-persistence` `11-zoom-ui-exclusion` `12-skeleton-language` `13-color-theme` `14-button-positioning` `14-pdf-modal` `15-icon-toggle` `16-awards-visual` `17-all-icons` `18-theme-and-mobile` `19-dark-theme` `19-pdf-download-url` | Visual & theme |
| 20-29 | `20-dark-theme-debug` `20-pdf-download-debug` `21-view-switcher` `22-theme-consistency` `23-dark-theme-borders` `24-course-inline-icons` `24-pdf-download-params` `25-inline-icons` `26-course-list-icons` `27-course-icons-final` `28-references-pdf` `29-background-patterns` `29-pdf-toast` | Icons, PDF, dark theme |
| 30-39 | `30-tooltip-macos-dock` `31-tooltip-visual` `32-all-tooltips-final` `32-hyperscript-multi-src` `33-keyboard-shortcuts-refactored` `33-mobile-tooltip-position` `34-hyperscript-refactor` `34-mobile-button-opacity` `35-ipad-sidebar` `35-mobile-colored-buttons` `36-button-hover-footer` `37-footer-hover` `38-mobile-fixes` `39-mobile-updates` | Tooltips, mobile, hyperscript |
| 40-49 | `40-back-to-top-footer` `41-mobile-accordion` `43-info-modal-mobile-font` `43-mobile-accordion-modal` `44-mobile-modal-quick` `45-mobile-modal-comprehensive` `46-visual-accordion` `47-compact-accordion` `48-mobile-landscape-blur` `49-mobile-light-theme` | Mobile, modals, accordion |
| 50-59 | `50-landscape-layout` `51-mobile-button-opacity` `52-mobile-device-detection` `53-final-mobile-fixes` `54-landscape-mode` `55-button-centering` `56-landscape-debug` `57-horizontal-scroll` `58-modal-centering` `59-landscape-photo-backdrop` | Landscape, responsive |
| 60-69 | `60-accessibility` `60-sidebar-content-debug` `61-sidebar-positioning` `62-sidebar-computed-height` `63-media-query-match` `64-desktop-view` `65-page-2-sidebar` `66-comprehensive-all-viewports` `67-button-colors-visibility` `68-menu-colors-dark-theme` `69-scroll-header-behavior` | Accessibility, sidebar, viewports |
| 70-82 | `70-json-content-validation` `71-cmd-k-api-scroll` `72-cmd-k-button` `73-contact-form` `74-button-icon-fluid-sizing` `75-debug-button-icons` `75-html-invoker-commands` `76-cmd-k-lazy-loading` `76-visual-verification` `77-intro-text-justification` `78-fab-search-removal` `79-sprites` `80-mobile-fab-overflow` `81-css-bundling` `82-head-support` | CMD+K, contact, sprites, CSS |

---

## Architecture Quick Reference

### Tech Stack

| Component | Technology |
|-----------|------------|
| Backend | Go 1.21+ (stdlib HTTP server) |
| Frontend | HTMX 1.9+ + Hyperscript + Vanilla JS |
| Templates | Go `html/template` (server-side rendering) |
| PDF Export | chromedp (headless Chrome) |
| Styling | Custom CSS (6-layer ITCSS architecture) |
| Icons | SVG sprites system |
| Command Palette | ninja-keys (CMD+K) |
| Testing | Playwright (E2E, 83 tests) + Go `testing` (unit) |
| Deploy | Nginx + Systemd + Let's Encrypt + GitHub Actions |
| i18n | Bilingual ES/EN with JSON data files |

### Internal Packages (`internal/`)

| Package | Responsibility |
|---------|---------------|
| `cache/` | Page data caching |
| `config/` | Configuration management |
| `constants/` | Application constants |
| `email/` | SMTP email service |
| `fileutil/` | File utility functions |
| `handlers/` | HTTP request handlers (CV, PDF, contact, API) |
| `httputil/` | HTTP utility functions |
| `middleware/` | Security headers, CSRF, rate limiting, logging |
| `models/` | Data models (CV, UI) |
| `pdf/` | PDF generation with chromedp |
| `routes/` | Route configuration |
| `templates/` | Template manager (hot reload in dev) |
| `validation/` | Input validation framework |

### Template Structure

```
templates/
├── index.html              # Main layout wrapper (paper design)
├── cv-content.html         # CV content rendering
├── cv-text.txt             # Plain text CV export
├── language-switch.html    # HTMX language switch partial
└── partials/
    ├── layout/             # head.html, head-scripts.html, head-language-switch.html
    ├── cv/                 # CV section partials
    ├── sections/           # Content sections
    ├── navigation/         # Navigation components
    ├── contact/            # Contact form partials
    ├── modals/             # Modal dialogs (PDF, info, contact)
    ├── widgets/            # Reusable widgets (zoom, theme, tooltips)
    └── color-theme-switcher.html
```

### CSS Architecture (6 layers)

| Layer | Directory | Purpose |
|-------|-----------|---------|
| 01 | `static/css/01-foundation/` | Reset, variables, base typography |
| 02 | `static/css/02-layout/` | Grid, flexbox, page/paper layouts |
| 03 | `static/css/03-components/` | Cards, buttons, sections, sidebar |
| 04 | `static/css/04-interactive/` | Hover, transitions, animations |
| 05 | `static/css/05-responsive/` | Breakpoints, mobile, landscape, tablet |
| 06 | `static/css/06-effects/` | Backgrounds, patterns, blur, glassmorphism |
| — | `static/css/main.css` | Main entry point (imports all layers) |
| — | `static/css/print.css` | Print-specific styles |

### JavaScript Modules

| File | Responsibility |
|------|---------------|
| `static/js/main.js` | App initialization, HTMX setup |
| `static/js/cv-functions.js` | CV-specific functions |
| `static/js/color-theme.js` | Light/Dark/Auto theme switching |
| `static/js/device-detection.js` | Mobile/desktop/tablet detection |
| `static/js/footer-buttons-interaction.js` | Footer button interactions |
| `static/js/ninja-keys-init.js` | CMD+K command palette setup |
| `static/js/scroll-at-bottom-handler.js` | Scroll position detection |

### Data Structure

```
data/
├── cv-es.json              # CV content (Spanish)
├── cv-en.json              # CV content (English)
├── ui-es.json              # UI strings (Spanish)
└── ui-en.json              # UI strings (English)
```

### Static Assets

| Directory | Contents |
|-----------|----------|
| `static/css/` | 6-layer CSS architecture + print.css |
| `static/js/` | 7 JavaScript modules |
| `static/images/` | Profile photo, project images |
| `static/dist/` | Built/bundled assets |
| `static/hyperscript/` | Hyperscript library |
| `static/pdf/` | Generated PDF files |
| `static/psd/` | Design source files |
| `static/llms.txt` | LLM-friendly site description |
| `static/robots.txt` | Search engine directives |
| `static/sitemap.xml` | XML sitemap |
| `static/sprite-showcase.html` | SVG sprite preview page |

### Security Features

| Feature | Implementation |
|---------|---------------|
| CSRF Protection | Cryptographic tokens |
| Rate Limiting | 5 forms/hour, 3 PDFs/minute |
| Bot Detection | Honeypot fields + timing validation |
| Input Validation | Comprehensive sanitization |
| Security Headers | CSP, HSTS, X-Frame-Options (A+ rated) |
| Browser-Only Access | Blocks automation tools on contact form |
| Security Logging | Structured JSON logs |

### Key Features

| Feature | Implementation |
|---------|---------------|
| Bilingual | ES/EN with instant HTMX switching (no reload) |
| PDF Export | Server-side via chromedp (headless Chrome) |
| Paper Design | White paper on gray background aesthetic |
| Zoom Control | 25%-300% with session persistence |
| CMD+K Palette | ninja-keys integration for quick navigation |
| Toast Notifications | PDF download feedback |
| Responsive | Mobile, tablet, desktop, landscape |
| Theme System | Light/Dark/Auto with localStorage |
| SVG Sprites | Optimized icon system |
| Hot Reload | Template hot reload in development mode |

---

## Makefile Commands

| Command | Description |
|---------|-------------|
| `make dev` | Dev server with hot reload |
| `make run` | Production mode |
| `make build` | Build binary → `cv-server` |
| `make test` | Go unit tests (fast, no Chrome) |
| `make test-unit` | Unit tests only |
| `make test-local` | All unit tests from project root |
| `make test-all` | All tests including PDF/Chrome integration |
| `make test-integration` | Integration tests only (PDF) |
| `make lint` | golangci-lint |
| `make lint-fix` | Lint with auto-fix |
| `make check` | Lint + unit tests |
| `make clean` | Clean build artifacts |
| `make sprites` | Generate SVG sprites |
| `make sprites-clean` | Clean sprite artifacts |
| `make css-dev` / `css-prod` / `css-watch` / `css-clean` | CSS build pipeline |

---

## Scripts Reference

| Script | Purpose |
|--------|---------|
| `scripts/deploy.sh` | Production deployment |
| `scripts/healthcheck.sh` | Health check verification |
| `scripts/rollback.sh` | Deployment rollback |
| `cmd/sprites/` | SVG sprite generation tool |

---

## Cross-References

| Resource | Notes |
|----------|-------|
| `doc/00-GO-DOCUMENTATION-INDEX.md` | Original numbered index with reading paths |
| `PROJECT-MEMORY.md` | **Read first** — critical patterns and rules |
| `CLAUDE.md` | AI development guidance and quick commands |
| `doc/DECISIONS.md` | Architectural Decision Records |

---

## Documentation Standards

- **Core docs** (`doc/`) use numbered files (00-27) with cross-references
- **Tests** follow numbered convention (0-82) plus feature-specific tests
- **Status indicators:** ✅ Complete | 🚧 In Progress | ⏳ Planned
- **Bilingual content** requires both `-es.json` and `-en.json` files
- **Security docs** include both audit (18) and implementation (19)

---

## Metrics

| Metric | Value |
|--------|-------|
| Documentation files | 40+ |
| Core technical docs (`doc/`) | 28 numbered + 3 additional |
| Internal packages | 13 |
| E2E test files (Playwright) | 83 |
| JavaScript modules | 7 |
| CSS layers | 6 |
| Languages | 2 (ES, EN) |
| Themes | 3 (Light, Dark, Auto) |
| Security docs | 4 (audit, implementation, privacy, security) |
| Deployment scripts | 3 |
| GitHub Actions workflows | 2 (deploy, test) |
| Zoom range | 25%-300% |

---

**Version:** 2.0.0 | **Last Updated:** February 2026 | **Port:** default (dev)