juanatsap
faf3a2ca45
Created detailed ASCII diagrams documenting the entire system architecture: 1. System Architecture (_go-learning/diagrams/01-system-architecture.md) - Overall system architecture with client/server/storage layers - Layered architecture (Presentation → Application → Business → Data) - Component interaction and HTTP request flow - Data flow from app start through per-request lifecycle - Package dependencies and file organization
19 KiB
19 KiB
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 - Detailed HTTP request lifecycle
- Middleware Chain - Middleware execution order
- Handler Organization - Handler file structure