refactor: Separate CV domain and UI presentation models into distinct packages
**Main Changes:** 1. **Package Restructuring** - Separated mixed concerns into focused packages: - Created `internal/models/cv/` for CV domain logic (CV, Personal, Experience, etc.) - Created `internal/models/ui/` for UI presentation logic (InfoModal, ShortcutsModal, etc.) - Removed monolithic `internal/models/cv.go` (300+ lines → organized packages) 2. **Testing** - Added comprehensive unit tests: - `internal/models/cv/loader_test.go` - CV data loading and validation - `internal/models/ui/loader_test.go` - UI translations loading - All tests passing ✅ 3. **Documentation** - Added Go learning knowledge base: - `_go-learning/architecture/server-design.md` - Goroutines, graceful shutdown explained - `_go-learning/refactorings/001-cv-model-separation.md` - This refactoring documented - Public documentation showcasing Go expertise (README.md kept private) 4. **Handler Updates** - Updated imports to use new package structure: - `internal/handlers/cv.go` - Uses `cvmodel` and `uimodel` aliases **Benefits:** - ✅ Clear separation of concerns (domain vs presentation) - ✅ Better testability (isolated package testing) - ✅ Improved maintainability (smaller, focused files) - ✅ Scalability (each domain can evolve independently) - ✅ Follows Go best practices (small, cohesive packages) **Other Updates:** - Updated middleware security checks - Template improvements - Organized completed prompts **Testing:** - All Go unit tests pass (cv, ui, handlers) - Server verified with curl tests (English, Spanish, Health endpoints) - Frontend functionality unchanged (refactoring is transparent to UI)
This commit is contained in:
juanatsap
@@ -56,3 +56,6 @@ playwright.config.js
|
||||
|
||||
# Test artifacts
|
||||
tests/screenshots/
|
||||
|
||||
# Personal learning documentation README (private goals and notes)
|
||||
_go-learning/README.md
|
||||
|
||||
@@ -0,0 +1,557 @@
|
||||
# Go Server Architecture: Why Goroutines and Graceful Shutdown
|
||||
|
||||
**Last Updated**: 2025-11-20
|
||||
**Learning Value**: ⭐⭐⭐⭐⭐
|
||||
|
||||
## 📋 Table of Contents
|
||||
1. [Server Startup Flow](#server-startup-flow)
|
||||
2. [Why Start Server in a Goroutine?](#why-start-server-in-a-goroutine)
|
||||
3. [Graceful Shutdown Pattern](#graceful-shutdown-pattern)
|
||||
4. [Channel Communication](#channel-communication)
|
||||
5. [Context and Timeouts](#context-and-timeouts)
|
||||
6. [Production Best Practices](#production-best-practices)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Server Startup Flow
|
||||
|
||||
### The Code (main.go:60-101)
|
||||
|
||||
```go
|
||||
// Start server in goroutine
|
||||
serverErrors := make(chan error, 1)
|
||||
go func() {
|
||||
log.Printf("✓ Server listening on http://%s:%s", cfg.Server.Host, cfg.Server.Port)
|
||||
serverErrors <- server.ListenAndServe() // Blocks until server stops
|
||||
}()
|
||||
|
||||
// Setup graceful shutdown
|
||||
shutdown := make(chan os.Signal, 1)
|
||||
signal.Notify(shutdown, os.Interrupt, syscall.SIGTERM)
|
||||
|
||||
// Wait for shutdown signal or server error
|
||||
select {
|
||||
case err := <-serverErrors:
|
||||
// Server stopped unexpectedly
|
||||
if !errors.Is(err, http.ErrServerClosed) {
|
||||
log.Fatalf("❌ Server error: %v", err)
|
||||
}
|
||||
case sig := <-shutdown:
|
||||
// User pressed Ctrl+C or system sent SIGTERM
|
||||
log.Printf("🛑 Shutdown signal received: %v", sig)
|
||||
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel()
|
||||
|
||||
if err := server.Shutdown(ctx); err != nil {
|
||||
log.Printf("⚠️ Graceful shutdown failed, forcing: %v", err)
|
||||
server.Close() // Force close if graceful fails
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Visual Flow
|
||||
|
||||
```
|
||||
main() starts
|
||||
│
|
||||
├─→ Load config
|
||||
├─→ Initialize templates
|
||||
├─→ Create handlers
|
||||
├─→ Setup routes
|
||||
└─→ Create HTTP server
|
||||
│
|
||||
├─→ Create error channel (serverErrors)
|
||||
│
|
||||
├─→ Launch GOROUTINE ──────────────┐
|
||||
│ │
|
||||
│ (main thread continues) │ (goroutine: runs in parallel)
|
||||
│ │
|
||||
│ ├─→ Log startup messages
|
||||
│ │
|
||||
│ └─→ server.ListenAndServe()
|
||||
│ (BLOCKS here, handling HTTP requests)
|
||||
│
|
||||
├─→ Create shutdown channel
|
||||
│
|
||||
├─→ Setup signal handler (Ctrl+C, SIGTERM)
|
||||
│
|
||||
└─→ SELECT statement (BLOCKS here)
|
||||
┌───────────────────────────────┐
|
||||
│ │
|
||||
├─→ Case 1: serverErrors │ Case 2: shutdown signal
|
||||
│ (server crashed) │ (user pressed Ctrl+C)
|
||||
│ → Log error │ → Initiate graceful shutdown
|
||||
│ → Exit │ → Wait max 30s for requests to finish
|
||||
│ │ → Force close if timeout
|
||||
└───────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤔 Why Start Server in a Goroutine?
|
||||
|
||||
### The Question
|
||||
> "Why do we do `go func() { server.ListenAndServe() }()` instead of just `server.ListenAndServe()` directly?"
|
||||
|
||||
### The Answer: Blocking vs. Non-Blocking
|
||||
|
||||
#### Without Goroutine (WRONG):
|
||||
```go
|
||||
func main() {
|
||||
server := &http.Server{Addr: ":1999"}
|
||||
|
||||
log.Println("Starting server...")
|
||||
server.ListenAndServe() // ← BLOCKS HERE FOREVER
|
||||
|
||||
// This code NEVER runs!
|
||||
setupGracefulShutdown() // ❌ Never reached
|
||||
waitForSignals() // ❌ Never reached
|
||||
}
|
||||
```
|
||||
|
||||
**Problem**: `ListenAndServe()` **blocks** (waits forever) handling HTTP requests. The function never returns unless the server crashes. Any code after it is unreachable!
|
||||
|
||||
#### With Goroutine (CORRECT):
|
||||
```go
|
||||
func main() {
|
||||
server := &http.Server{Addr: ":1999"}
|
||||
|
||||
// Launch server in separate goroutine
|
||||
serverErrors := make(chan error, 1)
|
||||
go func() {
|
||||
log.Println("Starting server...")
|
||||
serverErrors <- server.ListenAndServe() // Runs in parallel
|
||||
}()
|
||||
|
||||
// Main thread continues immediately!
|
||||
setupGracefulShutdown() // ✅ Runs
|
||||
waitForSignals() // ✅ Runs
|
||||
}
|
||||
```
|
||||
|
||||
**Solution**: The goroutine runs **in parallel** with the main thread. The server handles requests in the goroutine while the main thread sets up shutdown logic.
|
||||
|
||||
### What is a Goroutine?
|
||||
|
||||
> **Goroutine** = Lightweight thread managed by Go runtime
|
||||
|
||||
```go
|
||||
// Regular function call (synchronous)
|
||||
doWork() // Wait for doWork to finish before continuing
|
||||
|
||||
// Goroutine (asynchronous)
|
||||
go doWork() // Start doWork in parallel, continue immediately
|
||||
```
|
||||
|
||||
**Key Characteristics**:
|
||||
- ⚡ **Lightweight**: ~2KB memory (OS threads: ~2MB)
|
||||
- 🚀 **Fast**: Cheap to create, Go can run thousands simultaneously
|
||||
- 🎯 **Scheduled by Go**: Runtime multiplexes goroutines onto OS threads
|
||||
- 📡 **Communicate via channels**: Don't share memory, share by communicating
|
||||
|
||||
---
|
||||
|
||||
## 📡 Channel Communication
|
||||
|
||||
### What is a Channel?
|
||||
|
||||
> **Channel** = Typed conduit through which goroutines communicate
|
||||
|
||||
```go
|
||||
// Create a channel of ints
|
||||
messages := make(chan int)
|
||||
|
||||
// Send value to channel (blocks until someone receives)
|
||||
messages <- 42
|
||||
|
||||
// Receive value from channel (blocks until someone sends)
|
||||
value := <-messages
|
||||
```
|
||||
|
||||
### Why Channels?
|
||||
|
||||
**Problem**: How does the main thread know when the server goroutine encounters an error?
|
||||
|
||||
**Solution**: Use a channel to communicate errors from goroutine → main thread
|
||||
|
||||
```go
|
||||
// Main thread
|
||||
serverErrors := make(chan error, 1) // Buffered channel (capacity 1)
|
||||
|
||||
// Goroutine (different thread)
|
||||
go func() {
|
||||
err := server.ListenAndServe()
|
||||
serverErrors <- err // Send error to channel
|
||||
}()
|
||||
|
||||
// Main thread
|
||||
select {
|
||||
case err := <-serverErrors: // Receive error from channel
|
||||
log.Fatalf("Server failed: %v", err)
|
||||
}
|
||||
```
|
||||
|
||||
### Buffered vs. Unbuffered Channels
|
||||
|
||||
```go
|
||||
// Unbuffered (capacity 0) - default
|
||||
ch := make(chan int)
|
||||
// Sender blocks until receiver is ready
|
||||
// Receiver blocks until sender sends
|
||||
|
||||
// Buffered (capacity > 0)
|
||||
ch := make(chan int, 1)
|
||||
// Sender doesn't block if buffer has space
|
||||
// Receiver blocks only if buffer is empty
|
||||
```
|
||||
|
||||
**Why buffered for `serverErrors`?**
|
||||
```go
|
||||
serverErrors := make(chan error, 1) // Buffer size 1
|
||||
```
|
||||
|
||||
If the server crashes **before** we reach the `select` statement, the error can be stored in the buffer. Without buffering, the send would block forever (deadlock).
|
||||
|
||||
---
|
||||
|
||||
## 🛑 Graceful Shutdown Pattern
|
||||
|
||||
### The Problem: Abrupt Shutdown
|
||||
|
||||
```go
|
||||
// BAD: Immediate shutdown
|
||||
func main() {
|
||||
server.ListenAndServe()
|
||||
// User presses Ctrl+C
|
||||
// → Server IMMEDIATELY stops
|
||||
// → Ongoing requests are KILLED mid-flight
|
||||
// → Data loss, corrupted responses
|
||||
}
|
||||
```
|
||||
|
||||
**Consequences**:
|
||||
- User uploading a file → Upload lost
|
||||
- Database transaction → Data inconsistent
|
||||
- API call → Client gets network error
|
||||
|
||||
### The Solution: Graceful Shutdown
|
||||
|
||||
```go
|
||||
// GOOD: Graceful shutdown
|
||||
server.Shutdown(ctx) // Waits for ongoing requests to finish
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Stop accepting new requests
|
||||
2. Wait for ongoing requests to complete
|
||||
3. Close idle connections
|
||||
4. Shut down cleanly
|
||||
|
||||
### The Code Breakdown
|
||||
|
||||
#### Step 1: Setup Signal Handler
|
||||
```go
|
||||
shutdown := make(chan os.Signal, 1)
|
||||
signal.Notify(shutdown, os.Interrupt, syscall.SIGTERM)
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
- Creates a channel to receive OS signals
|
||||
- Tells Go: "When user presses Ctrl+C (`SIGINT`) or system sends `SIGTERM`, send signal to this channel"
|
||||
|
||||
**Why `SIGTERM`?**
|
||||
- Docker uses `SIGTERM` to stop containers
|
||||
- Kubernetes uses `SIGTERM` before killing pods
|
||||
- Systemd uses `SIGTERM` to stop services
|
||||
|
||||
#### Step 2: Wait for Signal
|
||||
```go
|
||||
select {
|
||||
case err := <-serverErrors:
|
||||
// Server crashed
|
||||
case sig := <-shutdown:
|
||||
// Shutdown requested
|
||||
}
|
||||
```
|
||||
|
||||
**`select` statement**: Waits for **whichever happens first**:
|
||||
- Server crashes → handle error
|
||||
- User presses Ctrl+C → initiate shutdown
|
||||
|
||||
#### Step 3: Graceful Shutdown with Timeout
|
||||
```go
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel()
|
||||
|
||||
if err := server.Shutdown(ctx); err != nil {
|
||||
log.Printf("⚠️ Graceful shutdown failed, forcing: %v", err)
|
||||
server.Close() // Force close
|
||||
}
|
||||
```
|
||||
|
||||
**What happens**:
|
||||
1. Create context with 30-second timeout
|
||||
2. Call `server.Shutdown(ctx)`:
|
||||
- Stop accepting new connections
|
||||
- Wait for active requests to finish (max 30s)
|
||||
- Close idle connections
|
||||
3. If timeout expires:
|
||||
- Graceful shutdown fails
|
||||
- Force close the server (kill all connections)
|
||||
|
||||
---
|
||||
|
||||
## 🕒 Context and Timeouts
|
||||
|
||||
### What is a Context?
|
||||
|
||||
> **Context** = Carries deadlines, cancellation signals, and request-scoped values across API boundaries
|
||||
|
||||
```go
|
||||
// Create context with 5-second timeout
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel() // Always call cancel to release resources
|
||||
|
||||
// Use context in operation
|
||||
err := longRunningOperation(ctx)
|
||||
if errors.Is(err, context.DeadlineExceeded) {
|
||||
log.Println("Operation timed out!")
|
||||
}
|
||||
```
|
||||
|
||||
### Why Context for Shutdown?
|
||||
|
||||
```go
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel()
|
||||
|
||||
server.Shutdown(ctx)
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
1. **Prevents infinite waiting**: If requests don't finish in 30s, proceed anyway
|
||||
2. **Resource cleanup**: `defer cancel()` ensures context resources are freed
|
||||
3. **Cancellation propagation**: All handlers get notified to wrap up
|
||||
|
||||
### Context Hierarchy
|
||||
|
||||
```
|
||||
context.Background() ← Root context
|
||||
│
|
||||
└─→ context.WithTimeout(30s) ← Child context
|
||||
│
|
||||
└─→ HTTP request handlers use this context
|
||||
(when timeout expires, all get cancelled)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Why This Pattern?
|
||||
|
||||
### Comparison
|
||||
|
||||
| Approach | Pro | Con |
|
||||
|----------|-----|-----|
|
||||
| **No goroutine** | Simple | Can't handle shutdown, server blocks forever |
|
||||
| **Goroutine without channels** | Server runs in background | Can't detect errors, no communication |
|
||||
| **Our pattern** | Clean shutdown, error handling, production-ready | Slightly more complex |
|
||||
|
||||
### Real-World Scenarios
|
||||
|
||||
#### Scenario 1: Server Crash
|
||||
```
|
||||
1. Server goroutine encounters error (port already in use)
|
||||
2. Error sent to serverErrors channel
|
||||
3. Main thread receives error via select
|
||||
4. Log error and exit gracefully
|
||||
```
|
||||
|
||||
#### Scenario 2: Graceful Deployment (Kubernetes)
|
||||
```
|
||||
1. Kubernetes sends SIGTERM (wants to update pod)
|
||||
2. Signal handler receives SIGTERM
|
||||
3. Server stops accepting new requests
|
||||
4. Waits up to 30s for active requests to finish
|
||||
5. Closes cleanly
|
||||
6. Kubernetes starts new pod
|
||||
→ Zero downtime deployment! ✨
|
||||
```
|
||||
|
||||
#### Scenario 3: Developer Stops Server (Ctrl+C)
|
||||
```
|
||||
1. Developer presses Ctrl+C (SIGINT)
|
||||
2. Signal handler receives SIGINT
|
||||
3. Ongoing PDF generation continues for up to 30s
|
||||
4. Server shuts down cleanly
|
||||
5. No corrupted files or broken requests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💼 Production Best Practices
|
||||
|
||||
### 1. **Always Use Timeouts**
|
||||
|
||||
```go
|
||||
server := &http.Server{
|
||||
Addr: ":1999",
|
||||
Handler: handler,
|
||||
ReadTimeout: 15 * time.Second, // Max time to read request
|
||||
WriteTimeout: 15 * time.Second, // Max time to write response
|
||||
IdleTimeout: 120 * time.Second, // Max time for keep-alive connections
|
||||
}
|
||||
```
|
||||
|
||||
**Why?**
|
||||
- Prevents slow clients from tying up server resources
|
||||
- Protects against slowloris attacks
|
||||
- Ensures predictable performance
|
||||
|
||||
### 2. **Use Buffered Channels for Errors**
|
||||
|
||||
```go
|
||||
serverErrors := make(chan error, 1) // Buffer size 1
|
||||
```
|
||||
|
||||
**Why?**
|
||||
- Prevents goroutine deadlock if error occurs before select
|
||||
- Allows error to be queued even if no receiver yet
|
||||
|
||||
### 3. **Always `defer cancel()` with Contexts**
|
||||
|
||||
```go
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
defer cancel() // ← CRITICAL: Release resources
|
||||
```
|
||||
|
||||
**Why?**
|
||||
- Prevents context leaks
|
||||
- Frees timers and goroutines associated with context
|
||||
- Go vet will warn if you forget
|
||||
|
||||
### 4. **Handle Both SIGINT and SIGTERM**
|
||||
|
||||
```go
|
||||
signal.Notify(shutdown, os.Interrupt, syscall.SIGTERM)
|
||||
```
|
||||
|
||||
**Why?**
|
||||
- `SIGINT` (Ctrl+C): Developer stopping server locally
|
||||
- `SIGTERM`: System/orchestrator (Docker, K8s) stopping server
|
||||
- Ensures shutdown works in all environments
|
||||
|
||||
### 5. **Have a Force-Close Fallback**
|
||||
|
||||
```go
|
||||
if err := server.Shutdown(ctx); err != nil {
|
||||
log.Printf("⚠️ Graceful shutdown failed, forcing: %v", err)
|
||||
server.Close() // ← Force close if graceful fails
|
||||
}
|
||||
```
|
||||
|
||||
**Why?**
|
||||
- If requests don't finish in timeout, force close
|
||||
- Prevents server hanging indefinitely
|
||||
- Ensures server always stops eventually
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Shutdown Logic
|
||||
|
||||
### Manual Test
|
||||
|
||||
```bash
|
||||
# Terminal 1: Start server
|
||||
go run main.go
|
||||
|
||||
# Terminal 2: Send request that takes 5 seconds
|
||||
curl "http://localhost:1999/slow-endpoint"
|
||||
|
||||
# Terminal 1: Press Ctrl+C while request is active
|
||||
# → Server waits for request to finish (up to 30s)
|
||||
# → Then shuts down cleanly
|
||||
```
|
||||
|
||||
### Simulating SIGTERM (Production)
|
||||
|
||||
```bash
|
||||
# Get process ID
|
||||
ps aux | grep "go run main.go"
|
||||
|
||||
# Send SIGTERM (like Kubernetes would)
|
||||
kill -TERM <PID>
|
||||
|
||||
# Server should shut down gracefully
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Key Concepts Summary
|
||||
|
||||
### Goroutines
|
||||
- **Lightweight threads** managed by Go runtime
|
||||
- Use `go func()` to run functions concurrently
|
||||
- Cheap to create (2KB vs. 2MB for OS threads)
|
||||
|
||||
### Channels
|
||||
- **Communication pipes** between goroutines
|
||||
- Use `<-` to send/receive values
|
||||
- Buffered channels can store values when no receiver ready
|
||||
|
||||
### Select
|
||||
- **Multiplex** on multiple channel operations
|
||||
- Blocks until one case can proceed
|
||||
- Used to wait for first of multiple events
|
||||
|
||||
### Context
|
||||
- **Carries deadlines** and cancellation signals
|
||||
- Use `WithTimeout` to set operation deadlines
|
||||
- Always `defer cancel()` to prevent leaks
|
||||
|
||||
### Graceful Shutdown
|
||||
- **Stop accepting** new requests
|
||||
- **Wait** for active requests to finish (with timeout)
|
||||
- **Force close** if timeout expires
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Interview Talking Points
|
||||
|
||||
### "Why do you use goroutines for the HTTP server?"
|
||||
|
||||
> "I use a goroutine to run `ListenAndServe()` because it's a blocking call—it runs forever handling requests. By launching it in a goroutine, the main thread remains free to set up graceful shutdown logic. This pattern allows me to handle OS signals like SIGTERM (from Kubernetes) and SIGINT (Ctrl+C) to shut down cleanly, ensuring ongoing requests finish before the server stops."
|
||||
|
||||
### "How do you handle server errors in a goroutine?"
|
||||
|
||||
> "I use a buffered channel (`make(chan error, 1)`) to communicate errors from the server goroutine back to the main thread. The goroutine sends any error from `ListenAndServe()` to this channel, and the main thread uses a `select` statement to wait for either an error or a shutdown signal, whichever comes first."
|
||||
|
||||
### "What is graceful shutdown and why is it important?"
|
||||
|
||||
> "Graceful shutdown means stopping the server without killing active requests. When I receive a shutdown signal, I call `server.Shutdown()` with a context that has a 30-second timeout. This stops accepting new connections but waits for ongoing requests to complete naturally. If the timeout expires, I force-close as a fallback. This prevents data loss and gives clients a clean response instead of a broken connection."
|
||||
|
||||
### "Why use context with timeout?"
|
||||
|
||||
> "Context with timeout ensures graceful shutdown doesn't wait forever. If some requests are hanging, the 30-second timeout ensures the server shuts down eventually. The context also propagates cancellation to all handlers, signaling them to wrap up. Without timeout, a misbehaving request could prevent the server from ever shutting down."
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Further Reading
|
||||
|
||||
### Official Go Documentation
|
||||
- [Effective Go: Concurrency](https://go.dev/doc/effective_go#concurrency)
|
||||
- [Go Blog: Concurrency Patterns](https://go.dev/blog/pipelines)
|
||||
- [Go Blog: Context](https://go.dev/blog/context)
|
||||
|
||||
### Server Patterns
|
||||
- [Graceful Shutdown in Go](https://pkg.go.dev/net/http#Server.Shutdown)
|
||||
- [Go HTTP Server Guide](https://github.com/golang/go/wiki/HttpServerShutdown)
|
||||
|
||||
### Books
|
||||
- "Concurrency in Go" - Katherine Cox-Buday
|
||||
- "Go in Practice" - Matt Butcher & Matt Farina
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-20
|
||||
**Practice Project**: CV Server (github.com/juanatsap/cv-site)
|
||||
@@ -0,0 +1,779 @@
|
||||
# Refactoring #001: CV Model and UI Model Separation
|
||||
|
||||
**Date**: 2025-11-20
|
||||
**Status**: In Progress
|
||||
**Complexity**: Medium
|
||||
**Learning Value**: ⭐⭐⭐⭐⭐
|
||||
|
||||
## 📋 Table of Contents
|
||||
1. [The Problem](#the-problem)
|
||||
2. [Why This Matters](#why-this-matters)
|
||||
3. [The Solution](#the-solution)
|
||||
4. [Deep Dive: Go Package Philosophy](#deep-dive-go-package-philosophy)
|
||||
5. [Architecture Diagrams](#architecture-diagrams)
|
||||
6. [Implementation Steps](#implementation-steps)
|
||||
7. [Testing Strategy](#testing-strategy)
|
||||
8. [Lessons Learned](#lessons-learned)
|
||||
|
||||
---
|
||||
|
||||
## 🔴 The Problem
|
||||
|
||||
### Current State
|
||||
|
||||
The file `internal/models/cv.go` (301 lines) contains **two completely different concerns**:
|
||||
|
||||
1. **Domain Models (lines 13-158)**: Business logic and CV data structures
|
||||
- `CV`, `Personal`, `Experience`, `Education`, `Skills`, `Language`, `Project`, etc.
|
||||
- Represents the **core business domain** of a curriculum vitae
|
||||
- Data that comes from `data/cv-{lang}.json`
|
||||
|
||||
2. **Presentation Models (lines 160-215)**: UI configuration and translations
|
||||
- `UI`, `InfoModal`, `ShortcutsModal`, `TechStack`, `ShortcutGroup`, etc.
|
||||
- Represents **user interface state** and internationalization
|
||||
- Data that comes from `data/ui-{lang}.json`
|
||||
|
||||
### Why Is This a Problem?
|
||||
|
||||
```go
|
||||
// Current: Everything mixed together
|
||||
package models
|
||||
|
||||
type CV struct { ... } // Business domain
|
||||
type Experience struct { ... } // Business domain
|
||||
type UI struct { ... } // Presentation layer!?
|
||||
type InfoModal struct { ... } // Presentation layer!?
|
||||
```
|
||||
|
||||
**Violations**:
|
||||
- ❌ **Single Responsibility Principle**: One file doing two jobs
|
||||
- ❌ **Separation of Concerns**: Business logic mixed with UI logic
|
||||
- ❌ **Scalability**: Hard to grow either domain independently
|
||||
- ❌ **Testability**: Can't test CV logic without UI types in scope
|
||||
- ❌ **Clarity**: New developers confused about boundaries
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Why This Matters
|
||||
|
||||
### 1. **Separation of Concerns** (Fundamental Design Principle)
|
||||
|
||||
> "A module should be responsible to one, and only one, actor." - Robert C. Martin (Uncle Bob)
|
||||
|
||||
In our case, we have **two actors**:
|
||||
- **Business stakeholders**: Care about CV data structure, validation, completeness
|
||||
- **UI/UX designers**: Care about modal content, keyboard shortcuts, translations
|
||||
|
||||
Mixing these concerns means:
|
||||
- Changes to UI translations force recompilation of CV business logic
|
||||
- Testing CV data loading requires UI types in memory
|
||||
- Can't reason about one domain without understanding the other
|
||||
|
||||
### 2. **Go's Package Philosophy**
|
||||
|
||||
Go encourages **small, focused packages** that do one thing well:
|
||||
|
||||
```go
|
||||
// Go standard library examples
|
||||
import "net/http" // HTTP client/server
|
||||
import "encoding/json" // JSON encoding
|
||||
import "html/template" // HTML templating
|
||||
|
||||
// NOT like this (anti-pattern):
|
||||
import "net/everything" // HTTP, WebSocket, RPC, all mixed
|
||||
```
|
||||
|
||||
**Key Insight**: Go packages are the **primary means of abstraction**. Unlike Java/C# where classes are primary, in Go you think in packages.
|
||||
|
||||
### 3. **Dependency Management**
|
||||
|
||||
```
|
||||
Current (Bad):
|
||||
┌─────────────────────────────────┐
|
||||
│ internal/handlers/cv.go │
|
||||
│ (imports "models" - gets BOTH │
|
||||
│ CV domain AND UI presentation)│
|
||||
└─────────────────────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ internal/models/cv.go │
|
||||
│ CV domain + UI presentation │
|
||||
│ (300+ lines, mixed concerns) │
|
||||
└─────────────────────────────────┘
|
||||
|
||||
Future (Good):
|
||||
┌─────────────────────────────────┐
|
||||
│ internal/handlers/cv.go │
|
||||
│ (imports BOTH packages, but │
|
||||
│ can choose what to import) │
|
||||
└─────────────────────────────────┘
|
||||
▼ ▼
|
||||
┌──────────┐ ┌──────────┐
|
||||
│ models/cv│ │ models/ui│
|
||||
│ (domain)│ │ (present)│
|
||||
└──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- Handlers can import just `models/cv` if they don't need UI
|
||||
- PDF generator doesn't need to know about modals
|
||||
- API endpoints can return CV data without UI overhead
|
||||
|
||||
### 4. **Testing Independence**
|
||||
|
||||
```go
|
||||
// With separated packages, you can test CV logic without UI:
|
||||
|
||||
// cv/loader_test.go
|
||||
func TestLoadCV(t *testing.T) {
|
||||
cv, err := cv.LoadCV("en")
|
||||
// Test ONLY CV business logic
|
||||
// No UI types needed, faster compilation
|
||||
}
|
||||
|
||||
// ui/loader_test.go
|
||||
func TestLoadUI(t *testing.T) {
|
||||
ui, err := ui.LoadUI("en")
|
||||
// Test ONLY UI translations
|
||||
// No CV types needed
|
||||
}
|
||||
```
|
||||
|
||||
### 5. **Scalability**
|
||||
|
||||
As the project grows:
|
||||
|
||||
```
|
||||
CV domain might add:
|
||||
- Validation logic
|
||||
- Export formats (PDF, Word, LinkedIn)
|
||||
- Version control
|
||||
- Analytics
|
||||
- Recommendations engine
|
||||
|
||||
UI domain might add:
|
||||
- More modals
|
||||
- Theme configurations
|
||||
- Accessibility settings
|
||||
- User preferences
|
||||
- A/B testing configs
|
||||
|
||||
With separation: Each grows independently
|
||||
Without separation: 1000+ line monolithic file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 The Solution
|
||||
|
||||
### Target Package Structure
|
||||
|
||||
```
|
||||
internal/models/
|
||||
├── cv/ # CV Domain Package
|
||||
│ ├── cv.go # Core CV types (CV, Personal, etc.)
|
||||
│ ├── loader.go # LoadCV() + data loading logic
|
||||
│ └── loader_test.go # Unit tests for CV loading
|
||||
│
|
||||
├── ui/ # UI Presentation Package
|
||||
│ ├── ui.go # UI types (UI, InfoModal, etc.)
|
||||
│ ├── loader.go # LoadUI() + data loading logic
|
||||
│ └── loader_test.go # Unit tests for UI loading
|
||||
│
|
||||
└── cv.go (DEPRECATED) # Optional compatibility layer
|
||||
```
|
||||
|
||||
### Why This Structure?
|
||||
|
||||
#### 1. **Package Names Reveal Intent**
|
||||
```go
|
||||
import "github.com/juanatsap/cv-site/internal/models/cv"
|
||||
import "github.com/juanatsap/cv-site/internal/models/ui"
|
||||
```
|
||||
|
||||
Just from the import, you know:
|
||||
- `cv` = Business domain logic
|
||||
- `ui` = Presentation layer logic
|
||||
|
||||
#### 2. **File Names Are Self-Documenting**
|
||||
```
|
||||
cv/loader.go → "This loads CV data"
|
||||
ui/loader.go → "This loads UI translations"
|
||||
```
|
||||
|
||||
No need to read 300 lines to find what you need.
|
||||
|
||||
#### 3. **Tests Live Alongside Code** (Go Convention)
|
||||
```
|
||||
cv/cv.go → CV type definitions
|
||||
cv/loader.go → CV loading logic
|
||||
cv/loader_test.go → Tests for loader.go
|
||||
```
|
||||
|
||||
Go's tooling expects `*_test.go` files in the same directory as the code they test.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Deep Dive: Go Package Philosophy
|
||||
|
||||
### What Makes a Good Go Package?
|
||||
|
||||
#### Principle 1: **Cohesion**
|
||||
> "Things that change together should be packaged together."
|
||||
|
||||
**Good**: All CV types in one package (they change when business requirements change)
|
||||
**Bad**: CV types mixed with UI types (they change for different reasons)
|
||||
|
||||
#### Principle 2: **Minimal API Surface**
|
||||
> "Export only what's necessary."
|
||||
|
||||
```go
|
||||
// cv/loader.go
|
||||
|
||||
// Exported (public API)
|
||||
func LoadCV(lang string) (*CV, error) { ... }
|
||||
|
||||
// Unexported (internal helper)
|
||||
func findDataFile(filename string) (string, error) { ... }
|
||||
func replaceYearPlaceholder(url, year string) string { ... }
|
||||
```
|
||||
|
||||
**Why unexport helpers?**
|
||||
- Smaller public API = easier to maintain
|
||||
- Can refactor internals without breaking clients
|
||||
- Forces callers to use the high-level `LoadCV()` interface
|
||||
|
||||
#### Principle 3: **No Circular Dependencies**
|
||||
Go compiler **forbids** package cycles:
|
||||
|
||||
```go
|
||||
// This will NOT compile:
|
||||
package cv
|
||||
import "ui" // cv depends on ui
|
||||
|
||||
package ui
|
||||
import "cv" // ui depends on cv
|
||||
// ERROR: import cycle not allowed
|
||||
```
|
||||
|
||||
**Our design avoids this**:
|
||||
```
|
||||
handlers → cv
|
||||
handlers → ui
|
||||
cv → (nothing)
|
||||
ui → (nothing)
|
||||
```
|
||||
|
||||
Clean one-way dependency flow!
|
||||
|
||||
#### Principle 4: **Package Names Are Part of the API**
|
||||
|
||||
```go
|
||||
// BAD: Stutter
|
||||
cv.CVLoader() // "CV" mentioned twice
|
||||
cv.LoadCVData() // Redundant
|
||||
|
||||
// GOOD: Clear, concise
|
||||
cv.LoadCV() // Package name + function name = clear intent
|
||||
ui.LoadUI() // Same pattern
|
||||
```
|
||||
|
||||
When you import `cv`, it's obvious everything in it relates to CV domain.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Architecture Diagrams
|
||||
|
||||
### Before Refactoring (Current State)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ main.go │
|
||||
│ (Server startup) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ internal/handlers/cv.go │
|
||||
│ (HTTP handlers for CV endpoints) │
|
||||
│ │
|
||||
│ import "github.com/.../internal/models" │
|
||||
│ │
|
||||
│ cv, _ := models.LoadCV("en") ← Gets CV data │
|
||||
│ ui, _ := models.LoadUI("en") ← Gets UI translations │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ internal/models/cv.go │
|
||||
│ (300+ LINES) │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ CV Domain Models (lines 13-158) │ │
|
||||
│ │ - type CV struct { ... } │ │
|
||||
│ │ - type Personal struct { ... } │ │
|
||||
│ │ - type Experience struct { ... } │ │
|
||||
│ │ - func LoadCV(lang) (*CV, error) │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ UI Presentation Models (lines 160-215) │ │
|
||||
│ │ - type UI struct { ... } │ │
|
||||
│ │ - type InfoModal struct { ... } │ │
|
||||
│ │ - type ShortcutsModal struct { ... } │ │
|
||||
│ │ - func LoadUI(lang) (*UI, error) │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ PROBLEM: Two concerns mixed in one file! │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ data/cv-*.json│ │data/ui-*.json│
|
||||
│ (CV data) │ │ (UI text) │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Issues**:
|
||||
- ❌ Single file with multiple responsibilities
|
||||
- ❌ Can't import CV without also importing UI types
|
||||
- ❌ Hard to test CV logic in isolation
|
||||
- ❌ Confusing for new developers
|
||||
|
||||
### After Refactoring (Target State)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ main.go │
|
||||
│ (Server startup) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ internal/handlers/cv.go │
|
||||
│ (HTTP handlers for CV endpoints) │
|
||||
│ │
|
||||
│ import cvmodel "github.com/.../internal/models/cv" │
|
||||
│ import uimodel "github.com/.../internal/models/ui" │
|
||||
│ │
|
||||
│ cv, _ := cvmodel.LoadCV("en") ← Clear: CV domain │
|
||||
│ ui, _ := uimodel.LoadUI("en") ← Clear: UI presentation │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│ │
|
||||
┌──────────┴────────┐ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────────────┐
|
||||
│ internal/models/│ │ internal/models/ui/ │
|
||||
│ cv/ │ │ │
|
||||
│ │ │ ┌───────────────────┐ │
|
||||
│ ┌─────────────┐ │ │ │ ui.go │ │
|
||||
│ │ cv.go │ │ │ │ - type UI │ │
|
||||
│ │ - type CV │ │ │ │ - type InfoModal │ │
|
||||
│ │ - Personal │ │ │ │ - type Shortcuts │ │
|
||||
│ │ - Experience│ │ │ └───────────────────┘ │
|
||||
│ └─────────────┘ │ │ │
|
||||
│ │ │ ┌───────────────────┐ │
|
||||
│ ┌─────────────┐ │ │ │ loader.go │ │
|
||||
│ │ loader.go │ │ │ │ - LoadUI(lang) │ │
|
||||
│ │ - LoadCV() │ │ │ │ - findDataFile() │ │
|
||||
│ └─────────────┘ │ │ └───────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌─────────────┐ │ │ ┌───────────────────┐ │
|
||||
│ │loader_test │ │ │ │ loader_test.go │ │
|
||||
│ │ - TestLoadCV│ │ │ │ - TestLoadUI │ │
|
||||
│ └─────────────┘ │ │ └───────────────────┘ │
|
||||
└─────────────────┘ └─────────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│data/cv-*.json│ │data/ui-*.json│
|
||||
│ (CV data) │ │ (UI text) │
|
||||
└──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Can import `cv` without `ui` (and vice versa)
|
||||
- ✅ Independent testing of each domain
|
||||
- ✅ Easier to navigate and understand
|
||||
- ✅ Scales as project grows
|
||||
|
||||
### Dependency Graph
|
||||
|
||||
```
|
||||
Templates
|
||||
(*.html)
|
||||
▲
|
||||
│ (runtime reflection,
|
||||
│ no compile-time deps)
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
internal/handlers/cv.go │
|
||||
│ │
|
||||
│ │
|
||||
┌─────────┴─────────┐ │
|
||||
│ │ │
|
||||
▼ ▼ │
|
||||
┌─────────┐ ┌──────────┐ │
|
||||
│models/cv│ │models/ui │ │
|
||||
│ │ │ │ │
|
||||
│ (domain)│ │(present) │ │
|
||||
└─────────┘ └──────────┘ │
|
||||
│ │ │
|
||||
└─────────┬─────────┘ │
|
||||
▼ │
|
||||
JSON Data Files │
|
||||
┌──────────────┐ │
|
||||
│ cv-*.json │ │
|
||||
│ ui-*.json │ │
|
||||
└──────────────┘ │
|
||||
│
|
||||
│
|
||||
Static Assets ────┘
|
||||
(CSS, images)
|
||||
```
|
||||
|
||||
**Key Observations**:
|
||||
- No circular dependencies
|
||||
- `cv` and `ui` packages are independent (parallel)
|
||||
- Handlers orchestrate both domains
|
||||
- Templates have no compile-time dependencies
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Implementation Steps
|
||||
|
||||
### Phase 1: Create New Package Structure ✅
|
||||
|
||||
```bash
|
||||
mkdir -p internal/models/cv
|
||||
mkdir -p internal/models/ui
|
||||
```
|
||||
|
||||
### Phase 2: Extract CV Domain Types ✅
|
||||
|
||||
**File: `internal/models/cv/cv.go`**
|
||||
- Move: `CV`, `Personal`, `Experience`, `Education`, `Skills`, `SkillCategory`, `Language`, `Project`, `Award`, `Certification`, `Course`, `Reference`, `Other`, `Meta`
|
||||
- Keep: JSON tags, struct tags, comments
|
||||
|
||||
**File: `internal/models/cv/loader.go`**
|
||||
- Move: `LoadCV()` function
|
||||
- Move: `findDataFile()` helper
|
||||
- Move: `replaceYearPlaceholder()` helper
|
||||
- Add: Package-level documentation
|
||||
|
||||
### Phase 3: Extract UI Presentation Types ✅
|
||||
|
||||
**File: `internal/models/ui/ui.go`**
|
||||
- Move: `UI`, `InfoModal`, `TechStack`, `ShortcutsModal`, `ShortcutsSections`, `ShortcutGroup`, `ShortcutItem`
|
||||
|
||||
**File: `internal/models/ui/loader.go`**
|
||||
- Move: `LoadUI()` function
|
||||
- Duplicate: `findDataFile()` helper (or create shared util)
|
||||
|
||||
### Phase 4: Update Handler Imports 🔄
|
||||
|
||||
**File: `internal/handlers/cv.go`**
|
||||
|
||||
```go
|
||||
// Before:
|
||||
import "github.com/juanatsap/cv-site/internal/models"
|
||||
|
||||
// After:
|
||||
import (
|
||||
cvmodel "github.com/juanatsap/cv-site/internal/models/cv"
|
||||
uimodel "github.com/juanatsap/cv-site/internal/models/ui"
|
||||
)
|
||||
```
|
||||
|
||||
**Why the aliases?**
|
||||
- `cvmodel` and `uimodel` prevent shadowing of `cv` and `ui` variables
|
||||
- Common Go pattern when package name conflicts with variable names
|
||||
|
||||
### Phase 5: Create Tests ✅
|
||||
|
||||
**File: `internal/models/cv/loader_test.go`**
|
||||
- Test `LoadCV()` for both languages
|
||||
- Test error cases (invalid language, missing file)
|
||||
- Test year placeholder replacement
|
||||
|
||||
**File: `internal/models/ui/loader_test.go`**
|
||||
- Test `LoadUI()` for both languages
|
||||
- Test error cases
|
||||
|
||||
### Phase 6: Validation 🔄
|
||||
|
||||
```bash
|
||||
# Compile check
|
||||
go build ./...
|
||||
|
||||
# Run tests
|
||||
go test ./internal/models/cv/...
|
||||
go test ./internal/models/ui/...
|
||||
|
||||
# Start server
|
||||
make run
|
||||
|
||||
# Test endpoints
|
||||
curl http://localhost:1999/?lang=en
|
||||
curl http://localhost:1999/?lang=es
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### Test Organization
|
||||
|
||||
```
|
||||
Frontend Tests (EXISTING - DON'T TOUCH):
|
||||
tests/
|
||||
├── mjs/
|
||||
│ ├── 01-*.test.mjs # E2E tests
|
||||
│ ├── 29-pdf-toast-*.test.mjs
|
||||
│ └── ...
|
||||
└── (Bun/JavaScript tests for full UX)
|
||||
|
||||
Backend Tests (NEW - GO TESTS):
|
||||
internal/
|
||||
├── models/
|
||||
│ ├── cv/
|
||||
│ │ ├── cv.go
|
||||
│ │ ├── loader.go
|
||||
│ │ └── loader_test.go # Unit tests for CV package
|
||||
│ └── ui/
|
||||
│ ├── ui.go
|
||||
│ ├── loader.go
|
||||
│ └── loader_test.go # Unit tests for UI package
|
||||
└── handlers/
|
||||
├── cv.go
|
||||
└── cv_test.go # Integration tests for handlers
|
||||
```
|
||||
|
||||
### Test Types
|
||||
|
||||
#### 1. **Unit Tests** (Fast, Isolated)
|
||||
```go
|
||||
// internal/models/cv/loader_test.go
|
||||
func TestLoadCV_ValidLanguage(t *testing.T) {
|
||||
cv, err := LoadCV("en")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadCV failed: %v", err)
|
||||
}
|
||||
if cv.Personal.Name == "" {
|
||||
t.Error("Expected CV to have a name")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Test individual functions in isolation
|
||||
|
||||
#### 2. **Integration Tests** (Medium Speed)
|
||||
```go
|
||||
// internal/handlers/cv_test.go
|
||||
func TestHomeHandler_ReturnsCV(t *testing.T) {
|
||||
req := httptest.NewRequest("GET", "/?lang=en", nil)
|
||||
w := httptest.NewRecorder()
|
||||
|
||||
handler.Home(w, req)
|
||||
|
||||
if w.Code != 200 {
|
||||
t.Errorf("Expected 200, got %d", w.Code)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Test how components work together
|
||||
|
||||
#### 3. **E2E Tests** (Existing, Don't Touch)
|
||||
```javascript
|
||||
// tests/mjs/01-*.test.mjs
|
||||
test('CV loads in English', async () => {
|
||||
await page.goto('http://localhost:1999/?lang=en');
|
||||
await expect(page.locator('h1')).toContainText('CV');
|
||||
});
|
||||
```
|
||||
|
||||
**Purpose**: Test full user experience (UI + backend + interactions)
|
||||
|
||||
### Why This Separation?
|
||||
|
||||
| Test Type | Speed | Scope | When to Run |
|
||||
|-----------|-------|-------|-------------|
|
||||
| **Go Unit** | ⚡ Fast (ms) | Single function | Every save, pre-commit |
|
||||
| **Go Integration** | 🏃 Medium (100ms) | Multiple components | Pre-push, CI |
|
||||
| **E2E Frontend** | 🐌 Slow (seconds) | Full application | Pre-deploy, nightly |
|
||||
|
||||
**Philosophy**:
|
||||
- **Unit tests**: Catch bugs early, run constantly
|
||||
- **Integration tests**: Verify components work together
|
||||
- **E2E tests**: Ensure user experience is intact
|
||||
|
||||
---
|
||||
|
||||
## 📚 Lessons Learned
|
||||
|
||||
### 1. **Go Package Design Is an Art**
|
||||
|
||||
Creating packages isn't about file organization—it's about **domain boundaries**.
|
||||
|
||||
**Bad approach**: "Let's split cv.go because it's too long"
|
||||
**Good approach**: "Let's separate CV domain from UI domain because they have different responsibilities"
|
||||
|
||||
### 2. **Duplication vs. Abstraction**
|
||||
|
||||
We duplicated `findDataFile()` in both `cv/loader.go` and `ui/loader.go`.
|
||||
|
||||
**Why?**
|
||||
- It's a small function (17 lines)
|
||||
- Creates **package independence** (no shared dependencies)
|
||||
- Avoids premature abstraction
|
||||
|
||||
**Rule of thumb**: "Duplication is far cheaper than the wrong abstraction." - Sandi Metz
|
||||
|
||||
### 3. **Import Aliases Save Pain**
|
||||
|
||||
```go
|
||||
// Without aliases (BAD):
|
||||
import "github.com/.../models/cv"
|
||||
|
||||
func Home() {
|
||||
cv, _ := cv.LoadCV("en") // ERROR: cv.cv? Confusing!
|
||||
}
|
||||
|
||||
// With aliases (GOOD):
|
||||
import cvmodel "github.com/.../models/cv"
|
||||
|
||||
func Home() {
|
||||
cv, _ := cvmodel.LoadCV("en") // Clear!
|
||||
}
|
||||
```
|
||||
|
||||
### 4. **Tests Are Part of the Public API**
|
||||
|
||||
In Go, tests live alongside the code. This forces you to think about:
|
||||
- What's exported (public)?
|
||||
- What's unexported (private)?
|
||||
- How will clients use this package?
|
||||
|
||||
### 5. **Refactoring Is Iterative**
|
||||
|
||||
We could further refactor:
|
||||
- Split `cv/cv.go` into multiple files (`personal.go`, `experience.go`, etc.)
|
||||
- Extract validation logic
|
||||
- Add builder patterns
|
||||
|
||||
But we stopped here because:
|
||||
- ✅ Addresses the immediate problem (mixed concerns)
|
||||
- ✅ Provides clear boundaries
|
||||
- ✅ Leaves room for future improvements
|
||||
- ✅ Doesn't over-engineer
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Key Takeaways for Job Interviews
|
||||
|
||||
### When Asked About Go Package Design:
|
||||
|
||||
**Question**: "How do you organize Go code?"
|
||||
|
||||
**Answer Framework**:
|
||||
1. **Start with the domain**: What are the core concepts? (CV, UI, etc.)
|
||||
2. **Identify responsibilities**: What changes together? What changes for different reasons?
|
||||
3. **Create boundaries**: Packages represent domain boundaries, not file organization
|
||||
4. **Follow Go idioms**: Small, focused packages with clear names
|
||||
5. **Avoid circular dependencies**: Design for one-way dependency flow
|
||||
|
||||
### Example Response:
|
||||
|
||||
> "In my CV project, I refactored a monolithic `models/cv.go` file that mixed business domain (CV data) with presentation logic (UI translations). I split it into two packages: `models/cv` for the business domain and `models/ui` for presentation.
|
||||
>
|
||||
> This followed Go's philosophy of small, focused packages and made the code more testable—I could now test CV logic without importing UI types. The key insight was recognizing these were two different domains with different change drivers: CV structure changes when business requirements change, while UI changes when designers update the interface.
|
||||
>
|
||||
> I also ensured no circular dependencies by having both packages be leaf nodes in the dependency graph, with handlers orchestrating both."
|
||||
|
||||
### When Asked About Refactoring:
|
||||
|
||||
**Question**: "Tell me about a significant refactoring you did."
|
||||
|
||||
**Answer Framework**:
|
||||
1. **Identify the problem**: What was wrong? Why did it matter?
|
||||
2. **Design the solution**: What principles guided your approach?
|
||||
3. **Execute incrementally**: How did you minimize risk?
|
||||
4. **Validate the change**: How did you ensure it worked?
|
||||
5. **Measure the impact**: What improved?
|
||||
|
||||
**Metrics for this refactoring**:
|
||||
- Lines per file: 300+ → ~100 (more manageable)
|
||||
- Test isolation: Impossible → Easy (independent domains)
|
||||
- Compilation time: Unchanged (actually slightly faster with parallel compilation)
|
||||
- Maintainability: Improved (clear boundaries)
|
||||
|
||||
---
|
||||
|
||||
## 📈 Next Steps
|
||||
|
||||
### Potential Future Improvements
|
||||
|
||||
1. **Further file splitting**:
|
||||
```
|
||||
cv/
|
||||
├── cv.go # Core CV type
|
||||
├── personal.go # Personal info types
|
||||
├── experience.go # Work experience types
|
||||
├── skills.go # Skills types
|
||||
└── loader.go # Data loading
|
||||
```
|
||||
|
||||
2. **Add validation**:
|
||||
```go
|
||||
// cv/validation.go
|
||||
func (cv *CV) Validate() error {
|
||||
if cv.Personal.Name == "" {
|
||||
return errors.New("name is required")
|
||||
}
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
3. **Introduce interfaces**:
|
||||
```go
|
||||
type CVRepository interface {
|
||||
LoadCV(lang string) (*CV, error)
|
||||
SaveCV(cv *CV, lang string) error
|
||||
}
|
||||
```
|
||||
|
||||
4. **Add builders**:
|
||||
```go
|
||||
cv := cv.NewBuilder().
|
||||
WithPersonal(personal).
|
||||
WithExperience(experiences).
|
||||
Build()
|
||||
```
|
||||
|
||||
But remember: **Don't over-engineer**. Add complexity only when you need it.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Further Reading
|
||||
|
||||
### Go Package Design
|
||||
- [Go Blog: Package names](https://go.dev/blog/package-names)
|
||||
- [Effective Go: Packages](https://go.dev/doc/effective_go#packages)
|
||||
- [Go Proverbs: Clear is better than clever](https://go-proverbs.github.io/)
|
||||
|
||||
### Software Design Principles
|
||||
- **Single Responsibility Principle** (SRP)
|
||||
- **Separation of Concerns** (SoC)
|
||||
- **Dependency Inversion Principle** (DIP)
|
||||
|
||||
### Books
|
||||
- "The Go Programming Language" - Donovan & Kernighan (Chapter 10: Packages)
|
||||
- "Clean Architecture" - Robert C. Martin (Principles apply to Go)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-11-20
|
||||
**Status**: Implementing
|
||||
**Confidence**: High (well-established patterns)
|
||||
+11
-10
@@ -11,7 +11,8 @@ import (
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/juanatsap/cv-site/internal/models"
|
||||
cvmodel "github.com/juanatsap/cv-site/internal/models/cv"
|
||||
uimodel "github.com/juanatsap/cv-site/internal/models/ui"
|
||||
"github.com/juanatsap/cv-site/internal/pdf"
|
||||
"github.com/juanatsap/cv-site/internal/templates"
|
||||
)
|
||||
@@ -53,14 +54,14 @@ func (h *CVHandler) Home(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
|
||||
// Load CV data
|
||||
cv, err := models.LoadCV(lang)
|
||||
cv, err := cvmodel.LoadCV(lang)
|
||||
if err != nil {
|
||||
HandleError(w, r, DataLoadError(err, "CV"))
|
||||
return
|
||||
}
|
||||
|
||||
// Load UI translations
|
||||
ui, err := models.LoadUI(lang)
|
||||
ui, err := uimodel.LoadUI(lang)
|
||||
if err != nil {
|
||||
HandleError(w, r, DataLoadError(err, "UI"))
|
||||
return
|
||||
@@ -161,14 +162,14 @@ func (h *CVHandler) CVContent(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
|
||||
// Load CV data
|
||||
cv, err := models.LoadCV(lang)
|
||||
cv, err := cvmodel.LoadCV(lang)
|
||||
if err != nil {
|
||||
HandleError(w, r, DataLoadError(err, "CV"))
|
||||
return
|
||||
}
|
||||
|
||||
// Load UI translations
|
||||
ui, err := models.LoadUI(lang)
|
||||
ui, err := uimodel.LoadUI(lang)
|
||||
if err != nil {
|
||||
HandleError(w, r, DataLoadError(err, "UI"))
|
||||
return
|
||||
@@ -345,7 +346,7 @@ func (h *CVHandler) ExportPDF(w http.ResponseWriter, r *http.Request) {
|
||||
log.Printf("PDF export requested: lang=%s, length=%s, icons=%s, version=%s", lang, length, icons, version)
|
||||
|
||||
// Load CV data to get name for filename
|
||||
cv, err := models.LoadCV(lang)
|
||||
cv, err := cvmodel.LoadCV(lang)
|
||||
if err != nil {
|
||||
HandleError(w, r, DataLoadError(err, "CV"))
|
||||
return
|
||||
@@ -441,7 +442,7 @@ func (h *CVHandler) ExportPDF(w http.ResponseWriter, r *http.Request) {
|
||||
|
||||
// splitSkills splits skill categories between left (page 1) and right (page 2) sidebars
|
||||
// Each category explicitly specifies which sidebar it belongs to via the "sidebar" field
|
||||
func splitSkills(skills []models.SkillCategory) (left, right []models.SkillCategory) {
|
||||
func splitSkills(skills []cvmodel.SkillCategory) (left, right []cvmodel.SkillCategory) {
|
||||
if len(skills) == 0 {
|
||||
return nil, nil
|
||||
}
|
||||
@@ -570,7 +571,7 @@ func calculateDuration(startDate, endDate string, current bool, lang string) str
|
||||
// processProjectDates calculates dynamic dates for projects
|
||||
// If a project has a gitRepoUrl, it fetches the first commit date
|
||||
// For current projects, it sets the current system date
|
||||
func processProjectDates(project *models.Project, lang string) {
|
||||
func processProjectDates(project *cvmodel.Project, lang string) {
|
||||
now := time.Now()
|
||||
|
||||
// Set dynamic current date for ongoing projects
|
||||
@@ -718,13 +719,13 @@ func getGitRepoFirstCommitDate(repoPath string) string {
|
||||
// prepareTemplateData prepares common template data used across handlers
|
||||
func (h *CVHandler) prepareTemplateData(lang string) (map[string]interface{}, error) {
|
||||
// Load CV data
|
||||
cv, err := models.LoadCV(lang)
|
||||
cv, err := cvmodel.LoadCV(lang)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Load UI translations
|
||||
ui, err := models.LoadUI(lang)
|
||||
ui, err := uimodel.LoadUI(lang)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
@@ -30,11 +30,11 @@ func SecurityHeaders(next http.Handler) http.Handler {
|
||||
|
||||
// Content Security Policy (comprehensive)
|
||||
csp := "default-src 'self'; " +
|
||||
"script-src 'self' 'unsafe-inline' https://unpkg.com https://cdn.jsdelivr.net https://matomo.drolo.club; " +
|
||||
"script-src 'self' 'unsafe-inline' https://unpkg.com https://cdn.jsdelivr.net https://matomo.morenorub.io; " +
|
||||
"style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
|
||||
"font-src 'self' https://fonts.gstatic.com; " +
|
||||
"img-src 'self' data: https:; " +
|
||||
"connect-src 'self' https://api.iconify.design https://matomo.drolo.club; " +
|
||||
"connect-src 'self' https://api.iconify.design https://matomo.morenorub.io; " +
|
||||
"frame-ancestors 'self'; " +
|
||||
"base-uri 'self'; " +
|
||||
"form-action 'self'"
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
package cv
|
||||
|
||||
// CV represents the complete curriculum vitae structure
|
||||
type CV struct {
|
||||
Personal Personal `json:"personal"`
|
||||
Summary string `json:"summary"`
|
||||
Experience []Experience `json:"experience"`
|
||||
Education []Education `json:"education"`
|
||||
Skills Skills `json:"skills"`
|
||||
Languages []Language `json:"languages"`
|
||||
Projects []Project `json:"projects"`
|
||||
Awards []Award `json:"awards"`
|
||||
Certifications []Certification `json:"certifications"`
|
||||
Courses []Course `json:"courses"`
|
||||
References []Reference `json:"references"`
|
||||
Other Other `json:"other"`
|
||||
Meta Meta `json:"meta"`
|
||||
}
|
||||
|
||||
type Personal struct {
|
||||
Name string `json:"name"`
|
||||
Title string `json:"title"`
|
||||
Location string `json:"location"`
|
||||
Email string `json:"email"`
|
||||
Phone string `json:"phone"`
|
||||
DateOfBirth string `json:"dateOfBirth"`
|
||||
PlaceOfBirth string `json:"placeOfBirth"`
|
||||
Citizenship string `json:"citizenship"`
|
||||
LinkedIn string `json:"linkedin"`
|
||||
GitHub string `json:"github"`
|
||||
Domestika string `json:"domestika"`
|
||||
Website string `json:"website"`
|
||||
Photo string `json:"photo"`
|
||||
}
|
||||
|
||||
type Experience struct {
|
||||
Position string `json:"position"`
|
||||
Company string `json:"company"`
|
||||
CompanyURL string `json:"companyURL,omitempty"` // Optional URL for company website
|
||||
CompanyLogo string `json:"companyLogo"`
|
||||
Location string `json:"location"`
|
||||
StartDate string `json:"startDate"`
|
||||
EndDate string `json:"endDate"`
|
||||
Current bool `json:"current"`
|
||||
Expired bool `json:"expired,omitempty"` // Optional flag for expired companies
|
||||
ShortDescription string `json:"shortDescription"`
|
||||
Responsibilities []string `json:"responsibilities"`
|
||||
Technologies []string `json:"technologies"`
|
||||
Highlights []string `json:"highlights"`
|
||||
Duration string `json:"-"` // Calculated field, not from JSON
|
||||
}
|
||||
|
||||
type Education struct {
|
||||
Degree string `json:"degree"`
|
||||
Institution string `json:"institution"`
|
||||
Location string `json:"location"`
|
||||
StartDate string `json:"startDate"`
|
||||
EndDate string `json:"endDate"`
|
||||
Field string `json:"field"`
|
||||
}
|
||||
|
||||
type Skills struct {
|
||||
Technical []SkillCategory `json:"technical"`
|
||||
SoftSkills []string `json:"soft_skills"`
|
||||
}
|
||||
|
||||
type SkillCategory struct {
|
||||
Category string `json:"category"`
|
||||
Proficiency int `json:"proficiency"`
|
||||
Items []string `json:"items"`
|
||||
Sidebar string `json:"sidebar"` // "left" or "right"
|
||||
}
|
||||
|
||||
type Language struct {
|
||||
Language string `json:"language"`
|
||||
Proficiency string `json:"proficiency"`
|
||||
Level int `json:"level"`
|
||||
Detail string `json:"detail,omitempty"` // Optional detail like "Oral (Medio/Alto) Escrito (Alto)"
|
||||
}
|
||||
|
||||
type Project struct {
|
||||
Title string `json:"title"`
|
||||
ProjectName string `json:"projectName,omitempty"` // Optional: linkable part of title
|
||||
ProjectDesc string `json:"projectDesc,omitempty"` // Optional: non-linkable description part
|
||||
URL string `json:"url"`
|
||||
ProjectLogo string `json:"projectLogo,omitempty"` // Optional logo filename
|
||||
GitRepoUrl string `json:"gitRepoUrl,omitempty"` // Optional git repository URL for dynamic dates
|
||||
Location string `json:"location"`
|
||||
StartDate string `json:"startDate,omitempty"` // Optional static start date
|
||||
Current bool `json:"current"`
|
||||
MaintainedBy string `json:"maintainedBy,omitempty"` // Optional maintainer name (e.g., "SAP")
|
||||
Technologies []string `json:"technologies"`
|
||||
ShortDescription string `json:"shortDescription"`
|
||||
Responsibilities []string `json:"responsibilities"`
|
||||
|
||||
// Computed fields (not stored in JSON)
|
||||
ComputedStartDate string `json:"-"` // Dynamically calculated from git repo or system
|
||||
DynamicDate string `json:"-"` // Current date for ongoing projects
|
||||
}
|
||||
|
||||
type Award struct {
|
||||
Title string `json:"title"`
|
||||
Issuer string `json:"issuer"`
|
||||
Date string `json:"date"`
|
||||
Description string `json:"description"`
|
||||
ShortDescription string `json:"shortDescription,omitempty"`
|
||||
Responsibilities []string `json:"responsibilities,omitempty"`
|
||||
AwardLogo string `json:"awardLogo"`
|
||||
}
|
||||
|
||||
type Certification struct {
|
||||
Name string `json:"name"`
|
||||
Issuer string `json:"issuer"`
|
||||
Date string `json:"date"`
|
||||
Description string `json:"description"`
|
||||
}
|
||||
|
||||
type Course struct {
|
||||
Title string `json:"title"`
|
||||
Institution string `json:"institution"`
|
||||
CourseLogo string `json:"courseLogo,omitempty"` // Optional logo filename
|
||||
Location string `json:"location"`
|
||||
Date string `json:"date"`
|
||||
Duration string `json:"duration"`
|
||||
Description string `json:"description"`
|
||||
ShortDescription string `json:"shortDescription,omitempty"`
|
||||
Responsibilities []string `json:"responsibilities,omitempty"`
|
||||
}
|
||||
|
||||
type Reference struct {
|
||||
Title string `json:"title"`
|
||||
URL string `json:"url"`
|
||||
Type string `json:"type"` // "recommendation", "portfolio", "profile", "cv", "presentation"
|
||||
Action string `json:"action,omitempty"` // Optional action like "downloadPDF"
|
||||
TextBefore string `json:"textBefore,omitempty"` // Text before the link
|
||||
LinkText string `json:"linkText,omitempty"` // Bold text inside the link
|
||||
TextAfter string `json:"textAfter,omitempty"` // Text after the link
|
||||
}
|
||||
|
||||
type Other struct {
|
||||
DriverLicense string `json:"driverLicense"`
|
||||
}
|
||||
|
||||
type Meta struct {
|
||||
Version string `json:"version"`
|
||||
LastUpdated string `json:"lastUpdated"`
|
||||
Format string `json:"format"`
|
||||
Language string `json:"language"`
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
package cv
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
// LoadCV loads CV data from a JSON file for the specified language
|
||||
func LoadCV(lang string) (*CV, error) {
|
||||
if lang != "en" && lang != "es" {
|
||||
return nil, fmt.Errorf("unsupported language: %s", lang)
|
||||
}
|
||||
|
||||
filename := fmt.Sprintf("data/cv-%s.json", lang)
|
||||
filepath, err := findDataFile(filename)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
data, err := os.ReadFile(filepath)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("error reading file %s: %w", filename, err)
|
||||
}
|
||||
|
||||
var cvData CV
|
||||
if err := json.Unmarshal(data, &cvData); err != nil {
|
||||
return nil, fmt.Errorf("error parsing JSON: %w", err)
|
||||
}
|
||||
|
||||
// Replace {{YEAR}} placeholder in reference URLs with current year
|
||||
currentYear := fmt.Sprintf("%d", time.Now().Year())
|
||||
for i := range cvData.References {
|
||||
cvData.References[i].URL = replaceYearPlaceholder(cvData.References[i].URL, currentYear)
|
||||
}
|
||||
|
||||
return &cvData, nil
|
||||
}
|
||||
|
||||
// findDataFile locates a data file by searching up the directory tree
|
||||
func findDataFile(filename string) (string, error) {
|
||||
// Try current directory first
|
||||
if _, err := os.Stat(filename); err == nil {
|
||||
return filename, nil
|
||||
}
|
||||
|
||||
// Try parent directories (for tests running from subdirectories)
|
||||
paths := []string{
|
||||
filename, // Current dir
|
||||
"../" + filename, // One level up
|
||||
"../../" + filename, // Two levels up (for tests in internal/handlers)
|
||||
"../../../" + filename, // Three levels up
|
||||
}
|
||||
|
||||
for _, path := range paths {
|
||||
if _, err := os.Stat(path); err == nil {
|
||||
return path, nil
|
||||
}
|
||||
}
|
||||
|
||||
return "", fmt.Errorf("file not found: %s (searched: current dir, ../, ../../, ../../../)", filename)
|
||||
}
|
||||
|
||||
// replaceYearPlaceholder replaces {{YEAR}} with the current year
|
||||
func replaceYearPlaceholder(url string, year string) string {
|
||||
return strings.ReplaceAll(url, "{{YEAR}}", year)
|
||||
}
|
||||
@@ -0,0 +1,100 @@
|
||||
package cv_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/juanatsap/cv-site/internal/models/cv"
|
||||
)
|
||||
|
||||
func TestLoadCV(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
lang string
|
||||
wantErr bool
|
||||
}{
|
||||
{
|
||||
name: "English CV",
|
||||
lang: "en",
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "Spanish CV",
|
||||
lang: "es",
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "Invalid language",
|
||||
lang: "fr",
|
||||
wantErr: true,
|
||||
},
|
||||
{
|
||||
name: "Empty language",
|
||||
lang: "",
|
||||
wantErr: true,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
cvData, err := cv.LoadCV(tt.lang)
|
||||
|
||||
if (err != nil) != tt.wantErr {
|
||||
t.Errorf("LoadCV() error = %v, wantErr %v", err, tt.wantErr)
|
||||
return
|
||||
}
|
||||
|
||||
if !tt.wantErr {
|
||||
if cvData == nil {
|
||||
t.Error("LoadCV() returned nil CV data")
|
||||
return
|
||||
}
|
||||
|
||||
// Validate CV has essential data
|
||||
if cvData.Personal.Name == "" {
|
||||
t.Error("LoadCV() returned CV with empty name")
|
||||
}
|
||||
|
||||
if len(cvData.Experience) == 0 {
|
||||
t.Error("LoadCV() returned CV with no experience")
|
||||
}
|
||||
|
||||
if len(cvData.Skills.Technical) == 0 {
|
||||
t.Error("LoadCV() returned CV with no technical skills")
|
||||
}
|
||||
|
||||
// Validate that year placeholder was replaced
|
||||
for i, ref := range cvData.References {
|
||||
if ref.URL == "" {
|
||||
continue
|
||||
}
|
||||
if len(ref.URL) >= 2 && ref.URL[0:2] == "{{" {
|
||||
t.Errorf("LoadCV() reference %d still has placeholder in URL: %s", i, ref.URL)
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadCV_DataIntegrity(t *testing.T) {
|
||||
cvData, err := cv.LoadCV("en")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadCV() failed: %v", err)
|
||||
}
|
||||
|
||||
// Test that computed fields are properly initialized (empty, not populated yet)
|
||||
for i, exp := range cvData.Experience {
|
||||
if exp.Duration != "" {
|
||||
t.Errorf("Experience[%d].Duration should be empty before calculation, got: %s", i, exp.Duration)
|
||||
}
|
||||
}
|
||||
|
||||
// Test that JSON tags are properly used
|
||||
if cvData.Meta.Version == "" {
|
||||
t.Error("Meta.Version should not be empty")
|
||||
}
|
||||
|
||||
if cvData.Meta.Language == "" {
|
||||
t.Error("Meta.Language should not be empty")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
package ui
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
)
|
||||
|
||||
// LoadUI loads UI translations from a JSON file for the specified language
|
||||
func LoadUI(lang string) (*UI, error) {
|
||||
if lang != "en" && lang != "es" {
|
||||
return nil, fmt.Errorf("unsupported language: %s", lang)
|
||||
}
|
||||
|
||||
filename := fmt.Sprintf("data/ui-%s.json", lang)
|
||||
filepath, err := findDataFile(filename)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
data, err := os.ReadFile(filepath)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("error reading file %s: %w", filename, err)
|
||||
}
|
||||
|
||||
var uiData UI
|
||||
if err := json.Unmarshal(data, &uiData); err != nil {
|
||||
return nil, fmt.Errorf("error parsing JSON: %w", err)
|
||||
}
|
||||
|
||||
return &uiData, nil
|
||||
}
|
||||
|
||||
// findDataFile locates a data file by searching up the directory tree
|
||||
func findDataFile(filename string) (string, error) {
|
||||
// Try current directory first
|
||||
if _, err := os.Stat(filename); err == nil {
|
||||
return filename, nil
|
||||
}
|
||||
|
||||
// Try parent directories (for tests running from subdirectories)
|
||||
paths := []string{
|
||||
filename, // Current dir
|
||||
"../" + filename, // One level up
|
||||
"../../" + filename, // Two levels up (for tests in internal/handlers)
|
||||
"../../../" + filename, // Three levels up
|
||||
}
|
||||
|
||||
for _, path := range paths {
|
||||
if _, err := os.Stat(path); err == nil {
|
||||
return path, nil
|
||||
}
|
||||
}
|
||||
|
||||
return "", fmt.Errorf("file not found: %s (searched: current dir, ../, ../../, ../../../)", filename)
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
package ui_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/juanatsap/cv-site/internal/models/ui"
|
||||
)
|
||||
|
||||
func TestLoadUI(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
lang string
|
||||
wantErr bool
|
||||
}{
|
||||
{
|
||||
name: "English UI",
|
||||
lang: "en",
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "Spanish UI",
|
||||
lang: "es",
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "Invalid language",
|
||||
lang: "fr",
|
||||
wantErr: true,
|
||||
},
|
||||
{
|
||||
name: "Empty language",
|
||||
lang: "",
|
||||
wantErr: true,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
uiData, err := ui.LoadUI(tt.lang)
|
||||
|
||||
if (err != nil) != tt.wantErr {
|
||||
t.Errorf("LoadUI() error = %v, wantErr %v", err, tt.wantErr)
|
||||
return
|
||||
}
|
||||
|
||||
if !tt.wantErr {
|
||||
if uiData == nil {
|
||||
t.Error("LoadUI() returned nil UI data")
|
||||
return
|
||||
}
|
||||
|
||||
// Validate UI has essential data
|
||||
if uiData.InfoModal.Title == "" {
|
||||
t.Error("LoadUI() returned UI with empty InfoModal title")
|
||||
}
|
||||
|
||||
if uiData.ShortcutsModal.Title == "" {
|
||||
t.Error("LoadUI() returned UI with empty ShortcutsModal title")
|
||||
}
|
||||
|
||||
// Validate TechStack is populated
|
||||
if uiData.InfoModal.TechStack.GoHono == "" {
|
||||
t.Error("LoadUI() returned UI with empty TechStack.GoHono")
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadUI_ModalData(t *testing.T) {
|
||||
uiData, err := ui.LoadUI("en")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadUI() failed: %v", err)
|
||||
}
|
||||
|
||||
// Test InfoModal structure
|
||||
if uiData.InfoModal.Description == "" {
|
||||
t.Error("InfoModal.Description should not be empty")
|
||||
}
|
||||
|
||||
if uiData.InfoModal.ViewSource == "" {
|
||||
t.Error("InfoModal.ViewSource should not be empty")
|
||||
}
|
||||
|
||||
// Test ShortcutsModal structure
|
||||
if uiData.ShortcutsModal.Description == "" {
|
||||
t.Error("ShortcutsModal.Description should not be empty")
|
||||
}
|
||||
|
||||
// Test that shortcuts sections exist
|
||||
if uiData.ShortcutsModal.Sections.Zoom.Title == "" {
|
||||
t.Error("Zoom shortcuts section should have a title")
|
||||
}
|
||||
|
||||
if uiData.ShortcutsModal.Sections.Actions.Title == "" {
|
||||
t.Error("Actions shortcuts section should have a title")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
package ui
|
||||
|
||||
import "html/template"
|
||||
|
||||
// UI represents user interface translations and configuration
|
||||
type UI struct {
|
||||
InfoModal InfoModal `json:"infoModal"`
|
||||
ShortcutsModal ShortcutsModal `json:"shortcutsModal"`
|
||||
}
|
||||
|
||||
type InfoModal struct {
|
||||
Title string `json:"title"`
|
||||
Description template.HTML `json:"description"`
|
||||
TechStack TechStack `json:"techStack"`
|
||||
ViewSource string `json:"viewSource"`
|
||||
ViewSourceSubtext string `json:"viewSourceSubtext"`
|
||||
}
|
||||
|
||||
type TechStack struct {
|
||||
GoHono string `json:"goHono"`
|
||||
HTMX string `json:"htmx"`
|
||||
HTML5 string `json:"html5"`
|
||||
CSS3 string `json:"css3"`
|
||||
}
|
||||
|
||||
type ShortcutsModal struct {
|
||||
Title string `json:"title"`
|
||||
Description string `json:"description"`
|
||||
Sections ShortcutsSections `json:"sections"`
|
||||
}
|
||||
|
||||
type ShortcutsSections struct {
|
||||
Zoom ShortcutGroup `json:"zoom"`
|
||||
ViewControls ShortcutGroup `json:"viewControls"`
|
||||
Navigation ShortcutGroup `json:"navigation"`
|
||||
Actions ShortcutGroup `json:"actions"`
|
||||
Browser ShortcutGroup `json:"browser"`
|
||||
}
|
||||
|
||||
type ShortcutGroup struct {
|
||||
Title string `json:"title"`
|
||||
ZoomIn *ShortcutItem `json:"zoomIn,omitempty"`
|
||||
ZoomOut *ShortcutItem `json:"zoomOut,omitempty"`
|
||||
ZoomReset *ShortcutItem `json:"zoomReset,omitempty"`
|
||||
ToggleLength *ShortcutItem `json:"toggleLength,omitempty"`
|
||||
ToggleIcons *ShortcutItem `json:"toggleIcons,omitempty"`
|
||||
ToggleTheme *ShortcutItem `json:"toggleTheme,omitempty"`
|
||||
ExpandAll *ShortcutItem `json:"expandAll,omitempty"`
|
||||
CollapseAll *ShortcutItem `json:"collapseAll,omitempty"`
|
||||
ScrollToTop *ShortcutItem `json:"scrollToTop,omitempty"`
|
||||
Print *ShortcutItem `json:"print,omitempty"`
|
||||
CloseModal *ShortcutItem `json:"closeModal,omitempty"`
|
||||
ShowHelp *ShortcutItem `json:"showHelp,omitempty"`
|
||||
Tab *ShortcutItem `json:"tab,omitempty"`
|
||||
Enter *ShortcutItem `json:"enter,omitempty"`
|
||||
}
|
||||
|
||||
type ShortcutItem struct {
|
||||
Key string `json:"key"`
|
||||
Description string `json:"description"`
|
||||
}
|
||||
@@ -176,18 +176,20 @@
|
||||
<!-- External JavaScript - CSP Compliant -->
|
||||
<script src="/static/js/main.js"></script>
|
||||
|
||||
<!-- Matomo Analytics -->
|
||||
<!-- Matomo Analytics - First-party subdomain to bypass ad blockers -->
|
||||
<script>
|
||||
var _paq = window._paq = window._paq || [];
|
||||
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
|
||||
_paq.push(['trackPageView']);
|
||||
_paq.push(['enableLinkTracking']);
|
||||
(function() {
|
||||
var u="https://matomo.drolo.club/";
|
||||
var u="https://matomo.morenorub.io/";
|
||||
_paq.push(['setTrackerUrl', u+'matomo.php']);
|
||||
_paq.push(['setSiteId', '4']);
|
||||
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
|
||||
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
|
||||
g.async=true;
|
||||
g.src=u+'matomo.js';
|
||||
s.parentNode.insertBefore(g,s);
|
||||
})();
|
||||
</script>
|
||||
<!-- End Matomo Code -->
|
||||
|
||||
Reference in New Issue
Block a user