Skip to main content

Boson Architecture

The Boson framework is built upon a clean, modular architecture that prioritizes performance, maintainability, and flexibility. This page provides a comprehensive overview of how the framework is structured and how its components interact.

Architectural Principles​

Boson's architecture is guided by several key principles:

  1. Separation of Concerns: Each component has a distinct responsibility with well-defined interfaces
  2. Modularity: Components are decoupled and can be used independently
  3. Composability: Components can be combined in flexible ways to build complex applications
  4. Performance: Optimized data flow with minimal overhead and efficient resource usage
  5. Testability: Components designed for easy testing in isolation
  6. Extensibility: Clear extension points for customization and enhancement

Core Architecture Layers​

Boson's architecture can be visualized as a stack of layers, each building upon the previous:

┌─────────────────────────────────────────┐
│            Application Layer            │
├─────────────────────────────────────────┤
│            Controller Layer             │
├─────────────────────────────────────────┤
│             Routing Layer               │
├─────────────────────────────────────────┤
│            Middleware Layer             │
├─────────────────────────────────────────┤
│              Server Layer               │
├─────────────────────────────────────────┤
│               HTTP Layer                │
├─────────────────────────────────────────┤
│           Core Foundation Layer         │
└─────────────────────────────────────────┘

1. Core Foundation Layer​

The foundation layer provides essential services used throughout the framework:

  • Memory Management: Smart pointers and RAII principles ensure proper resource handling
  • Event Loop: Asynchronous execution environment for handling multiple concurrent requests
  • Threading Model: Thread pool and work distribution for optimal performance
  • I/O Abstraction: Non-blocking input/output operations for handling many connections
  • Error Handling: Exception management and propagation throughout the application
  • Logging: Structured logging infrastructure for monitoring and debugging

2. HTTP Layer​

Built on the foundation layer, the HTTP layer manages the raw HTTP protocol:

  • Connection Management: Efficient TCP socket handling
  • HTTP Parser: Fast, secure parsing of HTTP messages
  • Protocol Implementation: HTTP/1.1 support with proper header handling
  • TLS Integration: Secure connection handling when configured
  • Buffer Management: Efficient data buffering for minimal copying

3. Server Layer​

The server layer encapsulates the HTTP server and provides an interface for the application:

  • Configuration: Server settings and environment management
  • Lifecycle Management: Proper server startup, shutdown, and request handling
  • Connection Pooling: Efficient reuse of connections
  • Resource Management: Proper cleanup when the server terminates
  • Monitoring Hooks: Performance monitoring and statistics collection

4. Middleware Layer​

The middleware layer enables processing of requests and responses through a chain of handlers:

  • Middleware Chain: Sequential processing of middleware functions
  • Error Middleware: Special middleware for error handling
  • Built-in Middleware: Common functionality like logging, CORS, etc.
  • Custom Middleware: Extension points for application-specific processing
  • Next Function: Control flow between middleware components

5. Routing Layer​

The routing layer directs incoming requests to the appropriate handler:

  • Route Matching: Path pattern matching with parameters
  • HTTP Method Handling: Different handlers for GET, POST, PUT, DELETE, etc.
  • Parameter Extraction: Path and query parameter parsing
  • Route Groups: Organizing related routes together
  • Router Mounting: Composable routers for modular applications

6. Controller Layer​

The controller layer organizes related route handlers into cohesive units:

  • Controller Classes: Group related functionality
  • Resource Management: RESTful resource handling
  • Request Processing: Business logic implementation
  • Response Generation: Creating appropriate HTTP responses
  • Error Handling: Controller-specific error management

7. Application Layer​

The application layer is where developers build their specific applications:

  • Business Logic: Application-specific code
  • Models: Data structures and business objects
  • Services: Reusable business logic
  • Configuration: Application-specific settings
  • Custom Middleware: Application-specific request processing

Component Interaction Diagram​

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐
│ Client  │────►│  HTTP   │────►│ Routing │────►│Middleware│────►│Controller│
│ Request │     │ Server  │     │  Layer  │     │  Chain   │     │  Action  │
└─────────┘     └─────────┘     └─────────┘     └──────────┘     └──────────┘
                                                                     │
┌─────────┐     ┌─────────┐     ┌─────────┐     ┌──────────┐         │
│ Client  │◄────│  HTTP   │◄────│Response │◄────│Middleware│◄────────┘
│Response │     │ Server  │     │ Object  │     │  Chain   │
└─────────┘     └─────────┘     └─────────┘     └──────────┘

Request Lifecycle​

A typical request flows through Boson's architecture as follows:

  1. Receive: Client sends HTTP request to server
  2. Parse: HTTP parser processes raw request data
  3. Create Request Object: Request object is created from parsed data
  4. Global Middleware: Global middleware processes the request
  5. Route Matching: Router matches request to a route
  6. Route Middleware: Route-specific middleware is applied
  7. Controller Action: Controller action or route handler is executed
  8. Generate Response: Response is generated with appropriate status, headers, and body
  9. Response Middleware: Response middleware is applied in reverse order
  10. Send Response: HTTP response is sent back to client

Extensibility Points​

Boson provides several mechanisms for extending functionality:

  1. Custom Middleware: Add processing logic to the request/response pipeline
  2. Route Handlers: Implement custom request handling logic
  3. Controller Classes: Organize related routes and business logic
  4. Custom Error Handlers: Process exceptions in application-specific ways
  5. Static File Handlers: Configure static file serving with custom options

Core Classes and Relationships​

The Boson framework revolves around several key classes that work together:

  • Server: The main class that configures and runs the HTTP server
  • Request: Represents an HTTP request with access to methods, headers, params, etc.
  • Response: Represents an HTTP response with methods to set status, headers, body, etc.
  • Middleware: Functions that process requests and responses in sequence
  • Router: Matches request paths to handlers and organizes related routes
  • Controller: Optional class-based organization of related route handlers

Performance Optimizations​

Boson incorporates various performance optimizations:

  1. Header-Only Components: Some components are implemented as header-only for compiler optimization
  2. Zero-copy Operations: Minimizing data copying where possible
  3. Request Pooling: Reusing request objects to reduce allocation overhead
  4. Efficient Routing: Fast path matching algorithms
  5. Minimal Dependencies: Few external dependencies to reduce overhead

Understanding this architecture will help you leverage Boson's capabilities effectively and extend the framework to meet your specific needs.