# System Architecture Diagram

## Overall System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         CV Website System                        │
│                                                                  │
│  ┌────────────┐         ┌────────────┐        ┌──────────────┐ │
│  │   Client   │────────▶│   Server   │───────▶│   Storage    │ │
│  │  Browser   │◀────────│  (Bun/Go)  │◀───────│  (Static)    │ │
│  └────────────┘         └────────────┘        └──────────────┘ │
│       │                       │                       │          │
│       │ HTMX                  │ Templates             │ JSON     │
│       │ HTTP                  │ Rendering             │ Files    │
│       │                       │                       │          │
│       ▼                       ▼                       ▼          │
│  ┌────────────┐         ┌────────────┐        ┌──────────────┐ │
│  │   UI/UX    │         │  Handlers  │        │ Data Models  │ │
│  │ Components │         │ Middleware │        │   CV/UI      │ │
│  └────────────┘         └────────────┘        └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Layered Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                        Presentation Layer                         │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  HTML Templates + HTMX + Hyperscript + CSS                 │  │
│  │  - Server-side rendering                                    │  │
│  │  - Hypermedia-driven architecture                          │  │
│  │  - Progressive enhancement                                  │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                        Application Layer                          │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  HTTP Handlers (internal/handlers/)                         │  │
│  │  ┌──────────────┬──────────────┬──────────────┐            │  │
│  │  │ cv_pages.go  │ cv_htmx.go   │ cv_pdf.go    │            │  │
│  │  │ Page render  │ HTMX toggles │ PDF export   │            │  │
│  │  └──────────────┴──────────────┴──────────────┘            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Middleware Chain (internal/middleware/)                    │  │
│  │  Recovery → Logger → SecurityHeaders → Preferences         │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                         Business Layer                            │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Data Models (internal/models/)                             │  │
│  │  ┌──────────────┬──────────────┬──────────────┐            │  │
│  │  │ cv/          │ ui/          │ Validation   │            │  │
│  │  │ CV data      │ UI strings   │ Rules        │            │  │
│  │  └──────────────┴──────────────┴──────────────┘            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Services (internal/pdf/, internal/lang/)                   │  │
│  │  - PDF generation (chromedp)                                │  │
│  │  - Language handling                                        │  │
│  │  - Template management                                      │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                          Data Layer                               │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Static Files                                               │  │
│  │  ┌──────────────┬──────────────┬──────────────┐            │  │
│  │  │ data/        │ templates/   │ static/      │            │  │
│  │  │ cv-*.json    │ *.html       │ css/js/      │            │  │
│  │  │ ui-*.json    │ partials/    │ images/      │            │  │
│  │  └──────────────┴──────────────┴──────────────┘            │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
```

## Component Interaction

```
┌─────────────────────────────────────────────────────────────────┐
│                    HTTP Request Flow                             │
└─────────────────────────────────────────────────────────────────┘

Client Request
     │
     ├─→ Browser sends HTTP/HTMX request
     │
     ▼
┌─────────────┐
│   Router    │  Match URL pattern
│ (ServeMux)  │  ├─ / → Home
└─────────────┘  ├─ /cv → CVContent
     │           ├─ /toggle/* → HTMX handlers
     ▼           └─ /export/pdf → ExportPDF
┌─────────────┐
│ Middleware  │  Execute middleware chain
│   Chain     │  ├─ Recovery (panic handler)
└─────────────┘  ├─ Logger (request logging)
     │           ├─ SecurityHeaders (CSP, HSTS)
     ▼           └─ PreferencesMiddleware (cookies → context)
┌─────────────┐
│  Handler    │  Process request
│  Function   │  ├─ Parse request (typed)
└─────────────┘  ├─ Load data (models)
     │           ├─ Prepare template data
     ▼           └─ Render response
┌─────────────┐
│  Template   │  Server-side rendering
│  Rendering  │  ├─ Load template
└─────────────┘  ├─ Execute with data
     │           └─ Generate HTML
     ▼
┌─────────────┐
│  Response   │  Send to client
│  (HTML/PDF) │  └─ HTTP 200 OK
└─────────────┘
     │
     ▼
Client receives response
```

## Data Flow

```
┌────────────────────────────────────────────────────────────────┐
│                      Data Flow Diagram                          │
└────────────────────────────────────────────────────────────────┘

                        Application Start
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Load Configuration (config.Load())      │
        │  ├─ Server settings (port, timeouts)     │
        │  └─ Template settings (dir, hot reload)  │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Initialize Template Manager             │
        │  ├─ Scan template directory              │
        │  ├─ Parse all templates                  │
        │  └─ Cache compiled templates             │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Initialize Handlers                     │
        │  └─ CVHandler with template manager      │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Setup Routes + Middleware               │
        │  └─ routes.Setup(cvHandler, ...)        │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Start HTTP Server                       │
        │  └─ Listen on :8080                     │
        └──────────────────────────────────────────┘
                               │
                               ▼
                      Ready for Requests

─────────────────────────────────────────────────────────────────

                      Per-Request Flow
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Request arrives                         │
        │  └─ GET /?lang=es                       │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  PreferencesMiddleware reads cookies     │
        │  ├─ cv-length = "long"                   │
        │  ├─ cv-icons = "show"                    │
        │  ├─ cv-language = "es"                   │
        │  └─ Store in request context             │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Handler.Home() called                   │
        │  ├─ Get preferences from context         │
        │  ├─ Validate language                    │
        │  └─ Call prepareTemplateData("es")      │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Load Data                               │
        │  ├─ cvmodel.LoadCV("es")                │
        │  │  └─ Read data/cv-es.json             │
        │  └─ uimodel.LoadUI("es")                │
        │     └─ Read data/ui-es.json             │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Process Data                            │
        │  ├─ Calculate durations                  │
        │  ├─ Split skills into columns            │
        │  └─ Add SEO metadata                     │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Render Template                         │
        │  ├─ Get cached template                  │
        │  ├─ Execute with data map                │
        │  └─ Generate HTML                        │
        └──────────────────────────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────┐
        │  Send Response                           │
        │  └─ HTTP 200 + HTML body                │
        └──────────────────────────────────────────┘
```

## Package Dependencies

```
main.go
  ├─→ internal/config
  ├─→ internal/templates
  ├─→ internal/handlers
  │    ├─→ internal/middleware
  │    ├─→ internal/models/cv
  │    ├─→ internal/models/ui
  │    ├─→ internal/pdf
  │    └─→ internal/templates
  ├─→ internal/routes
  │    ├─→ internal/handlers
  │    └─→ internal/middleware
  └─→ internal/middleware

internal/handlers/
  ├─ cv.go (constructor)
  ├─ cv_pages.go (renders)
  ├─ cv_htmx.go (toggles)
  ├─ cv_pdf.go (PDF export)
  ├─ cv_helpers.go (utilities)
  ├─ types.go (request/response)
  └─ errors.go (error handling)

internal/middleware/
  └─ preferences.go (cookie → context)

internal/models/
  ├─ cv/ (CV data structures)
  └─ ui/ (UI text structures)
```

## Related Diagrams

- [Request Flow](./02-request-flow.md) - Detailed HTTP request lifecycle
- [Middleware Chain](./03-middleware-chain.md) - Middleware execution order
- [Handler Organization](./04-handler-organization.md) - Handler file structure