prod-guard-oss

Architecture Overview

This document describes the internal architecture of prod-guard, its core components, execution flow, and design decisions.

The goal of prod-guard’s architecture is to provide:

Zero-runtime overhead after startup
Clear separation between FREE and PREMIUM functionality
Deterministic, auditable production checks
Strong license enforcement without external dependencies

High-Level Architecture

prod-guard is a startup-time validation framework for Spring Boot applications. All checks are executed once during application startup.

There are no agents, background threads, schedulers, or network calls.


Application Startup
        |
        v
ProdGuardRunner
        |
        +-- License Verification
        |
        +-- Check Discovery
        |
        +-- License Gate (FREE / PREMIUM)
        |
        +-- Check Execution
        |
        +-- Result Aggregation
        |
        +-- Optional Startup Blocking

Core Components

ProdGuardRunner

ProdGuardRunner is the orchestration engine. It is executed during application startup and controls the entire lifecycle.

Responsibilities:

Detect active Spring profiles
Honor prodguard.force and prodguard.enabled
Trigger license verification
Discover available checks
Apply license gating
Execute allowed checks
Aggregate and log results
Optionally block application startup

ProdCheck

Each production rule is implemented as a ProdCheck.

A check is:

Stateless
Deterministic
Self-describing

Each check provides:

A unique code (e.g. PG-011)
A default severity
A human-readable message
A remediation hint

Checks are discovered automatically via Spring’s component scanning.

SeverityResolver

The SeverityResolver determines the effective severity of each finding.

Resolution order:

Explicit configuration override (prodguard.severity.*)
Check default severity

This allows teams to:

Disable specific checks
Downgrade blocking errors to warnings
Gradually adopt stricter policies

Licensing Architecture

LicenseVerifier

License validation is handled by the LicenseVerifier abstraction.

Two implementations exist:

NoopLicenseVerifier – FREE mode
SignedFileLicenseVerifier – PREMIUM mode

Selection is automatic based on configuration.

Signed License Model

prod-guard uses offline cryptographic licenses.

Ed25519 asymmetric signatures
Private key used only in license generation (CLI)
Public key embedded in runtime
No network calls
No callbacks

A license contains:

Licensee identifier
License tier (FREE / PREMIUM)
Issue date
Expiration date
Detached signature

LicenseContext

After verification, a LicenseContext is produced.

It represents the immutable result of license validation:

Validity (valid / invalid)
Licensee name
Expiration date

This context is evaluated exactly once at startup.

LicenseGate

LicenseGate enforces licensing at the check level.

By convention:

FREE checks → codes not starting with PG-2
PREMIUM checks → codes starting with PG-2

If a PREMIUM check is encountered without a valid license:

The check is skipped
A warning is logged

Execution Flow


1. Application starts
2. ProdGuardRunner invoked
3. Environment & profile detection
4. License verification
5. License expiration diagnostics
6. Check discovery
7. License gate filtering
8. Check execution
9. Result aggregation
10. Optional startup failure

Design Principles

Fail Fast

All validation happens before the application begins serving traffic.

Zero Runtime Cost

No background tasks, no polling, no memory retention after startup.

Offline First

prod-guard never requires network access.

Transparent Enforcement

Every decision is logged explicitly and auditable.

Enterprise-Ready

No vendor lock-in
No phone-home behavior
No hidden feature flags

Execution Model

prod-guard executes validation as part of the startup lifecycle, but not all checks run at the same moment.

To reflect this accurately, prod-guard uses a two-phase execution model.

Phase 1 — Pre-Start Validation (Static Checks)

When it runs

During application startup
Before the application is considered ready to serve traffic

What runs

Configuration-based checks
Environment validation
JVM, datasource, and framework defaults

Examples

JPA Open Session In View
Graceful shutdown configuration
Datasource pool sizing
Logging configuration
HTTP timeouts

Characteristics

No network calls
No runtime dependencies
Extremely fast
Safe in all environments

This phase applies to both FREE and PREMIUM editions.

Phase 2 — Post-Start Runtime Validation (Effective Checks)

Some production and security guarantees cannot be validated statically.

For example:

Are HTTPS redirects effective?
Are security headers actually present after proxies and filters?
Is CSP enforced or report-only?
Are cookies effectively marked Secure / HttpOnly?

These require observing the effective runtime behavior.

When it runs

Immediately after the applicattion is started
As part of the same startup lifecycle
Before prod-guard completes execution

What runs

Runtime HTTP/HTTPS checks
Effective security header validation
TLS and redirect enforcement

Examples

Effective HTTPS enforcement
HSTS configuration
CSP enforcement
Clickjacking protection
Cookie security flags

Characteristics

Performs real HTTP/HTTPS requests against localhost
Requires the server to be running
Executes synchronously
No background threads

This phase is PREMIUM-only.

Comparison with Traditional Monitoring

Aspect	Traditional Monitoring	prod-guard
Execution time	Runtime	Startup only
Purpose	Observation	Prevention
Failure handling	Alerts	Startup blocking
Licensing	Subscription / SaaS	Offline signed license

Next Steps

← Back to index