cv-site/doc/00-GO-DOCUMENTATION-INDEX.md

# CV Site Go Documentation

Comprehensive documentation for the Go implementation of the CV site.

## Documentation Overview

This documentation covers the core Go systems that power the CV site, with a focus on architecture, implementation details, and practical usage examples.

### 📚 Documentation Files

1. **[Go Validation System](24-GO-VALIDATION-SYSTEM.md)** (739 lines)
   - Tag-based validation with reflection caching
   - Built-in validation rules (required, email, pattern, etc.)
   - Security validation (injection prevention, honeypot, timing)
   - Custom rule extension guide
   - Complete ContactFormRequest example

2. **[Go Template System](25-GO-TEMPLATE-SYSTEM.md)** (894 lines)
   - Thread-safe template manager
   - Hot reload mechanism for development
   - Custom template functions (iterate, eq, safeHTML, dict)
   - Template organization and patterns
   - Performance optimizations

3. **[Go Routes and API](26-GO-ROUTES-API.md)** (1,203 lines)
   - Complete route table with descriptions
   - Middleware chain architecture
   - Security features (CSP, HSTS, rate limiting)
   - Protected endpoints and authentication
   - API request/response formats

4. **[Go Testing](27-GO-TESTING.md)** (~450 lines)
   - Coverage summary by package (100% for config, constants, httputil)
   - Test file descriptions and locations
   - Testing patterns (table-driven, HTTP handlers, middleware)
   - Coverage gap explanations
   - Best practices and CI/CD integration

5. **[AI Chat Agent — CV Assistant Mascot](28-AI-CHAT-AGENT.md)** (~544 lines)
   - Complete mascot feature reference: architecture, components, intelligence
   - ADK Go 1.0 integration with Gemini 2.5 Flash
   - Agent definition with query_cv tool (11 section types, cross-section search)
   - 8 question-type query strategies with instruction engineering
   - HTMX + Hyperscript chat widget with suggested question chips
   - Help modal with categorized example questions
   - Session management (in-memory, OOB swap)
   - Design system integration (CSS tokens, dark theme, responsive)
   - Graceful degradation, security, and testing (46 Playwright assertions)

6. **[AI Chat Showcase — Technical Writeup](29-AI-CHAT-SHOWCASE.md)** (~250 lines)
   - Public-facing technical showcase of the AI chat feature
   - Architecture diagram with dual-provider fallback
   - 9 key technical decisions explained with code examples
   - CV navigation links (GPS for the CV)
   - Technology stack and file structure
   - What this demonstrates for potential employers/clients

## Quick Navigation

### By Feature

