# CV Site - Go + HTMX

[![Go Version](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go)](https://go.dev/)
[![HTMX](https://img.shields.io/badge/HTMX-2.0-3366CC)](https://htmx.org/)
[![ADK Go](https://img.shields.io/badge/ADK_Go-1.0-4285F4?logo=google)](https://github.com/google/adk-go)
[![Gemini](https://img.shields.io/badge/Gemini_2.5_Flash-AI_Chat-8E75B2?logo=google)](https://aistudio.google.com/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Modern, minimal curriculum vitae website** for Juan Andrés Moreno Rubio built with **Go** and **HTMX**.

A professional, bilingual CV site with server-side PDF generation, HTMX interactivity, and a clean paper design aesthetic. Built as a personal portfolio project showcasing production-grade Go and HTMX development.

## 📌 Project Status

**This is a personal portfolio project** demonstrating production-grade Go and HTMX development.

**Open Source:** The code is MIT licensed and available for educational purposes. You're welcome to use it as a template or reference for your own projects. This repository is maintained as my personal CV site and may be modified without notice.

**Contributions:** This is a personal CV project and is feature-complete. I'm not seeking contributions, but you're welcome to use it as a template! If you find a critical security vulnerability, please report it via email.

## 📑 Table of Contents

- [Features](#-features)
- [AI Chat Agent](#-ai-chat-agent)
- [Demo](#-demo)
- [Security](#-security)
- [Quick Start](#-quick-start)
- [Updating Your CV](#-updating-your-cv)
- [Export to PDF](#-export-to-pdf)
- [Key Technologies](#-key-technologies)
- [Documentation](#-documentation)
- [Deployment](#-deployment)
- [Customization](#-customization)
- [Privacy & Analytics](#-privacy--analytics)
- [Contributing](#-contributing)
- [License](#-license)
- [Support](#-support)

## 🚀 Features

- ✅ **Bilingual Support** - Spanish and English with instant switching (no page reload)
- ✅ **Server-Side PDF Export** - Professional PDF generation using chromedp (headless Chrome)
- ✅ **Browser Print** - Alternative print-friendly layout for manual PDF creation
- ✅ **HTMX Dynamic Updates** - Smooth UX without heavy JavaScript
- ✅ **Paper Design** - Professional CV on elegant white paper with gray background
- ✅ **Zoom Control** - Adjustable zoom (25%-300%) with persistence across sessions
- ✅ **Responsive** - Mobile, tablet, and desktop friendly
- ✅ **JSON-Based Content** - Easy to update without touching code
- ✅ **AI Chat Agent** - Ask questions about the CV in natural language (powered by ADK Go + Gemini)
- ✅ **AI Development Section** - Showcases modern AI-assisted development skills
- ✅ **Fast & Lightweight** - Go backend with chromedp for PDF generation
- ✅ **Privacy-Friendly Analytics** - Self-hosted analytics (no third-party data sharing)
- ✅ **Security Hardened** - CSP headers, XSS protection, origin validation, rate limiting
- ✅ **Production Ready** - Systemd service, CI/CD workflows, deployment guides
- ✅ **Developer Friendly** - Hot reload, clear code structure, comprehensive Makefile

## 🤖 AI Chat Agent

Visitors can ask questions about the CV through a floating chat widget — powered by [Google ADK Go 1.0](https://github.com/google/adk-go) and Gemini 2.5 Flash.

### How It Works

```
Visitor types question → HTMX POST /api/chat → ADK Agent runs query_cv tool
→ Tool searches cached CV JSON data → Agent formulates answer → HTML response
```

### Example Questions & Answers

| Question | Answer |
|----------|--------|
| *"How many Go projects has Juan built?"* | Lists 2 Go projects with descriptions |
| *"What companies has he worked at?"* | Lists all 11 companies |
| *"Does he have React experience?"* | Shows companies where React was used |
| *"¿Qué certificaciones tiene?"* | Lists certifications — answers in Spanish automatically |

### Key Design Decisions

- **Single agent, single tool** — the CV data is bounded; multi-agent orchestration would be over-engineering
- **Reads from the same data cache** the site uses — zero data duplication, always in sync
- **Graceful degradation** — no API key? Chat icon simply doesn't appear. Zero impact on the site
- **HTMX-native** — `hx-post` sends messages, responses are HTML fragments, no WebSocket needed
- **Language-aware** — the agent responds in whatever language the visitor writes in

### Setup

```bash
# Get a free API key from https://aistudio.google.com/apikey
echo "GOOGLE_API_KEY=your-key" >> .env

# Chat icon appears automatically on next server start
go run .
```

**Free tier:** 15 requests/minute — more than enough for a personal CV site.

**Full technical documentation:** [doc/28-AI-CHAT-AGENT.md](doc/28-AI-CHAT-AGENT.md)

---

## 📸 Demo

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

**Live Features:**
- Single-page application with no page reloads
- Instant language switching (English ↔ Spanish)
- Professional PDF export with perfect font rendering
- Responsive design from mobile to desktop
- Clean paper aesthetic on gray background
- Print-friendly layouts

**Note:** This is my personal CV site. The code is open source for learning and reference purposes.

## 🔒 Security

This project demonstrates **production-grade security** practices with multiple layers of protection.

### Security Highlights

✅ **Browser-Only Access** - Contact form blocks automation tools (curl, Postman, scripts)
✅ **CSRF Protection** - Cryptographically secure tokens prevent cross-site attacks
✅ **Rate Limiting** - 5 forms/hour, 3 PDFs/minute to prevent abuse
✅ **Bot Detection** - Honeypot fields and timing validation
✅ **Input Validation** - Comprehensive sanitization and injection prevention
✅ **Security Headers** - A+ rated CSP, HSTS, X-Frame-Options
✅ **Security Logging** - Structured JSON logs for monitoring
✅ **Zero Critical Vulnerabilities** - Full OWASP Top 10 compliance

**Security Rating: A- (Very Good)**

**Documentation:** See [SECURITY.md](doc/9-SECURITY.md) for complete security architecture and implementation details.

---

## 📋 Running Locally

If you want to explore the code or run it locally:

### Prerequisites

- **Go 1.25.1+** installed
- **Chrome/Chromium** (for PDF generation)
- **Make** (optional, for easier development)

### Local Development

\`\`\`bash
# Download the code
git clone https://repos.txeo.club/txeo/cv-site.git
cd cv-site

# Option 1: Using Make - Development mode with hot reload (recommended)
make dev

# Option 2: Using Make - Production mode
make run

# Option 3: Using Go directly
go run main.go

# Option 4: Build and run binary
go build -o cv-server && ./cv-server
\`\`\`

### Development Workflow

The project includes automated quality checks at multiple stages:

| Stage | Command | What Runs | Coverage |
|-------|---------|-----------|----------|
| **Commit** | `git commit` | Pre-commit hook | Changed files only (fast) |
| **Push** | `git push` | Pre-push hook | **Entire codebase** (same as CI) |
| **Manual** | `make lint` | golangci-lint | Entire codebase |
| **Auto-fix** | `make lint-fix` | golangci-lint --fix | Fixes issues automatically |

**Available Make targets:**

\`\`\`bash
make lint        # Run linter on entire codebase (same as CI)
make lint-fix    # Auto-fix lint issues where possible
make test        # Run unit tests
make test-all    # Run all tests including integration
make check       # Run lint + unit tests
make css-prod    # Bundle and minify CSS for production
make dev         # Start development server with hot reload
\`\`\`

**Bypassing hooks (when needed):**
\`\`\`bash
git commit --no-verify  # Skip pre-commit hook
git push --no-verify    # Skip pre-push hook
\`\`\`

### Access the Site

Open **http://localhost:1999** in your browser

- 🇬🇧 **English version:** http://localhost:1999/?lang=en
- 🇪🇸 **Spanish version:** http://localhost:1999/?lang=es

**Language switching** is instant via HTMX - no page reload required!

## 📄 Updating Your CV

Edit JSON files in `data/`:
- **English**: `data/cv-en.json`
- **Spanish**: `data/cv-es.json`

No code changes needed - just refresh browser!

## 🖨️ Export to PDF

### Server-Side PDF Generation (Recommended)

1. Click **"Download as PDF"** button in the action bar
2. PDF is generated server-side using headless Chrome
3. File downloads automatically: `CV-Juan-Andres-Moreno-Rubio-{lang}.pdf`

**Advantages:**
- Consistent rendering across all platforms
- Perfect font rendering
- No browser compatibility issues
- Professional quality output

### Browser Print (Alternative)

1. Click **"Print Friendly"** button
2. Use browser print dialog (Cmd/Ctrl + P)
3. Select "Save as PDF"

**Endpoints:**
- English PDF: `http://localhost:1999/export/pdf?lang=en`
- Spanish PDF: `http://localhost:1999/export/pdf?lang=es`

## 🎯 Key Technologies

- **Backend:** Go 1.25+ (stdlib `net/http`, graceful shutdown)
- **AI Agent:** Google ADK Go 1.0 + Gemini 2.5 Flash (conversational CV navigator)
- **PDF Generation:** chromedp (headless Chrome automation)
- **Frontend:** HTMX 2.0 + Hyperscript (hypermedia-driven interactions)
- **Styling:** Custom CSS with Quicksand font from Google Fonts
- **Data:** JSON files for easy content management
- **Deployment:** Systemd service, manual binary, GitHub Actions CI/CD

## 📚 Documentation

This project includes comprehensive documentation organized by purpose:

### 📖 Getting Started
- **[README.md](README.md)** - Project overview, quick start, and features (you are here)
- **[DEPLOYMENT.md](doc/DEPLOYMENT.md)** - Production deployment guides for VPS and cloud platforms
- **[CUSTOMIZATION.md](doc/CUSTOMIZATION.md)** - How to customize this CV template for your own use

### 🔧 Technical Reference
- **[ARCHITECTURE.md](doc/ARCHITECTURE.md)** - System design, patterns, and technical decisions
- **[API.md](doc/API.md)** - Complete HTTP API reference and HTMX integration
- **[AI-CHAT-AGENT.md](doc/28-AI-CHAT-AGENT.md)** - ADK Go agent architecture, tool design, and integration details
- **[AI-CHAT-SHOWCASE.md](doc/29-AI-CHAT-SHOWCASE.md)** - Technical showcase: AI-powered CV navigation with ADK Go, dual-provider architecture, and document GPS

### 📋 Policies & Standards
- **[SECURITY.md](doc/9-SECURITY.md)** - Complete security architecture, implementation, and testing guide
- **[PRIVACY.md](doc/PRIVACY.md)** - Privacy policy template and analytics guidance
- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community standards (Contributor Covenant)
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution policy (personal project notice)

### 📄 License
- **[LICENSE](LICENSE)** - MIT License

## 🚀 Deployment

This project is production-ready with multiple deployment options. See **[DEPLOYMENT.md](doc/DEPLOYMENT.md)** for complete guides.

### Systemd Service

\`\`\`bash
# Install as systemd service
make install-service

# Update running service
make update-service
\`\`\`

### Manual Deployment

\`\`\`bash
# Build optimized binary
make build

# Run in production mode
GO_ENV=production ./cv-server
\`\`\`

### Cloud Platforms

Deployment guides available for:
- **Fly.io** - Complete fly.toml configuration
- **Google Cloud Run** - Container deployment
- **AWS ECS** - Task definitions
- **Railway / Render** - Auto-deploy configs

**See [DEPLOYMENT.md](doc/DEPLOYMENT.md) for detailed instructions.**

**Environment Configuration:** Copy `.env.example` to `.env` and customize:
- `PORT` - Server port (default: 1999)
- `GO_ENV` - Environment (development/production)
- `TEMPLATE_HOT_RELOAD` - Enable template hot-reload in development

**Security:** See [SECURITY.md](doc/9-SECURITY.md) for production deployment best practices.

## 🎨 Customization

**Want to use this template for your own CV?** See **[CUSTOMIZATION.md](doc/CUSTOMIZATION.md)** for the complete guide!

### Quick Start Customization

1. **Update Content:** Edit `data/cv-en.json` and `data/cv-es.json` with your information
2. **Customize Styling:** Modify `static/css/main.css` (colors, fonts, layout)
3. **Adjust Templates:** Edit files in `templates/` directory
4. **Add Sections:** Update `internal/models/cv.go` and JSON files

The [CUSTOMIZATION.md](doc/CUSTOMIZATION.md) guide includes:
- Complete JSON schema documentation
- Visual customization (colors, fonts, layout)
- Template modification examples
- Adding new languages
- Advanced customization patterns

## 🔒 Privacy & Analytics

This site demonstrates self-hosted analytics implementation for privacy-conscious tracking.

**Key features:**
- Self-hosted analytics (no third-party data sharing)
- Privacy-friendly (respects Do Not Track)
- Fully configurable

See **[PRIVACY.md](doc/PRIVACY.md)** for complete privacy policy template.

---

## 🤝 Using This Template

**This project is open-source and available for you to use!**

**If you use this as a template, you should:**
1. Review the analytics implementation in `templates/index.html`
2. Either configure your own analytics server or remove the tracking code
3. Update CSP headers in `internal/middleware/security.go` accordingly
4. Customize `PRIVACY.md` with your own privacy policy

See **[CUSTOMIZATION.md](doc/CUSTOMIZATION.md#analytics-configuration)** for detailed analytics configuration

**Other recommended changes:**
- Update all personal information in `data/cv-en.json` and `data/cv-es.json`
- Replace profile photo in `static/images/profile/`
- Update `ALLOWED_ORIGINS` in `.env` for API protection
- Customize colors and branding in `static/css/main.css`

See **[CUSTOMIZATION.md](doc/CUSTOMIZATION.md)** for the complete customization guide.

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

**TL;DR:** You can use this template for your own CV site, modify it, and distribute it. Just keep the original copyright notice.

## 💬 Questions or Issues?

- **Questions:** Feel free to fork and modify - this is a template!
- **Security Issues:** Report vulnerabilities via email
- **Documentation:** Check [CUSTOMIZATION.md](doc/CUSTOMIZATION.md) and [DEPLOYMENT.md](doc/DEPLOYMENT.md)

## 🙏 Acknowledgments

- **HTMX** - For making hypermedia-driven applications enjoyable
- **Google ADK Go** - For the production-grade agent framework
- **chromedp** - For reliable headless Chrome automation
- **Go Community** - For excellent standard library and tooling
- **AI Assistance** - For accelerating development and documentation

---

**Built with ❤️ using Go, HTMX, and AI assistance**