Weber Architecture

Overview

Weber is a hybrid web framework that combines a Go backend with a Preact frontend, offering both server-side rendering (SSR) and client-side interactivity. The architecture is designed for flexibility, allowing you to build anything from static websites to complex web applications.

High-Level Architecture

┌─────────────────────────────────────────────────────┐
│                   Client Browser                    │
│  ┌──────────────┐         ┌──────────────────────┐ │
│  │ Static HTML  │         │  Preact Components   │ │
│  │  (Templates) │         │  (Hydrated Islands)  │ │
│  └──────────────┘         └──────────────────────┘ │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│               Go Backend Server                     │
│  ┌────────────────────────────────────────────────┐ │
│  │            Routing Layer                       │ │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │ │
│  │  │  Static  │  │   API    │  │   Pages     │ │ │
│  │  │  Routes  │  │  Routes  │  │   Routes    │ │ │
│  │  └──────────┘  └──────────┘  └─────────────┘ │ │
│  └────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────┐ │
│  │         Application Layer                      │ │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │ │
│  │  │ Template │  │  Cache   │  │   Logger    │ │ │
│  │  │  Engine  │  │  System  │  │   System    │ │ │
│  │  └──────────┘  └──────────┘  └─────────────┘ │ │
│  └────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────┐ │
│  │           Data Layer                           │ │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │ │
│  │  │  Models  │  │ Database │  │   HTTP      │ │ │
│  │  │          │  │          │  │   Client    │ │ │
│  │  └──────────┘  └──────────┘  └─────────────┘ │ │
│  └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│           External Services & APIs                  │
│  ┌──────────┐  ┌──────────┐  ┌─────────────────┐  │
│  │   News   │  │ Football │  │   Advertisement │  │
│  │   APIs   │  │   APIs   │  │    Services     │  │
│  └──────────┘  └──────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────┘

Rendering Strategy

Weber employs a hybrid rendering approach:

1. Server-Side Rendering (SSR)

  • Initial page load is rendered on the server using Go templates
  • Fast first contentful paint (FCP)
  • SEO-friendly content
  • Works without JavaScript

2. Island Architecture (Partial Hydration)

  • Interactive Preact components are "islands" of interactivity
  • Components hydrate independently on the client
  • Reduces JavaScript bundle size
  • Improves performance by only hydrating what's needed

3. Client-Side Rendering (CSR)

  • Preact components handle dynamic interactions
  • State management for complex UIs
  • API calls for data fetching

Backend Architecture

Modular Design

The backend is organized into focused modules:

  • app/ - Core application framework
    • HTTP server setup
    • Request/response handling
    • Template rendering
    • Middleware system
  • route/ - Route handlers
    • Page handlers (index, about, news, etc.)
    • API endpoints
    • Route registration
  • model/ - Data models
    • Data structures
    • Business logic
    • Data transformation
  • http/ - HTTP client utilities
    • External API calls
    • Response caching
    • Error handling
  • logger/ - Logging system
    • Structured logging
    • Log levels
    • Performance tracking

Frontend Architecture

Component-Based

Preact components are organized by purpose:

  • components/ - Reusable UI components
    • Button, Card, Modal, etc.
    • Self-contained and composable
  • pages/ - Page-level components
    • Complete page implementations
    • Route-specific logic
  • layouts/ - Layout components
    • Common page structures
    • Header, footer, sidebar
  • utils/ - Utility functions
    • Helper functions
    • API clients
    • State management

Build System

Custom Node.js build system for flexibility:

  • Component bundling
  • Asset optimization
  • Template injection
  • Development mode with hot reload

Request Flow

Page Request

1. Browser requests /news
                ↓
2. Go router matches route
                ↓
3. Route handler executed
                ↓
4. Data fetched from APIs/cache
                ↓
5. Template rendered with data
                ↓
6. HTML sent to browser
                ↓
7. Browser parses HTML
                ↓
8. Preact bundles loaded
                ↓
9. Interactive components hydrate
                ↓
10. Page is fully interactive

API Request

1. Client component makes API call
                ↓
2. Go router matches API route
                ↓
3. Handler processes request
                ↓
4. Data fetched/computed
                ↓
5. JSON response sent
                ↓
6. Component updates state
                ↓
7. UI re-renders

Caching Strategy

Multi-layer caching for optimal performance:

1. HTTP Response Cache

  • Cache external API responses
  • Configurable TTL
  • Reduces external API calls

2. Template Cache

  • Parsed templates cached in memory
  • Faster rendering
  • Development mode disables cache

3. Application Cache

  • Custom caching layer
  • Page-level caching
  • Invalidation strategies

4. Browser Cache

  • Static assets with cache headers
  • Content hashing for cache busting

Configuration Management

Environment-based configuration:

config/
├── dev.json      # Development settings
├── test.json     # Test settings
└── prod.json     # Production settings

Configuration is loaded at startup based on the WEBER_ENV environment variable. Each environment can have different:

  • Server settings (port, host)
  • Database connections
  • Cache settings
  • Logging levels
  • External API endpoints

Error Handling

Comprehensive error handling at multiple levels:

Backend

  • Panic recovery middleware
  • Structured error logging
  • Custom error pages (404, 500)
  • Error response formatting

Frontend

  • Error boundaries for components
  • API error handling
  • User-friendly error messages

Security Considerations

  • Input Validation - All user input is validated and sanitized
  • CORS - Configurable CORS policies
  • Headers - Security headers (CSP, X-Frame-Options, etc.)
  • Authentication - OAuth integration support
  • HTTPS - Production deployments use HTTPS

Performance Optimization

Backend

  • Efficient Go concurrency patterns
  • Response caching
  • Connection pooling
  • Optimized logging (minimal allocations)

Frontend

  • Code splitting
  • Lazy loading
  • Preact's small bundle size (~3KB)
  • Asset optimization (minification, compression)

Network

  • HTTP/2 support
  • Gzip compression
  • CDN-ready static assets
  • Efficient caching headers

Scalability

Weber is designed to scale:

Horizontal Scaling

  • Stateless backend servers
  • Load balancer compatible
  • Shared cache layer possible

Vertical Scaling

  • Efficient resource usage
  • Go's lightweight goroutines
  • Tunable concurrency limits

Development Workflow

┌────────────────────────────────────────────┐
│        Development Environment             │
│  ┌──────────────┐    ┌──────────────────┐ │
│  │   Backend    │    │    Frontend      │ │
│  │  (Hot Reload)│    │  (Watch Mode)    │ │
│  └──────────────┘    └──────────────────┘ │
│         │                    │             │
│         └────────┬───────────┘             │
│                  │                         │
│         Live Reload/HMR                    │
└────────────────────────────────────────────┘

Next Steps