Brick Framework: Designing a Contract-Driven, Modular Backend Framework from First Principles

Introduction

Backend systems often accumulate complexity gradually. Routing logic blends into validation, business rules leak into infrastructure layers, and configuration errors surface only at runtime. Over time, this erosion of boundaries increases cognitive load and makes safe refactoring difficult. Brick Framework was designed to challenge that pattern by structuring backend infrastructure around explicit contracts, deterministic lifecycle management, and modular boundaries.

The Philosophy: Contracts as First-Class Citizens

At the center of Brick Framework is a contract-driven philosophy. OpenAPI definitions written in YAML are not treated as documentation artifacts but as executable runtime contracts. During application startup, the framework parses the OpenAPI file and constructs a strongly typed in-memory model representing paths, HTTP methods, parameters, request bodies, responses, schemas, components, and security schemes.

This model drives runtime behavior. Every incoming request is validated against the declared schema. Every outgoing response is verified before being returned. By elevating contracts to infrastructure-level enforcement, business logic becomes isolated from HTTP parsing, validation rules, and structural assumptions. The API definition becomes the single source of truth.

Designing the OpenAPI Parsing Engine

Parsing YAML is trivial compared to validating and modeling it correctly. The OpenAPI parser in Brick Framework is structured around well-defined abstractions. Each HTTP method extends an abstract HttpMethod class that encapsulates method-specific semantics and validation behavior. This avoids central conditional logic and distributes responsibility to method-level implementations.

Schema handling follows a similar polymorphic structure. An abstract Schema class defines the validation contract, and concrete implementations such as IntegerSchema, StringSchema, ArraySchema, ObjectSchema, and composition schemas like AllOfSchema, AnyOfSchema, and OneOfSchema implement their own validation logic. Instead of switching on schema type, the framework delegates behavior to the schema instance itself. A SchemaFactory centralizes schema creation, separating parsing from instantiation.

Handling Schema References and Cyclic Dependencies

OpenAPI schemas frequently reference other schemas, sometimes recursively. Improper handling of references can result in infinite loops or inconsistent validation behavior. To address this, Brick Framework builds a schema reference graph during startup and performs cycle detection using depth-first search.

By treating schema references as a directed graph problem, the framework ensures that circular dependencies are detected before serving traffic. This approach reinforces the fail-fast philosophy and prevents subtle runtime failures.

Annotation-Driven Service Registration

Beyond API parsing, Brick Framework includes an annotation-driven service model. Custom annotations such as Service, Validator, Identifier, and AutoInitialize allow classes to be discovered and managed automatically.

Annotation scanning occurs across both project classes and dependent JAR files, enabling modular architectures where services can live in separate repositories. This scanning process constructs metadata describing available services and validators, which is then used to wire the system together without explicit configuration files.

Dependency Resolution Using Graph Algorithms

The AutoInitialize mechanism is built on explicit graph theory concepts. Each annotated class is treated as a node in a dependency graph. Constructor parameters define directed edges to other nodes. The framework first performs cycle detection to ensure there are no circular dependencies between services.

After validation, it calculates the indegree of each node, representing the number of dependencies required for instantiation. Classes with zero indegree are instantiated first. As objects are created, the indegree of dependent classes is reduced. This process continues until all eligible classes are initialized. The result is deterministic, reflection-assisted dependency resolution without hidden magic or runtime surprises.

Execution Environment and Service Orchestration

Service communication within Brick Framework is mediated through an ExecutionEnvironment abstraction. Services do not directly invoke each other by concrete reference. Instead, they operate within an execution context identified by execution IDs.

This decoupling enables orchestration logic to remain centralized and supports the composite pattern through constructs such as ServiceGroup and SingleService. A group of services can execute as a single logical unit while preserving independent service behavior. This approach encourages modular composition without tight coupling.

Threading and Infrastructure Isolation

Threading is applied selectively in infrastructure components. Blocking operations such as logging or heavy startup tasks are isolated from request-processing threads. Concurrency decisions are deliberate and bounded, avoiding shared mutable state wherever possible. The objective is not parallelism for its own sake, but predictable performance and isolation of latency-sensitive paths.

Fail-Fast Startup Validation

One of the defining characteristics of Brick Framework is its aggressive startup validation. The framework verifies OpenAPI correctness, controller configuration, parameter bindings, validator method signatures, duplicate execution identifiers, and schema integrity before the application begins serving traffic.

This fail-fast model shifts error detection left in the development lifecycle. Instead of discovering misconfigurations under production load, developers receive immediate feedback during startup, reducing operational risk and increasing confidence.

Supporting Modular Monolith Architecture

Brick Framework is designed to enable modular monolithic systems. Business services can reside in separate repositories and be included as dependencies. The API layer remains centralized, exposing endpoints defined in OpenAPI files. Annotation scanning across JAR files ensures services and validators are discoverable without tightly coupling modules.

This structure enables teams to scale codebases structurally while maintaining deployment simplicity. It provides many of the organizational benefits of microservices without introducing distributed system overhead prematurely.

Quality Enforcement Through CI/CD

All repositories associated with Brick Framework follow strict CI/CD practices. Pull requests trigger compilation checks, unit tests with minimum coverage thresholds, and static code analysis. Only after passing these gates and code review can changes be merged. Automated tagging, package publishing, and version bumping ensure reproducible releases and traceable artifacts.

Brick Framework represents an exploration of backend infrastructure design grounded in first principles. By combining contract-driven validation, polymorphic abstractions, graph-based dependency resolution, modular architecture, and disciplined quality enforcement, it demonstrates how complexity can be structured rather than avoided.

The central insight behind the framework is simple: correctness enforced early, responsibilities separated clearly, and dependencies modeled explicitly result in backend systems that are easier to evolve and safer to maintain.