cv-site/doc

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

---

Quick Start

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

Additional docs:

File	Description
DECISIONS.md	Architectural Decision Records (ADRs)
HTMX-ANALYSIS-COMPLETE.md	HTMX implementation analysis
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)