Nanobar

Overview

NanobarAPI is a Starlette-based application framework and DevSecOps regression system. It captures spans and traces from real application integrations, derives immutable RegressionBricks from that evidence, organizes those bricks into Nanobar test classes bound to a stable monitored boundary, and analyzes the resulting integration suite by application or service boundary — while keeping ordinary application development lightweight: AppBoxes run locally without Docker, routes stay thin, and controllers and workers reuse the same orchestration logic through a shared validation gate.

Problem

Regression coverage for a real API tends to decay one of two ways: brittle golden-file snapshots that break on every harmless refactor, or an integration surface that quietly goes untested because there's no lightweight way to turn what actually happened in production into durable, versioned test evidence. NanobarAPI's refactor-tolerant comparison addresses the first failure mode directly — it compares the selected input, selected output, and declared assertions at a monitored boundary, and treats the intermediate call path as diagnostic evidence rather than part of the regression contract, so an internal refactor that doesn't change observable behavior doesn't break the test.

Architecture

The canonical relationship the whole system is built around:

instrumented execution
    -> sanitized spans
    -> trace
    -> immutable RegressionBrick
    -> evidenced Nanobar binding
    -> Nanobar suite analysis
    -> AppBox and system-level dashboard views

• Span — one telemetry observation from one instrumented operation or boundary, sanitized before export or persistence.
• Trace — the linked spans belonging to one realized execution path; evidence of how a request occurred, not automatically the regression contract.
• RegressionBrick — an immutable, versioned request/output example derived from trace evidence. A replay never edits a brick in place; new evidence creates a new brick.
• Nanobar — a class of integration tests representing one stable monitored boundary, identified by (nanobar_type, monitor_target), accumulating many RegressionBricks (success, failure, and edge-case members) over time.
• AppBox — a named application or service division for organizing code, dependencies, Nanobars, and results. A composition and classification boundary, not a required process or container.
• Backend pipeline — api-route → validation_gate → controller → service → repository | external API | library | model, with the validation gate letting API routes and background workers reuse the same controller.

Engineering Decisions

A few of the decisions that shape how NanobarAPI actually behaves, not just what it's named:

• Refactor-tolerant comparison, not exact trace replay. Regression equivalence compares the selected input, selected output, and declared assertions at a monitored boundary. Intermediate span topology is diagnostic evidence by default and only becomes part of equivalence when an explicit policy promotes it — so an internal refactor that doesn't change observable behavior doesn't fail the test.
• A Nanobar is the test class; a RegressionBrick is the member — and the binding between them is recorded, not assumed. Each binding stores its own match method (exact, regex, fuzzy, trace, or manual) and confidence, even when a first implementation commonly binds one brick to one Nanobar.
• AppBoxes run locally without Docker. Keeping ordinary application development lightweight was a hard requirement, not a nice-to-have — a service can still be frozen into an importable package for bundling once the system moves toward a microservice architecture.
• Worker-database replay never targets production by default. Deterministic, environment-aware seeders establish a known starting state before replay, and the verdict compares the resulting transition against the brick — replay uses local, seeded, replica, or shadow state, initiated only by an authorized human from the DevSecOps Nanobar Admin application.
• No silently duplicated taxonomy identifiers. Legacy shorthand values (api-response, service-response) must be migrated to canonical explicit ones (api-request-response, service-request-response) at an explicit compatibility boundary — the system is not allowed to silently persist two identifiers for the same Nanobar class.

Repository

github.com/NDutraConsulting/NanobarAPI

NanobarAPI isn't fully polished yet — making the repository public is on my backlog, tracked as a TODO in the project's own README until it's done.