Concepts and Architecture

Concepts and Architecture

Mental model

A Jul.IA process receives traffic on one or more listeners, selects a virtual server and location, applies policy and middleware, then serves content or forwards the request to another protocol endpoint.

client
  -> listener and TLS
  -> virtual host
  -> route match
  -> authentication / policy / middleware
  -> static handler, upstream proxy, application gateway, or protocol gateway
  -> logs, metrics, traces, and health state

Main building blocks

• Server - a listener and virtual-host definition.
• Location - a route matcher with one primary action.
• Upstream - a backend pool with balancing, health, and optional discovery.
• Middleware and policy - authentication, rate limits, compression, WAF, caching, and related controls.
• Admin plane - health endpoints, configuration operations, history, status, and the optional Console.
• Optional runtimes - capabilities compiled behind build tags, such as gRPC, HTTP/3, L4 streams, WAF, or WASM plugins.

Configuration and runtime lifecycle

Jul.IA is configuration-driven. A candidate configuration is parsed, validated, and preflighted before it is accepted through the managed apply path. Live changes use generation-based replacement so existing requests can drain while new requests use the new handler generation.

Not every field has the same lifecycle:

• Hot-reloadable changes can be published live.
• Restart-bound changes can be validated and staged for the next restart.
• Listener-sensitive changes depend on whether an address is new or already bound.

Use the reload semantics as the authority for current classification and guarantees.

Repository map

Area	Purpose
cmd/jul/	CLI entry point and subcommands
internal/app/	composition root, preflight, apply, and runtime lifecycle
internal/config/	TOML schema, parsing, defaults, and validation
internal/server/	HTTP server construction and reload machinery
internal/router/ and internal/handler/	request selection and actions
internal/upstream/	pools, health checks, and discovery
internal/admin/	admin API and Console backend
internal/observability/	metrics, access logging, and operational telemetry
docs/adr/	durable architecture decisions

The full and current map is maintained in docs/architecture.md.

Design principles

• One deployable binary, with optional capabilities selected at build time.
• Strict configuration: unknown or invalid known values fail closed.
• Invalid reloads do not replace the last serving configuration.
• Request input must not choose configuration-controlled destinations.
• Operational state and write locations should be explicit and least-privilege.

For deeper protocol background, use the concepts appendix.