273 lines
19 KiB
Markdown
273 lines
19 KiB
Markdown
|
# 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
|