**Validation:**
- [Tag Syntax](24-GO-VALIDATION-SYSTEM.md#tag-syntax)
- [Available Rules](24-GO-VALIDATION-SYSTEM.md#available-validation-rules)
- [ContactFormRequest Example](24-GO-VALIDATION-SYSTEM.md#complete-example-contactformrequest)
- [Error Handling](24-GO-VALIDATION-SYSTEM.md#error-handling)
- [Security Rules](24-GO-VALIDATION-SYSTEM.md#5-security-validation)

**Templates:**
- [Custom Functions](25-GO-TEMPLATE-SYSTEM.md#custom-template-functions)
- [Hot Reload](25-GO-TEMPLATE-SYSTEM.md#hot-reload-mechanism)
- [Thread Safety](25-GO-TEMPLATE-SYSTEM.md#thread-safety)
- [Template Patterns](25-GO-TEMPLATE-SYSTEM.md#template-patterns)
- [Security Best Practices](25-GO-TEMPLATE-SYSTEM.md#security-best-practices)

**Routes:**
- [Route Table](26-GO-ROUTES-API.md#route-table)
- [Middleware Stack](26-GO-ROUTES-API.md#middleware-stack)
- [Contact Form API](26-GO-ROUTES-API.md#apicontact---contact-form-submission)
- [PDF Export](26-GO-ROUTES-API.md#exportpdf---pdf-export)
- [Security Features](26-GO-ROUTES-API.md#security-features)

**Testing:**
- [Coverage Summary](27-GO-TESTING.md#coverage-summary)
- [Test Files](27-GO-TESTING.md#test-files)
- [Running Tests](27-GO-TESTING.md#running-tests)
- [Test Patterns](27-GO-TESTING.md#test-patterns)
- [Coverage Gaps](27-GO-TESTING.md#coverage-gaps)
- [Best Practices](27-GO-TESTING.md#best-practices)

### By Use Case

**Setting Up Validation:**
1. [Define struct with tags](24-GO-VALIDATION-SYSTEM.md#struct-definition)
2. [Call validator](24-GO-VALIDATION-SYSTEM.md#validation-execution)
3. [Handle errors](24-GO-VALIDATION-SYSTEM.md#error-handling-example)

**Creating Templates:**
1. [Initialize manager](25-GO-TEMPLATE-SYSTEM.md#initialization)
2. [Use custom functions](25-GO-TEMPLATE-SYSTEM.md#custom-template-functions)
3. [Render in handlers](25-GO-TEMPLATE-SYSTEM.md#usage-in-handlers)

**Adding Routes:**
1. [Configure middleware](26-GO-ROUTES-API.md#middleware-stack)
2. [Register handlers](26-GO-ROUTES-API.md#route-table)
3. [Apply security](26-GO-ROUTES-API.md#route-specific-middleware)

**Writing Tests:**
1. [Review existing coverage](27-GO-TESTING.md#coverage-summary)
2. [Follow test patterns](27-GO-TESTING.md#test-patterns)
3. [Run and verify](27-GO-TESTING.md#running-tests)

## System Architecture

### Overall Flow

```
┌──────────────────────────────────────────────────────────────┐
│                        HTTP Request                          │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       v
┌──────────────────────────────────────────────────────────────┐
│                    Middleware Chain                          │
│  Recovery → Logger → SecurityHeaders → DynamicCache →        │
│  Preferences → Router                                        │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       v
┌──────────────────────────────────────────────────────────────┐
│                      Route Handler                           │
│  1. Parse request                                            │
│  2. Get preferences from context                             │
│  3. Load data (CV, config)                                   │
│  4. Validate input (if needed)                               │
│  5. Render template                                          │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       v
┌──────────────────────────────────────────────────────────────┐
│                   Template Rendering                         │
│  1. Load template (hot reload in dev)                        │
│  2. Execute with data                                        │
│  3. Apply custom functions                                   │
│  4. Output HTML                                              │
└──────────────────────┬───────────────────────────────────────┘
                       │
                       v
┌──────────────────────────────────────────────────────────────┐
│                     HTTP Response                            │
│  - Security headers                                          │
│  - Cache headers                                             │
│  - Content-Type                                              │
│  - HTML/JSON/PDF body                                        │
└──────────────────────────────────────────────────────────────┘
```

### Contact Form Flow

```
POST /api/contact
      │
      v
┌─────────────────────┐
│  BrowserOnly        │  Check User-Agent, Referer, Headers
│  Middleware         │  → 403 if not browser
└─────────┬───────────┘
          │
          v
┌─────────────────────┐
│  RateLimiter        │  5 requests/hour per IP
│  (5/hour)           │  → 429 if exceeded
└─────────┬───────────┘
          │
          v
┌─────────────────────┐
│  Parse JSON         │  Decode ContactFormRequest
│  Request Body       │
└─────────┬───────────┘
          │
          v
┌─────────────────────┐
│  Validate with      │  Tag-based validation:
│  ValidateV2()       │  - required, trim, max
│                     │  - email, pattern
│                     │  - no_injection, honeypot
│                     │  - timing (2s-24h)
└─────────┬───────────┘
          │
          ├─> Validation Failed → 400 + errors
          │
          v
┌─────────────────────┐
│  Send Email         │  SMTP or email service
└─────────┬───────────┘
          │
          v
┌─────────────────────┐
│  200 OK             │  Success response
│  {success: true}    │
└─────────────────────┘
```

## Key Features

### 1. Validation System

**Highlights:**
- Reflection-based with `sync.Map` caching for performance
- Declarative tag syntax: `validate:"required,email,max=254"`
- 11+ built-in rules including security rules
- Extensible with custom rules
- Thread-safe concurrent validation

**Performance:**
- First validation: ~2000 ns/op
- Cached validations: ~1500 ns/op
- Pre-compiled regex patterns

**Security:**
- Email header injection prevention
- Honeypot bot detection
- Timing-based bot detection
- HTML sanitization
- UTF-8 aware length validation

### 2. Template System

**Highlights:**
- Thread-safe with `sync.RWMutex`
- Hot reload in development (edit without restart)
- 4 custom template functions
- Recursive partial loading
- Production caching

**Custom Functions:**
- `iterate(count)` - Generate integer ranges
- `eq(a, b)` - String equality
- `safeHTML(s)` - Safe HTML (trusted content only)
- `dict(k1, v1, ...)` - Create maps for sub-templates

**Thread Safety:**
- Development: Full lock during reload
- Production: Read-only lock (concurrent)

### 3. Routes and Middleware

**Highlights:**
- 15+ routes (public, HTMX, API, protected)
- 8 middleware layers
- Comprehensive security headers
- Rate limiting (contact: 5/hour, PDF: 3/min)
- Origin checking for PDF exports

**Security Features:**
- Content Security Policy (CSP)
- HTTP Strict Transport Security (HSTS)
- BrowserOnly middleware (blocks curl/Postman)
- Email header injection prevention
- Rate limiting per IP
- Origin/Referer validation

## Code Examples

### Validation Example

```go
// Define struct with validation tags
type ContactFormRequest struct {
    Name    string `json:"name"    validate:"required,trim,max=100,pattern=name"`
    Email   string `json:"email"   validate:"required,email,no_injection"`
    Message string `json:"message" validate:"required,trim,max=5000,sanitize"`
}

// Validate
if err := validation.ValidateContactFormV2(req); err != nil {
    // Handle validation errors
    validationErrors := err.(validation.ValidationErrors)
    return c.JSON(400, map[string]interface{}{
        "errors": validationErrors,
    })
}
```

### Template Example

```go
// Initialize template manager
cfg := &config.TemplateConfig{
    Dir:         "templates",
    PartialsDir: "templates/partials",
    HotReload:   true, // Development
}
manager, _ := templates.NewManager(cfg)

// Render in handler
tmpl, _ := manager.Render("home.html")
tmpl.Execute(w, map[string]interface{}{
    "Title": "CV",
    "CV":    cvData,
})
```

### Route Example

```go
// Protected contact endpoint
contactRateLimiter := middleware.NewRateLimiter(5, 1*time.Hour)
protectedHandler := middleware.BrowserOnly(
    contactRateLimiter.Middleware(
        http.HandlerFunc(cvHandler.HandleContact),
    ),
)
mux.Handle("/api/contact", protectedHandler)
```

## Testing

### Run All Tests

```bash
# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package
go test ./internal/validation/...

# Run with verbose output
go test -v ./internal/routes/...
```

### Test Examples

```bash
# Validation tests
go test ./internal/validation/ -v

# Template tests
go test ./internal/templates/ -v

# Middleware tests
go test ./internal/middleware/ -v

# Handler tests
go test ./internal/handlers/ -v
```

## Performance

### Benchmarks

```bash
# Run benchmarks
go test -bench=. ./...

# Validation benchmarks
go test -bench=Validate ./internal/validation/

# Template benchmarks
go test -bench=Render ./internal/templates/
```

### Typical Performance

**Validation:**
- Contact form validation: ~1.5 µs
- Email validation: ~500 ns
- Pattern matching: ~300 ns (pre-compiled)

**Templates:**
- Template render (cached): ~50-100 µs
- Hot reload: ~1-2 ms (development only)

**Routes:**
- Middleware overhead: ~10-20 µs per request
- Rate limiter check: ~100-200 ns
- Total request latency: <5 ms (p50), <20 ms (p99)

## Environment Configuration

### Development

```bash
export GO_ENV=development
export TEMPLATE_HOT_RELOAD=true
export PORT=8080
```

### Production

```bash
export GO_ENV=production
export TEMPLATE_HOT_RELOAD=false
export ALLOWED_ORIGINS="juan.andres.morenorub.io"
export PORT=8080
```

## File Organization

```
cv/
├── doc/
│   ├── 24-GO-VALIDATION-SYSTEM.md   # Validation docs
│   ├── 25-GO-TEMPLATE-SYSTEM.md     # Template docs
│   ├── 26-GO-ROUTES-API.md          # Routes/API docs
│   ├── 27-GO-TESTING.md             # Testing & coverage
│   └── 00-GO-DOCUMENTATION-INDEX.md # This file
│
├── internal/
│   ├── validation/
│   │   ├── validator.go             # Core validator
│   │   ├── rules.go                 # Validation rules
│   │   ├── errors.go                # Error types
│   │   └── contact.go               # ContactFormRequest
│   │
│   ├── templates/
│   │   └── template.go              # Template manager
│   │
│   ├── routes/
│   │   └── routes.go                # Route setup
│   │
│   ├── middleware/
│   │   ├── security.go              # Security middleware
│   │   ├── browser_only.go          # BrowserOnly middleware
│   │   ├── contact_rate_limit.go    # Rate limiting
│   │   ├── logger.go                # Request logging
│   │   ├── recovery.go              # Panic recovery
│   │   └── preferences.go           # User preferences
│   │
│   └── handlers/
│       ├── cv.go                    # CV handlers
│       ├── cv_contact.go            # Contact handler
│       ├── cv_pdf.go                # PDF handler
│       └── health.go                # Health check
│
└── templates/
    ├── *.html                       # Main templates
    └── partials/                    # Partial templates
```

## Best Practices

### Validation

1. **Use tag-based validation** for all struct validation
2. **Order rules correctly**: transformations first (trim, sanitize), then validations
3. **Use global validator** instance to benefit from caching
4. **Combine security rules** for defense in depth
5. **UTF-8 aware**: Use max/min for character count, not byte count

### Templates

1. **Disable hot reload** in production for performance
2. **Use safeHTML only** with trusted content (YAML/config)
3. **Organize templates** logically (main, partials, HTMX)
4. **Leverage custom functions** for reusable logic
5. **Test template execution** to catch errors early

### Routes

1. **Register specific routes first** to avoid conflicts
2. **Apply security middleware** to sensitive endpoints
3. **Use rate limiting** for resource-intensive operations
4. **Log all requests** for monitoring
5. **Implement health checks** for load balancers

## Troubleshooting

### Common Issues

**Validation not working:**
- Check tag syntax: `validate:"rule1,rule2=param"`
- Ensure field is exported (capitalized)
- Verify validator instance is created

**Template not found:**
- Check file exists in templates directory
- Verify filename matches `Render("name")`
- Check template loading logs

**Rate limit too strict:**
- Adjust limit in middleware initialization
- Clear rate limiter state (restart or implement clear endpoint)

**CORS errors:**
- Add domain to `ALLOWED_ORIGINS` environment variable
- Check `OriginChecker` middleware configuration

## Contributing

When adding new features:

1. **Update documentation** in relevant .md file
2. **Add tests** for new functionality
3. **Update route table** if adding endpoints
4. **Document security implications** if applicable
5. **Add examples** for complex features

## Version History

- **v1.0** (2025-12-06) - Initial comprehensive documentation
  - Validation system with tag-based approach
  - Template system with hot reload
  - Complete route and middleware documentation

## License

This documentation is part of the CV site project.

---

**Last Updated:** December 6, 2025
**Total Documentation:** 3,300+ lines across 4 files
**Coverage:** Validation, Templates, Routes, Middleware, Security, Testing