openframe-core

The foundation package of the OpenFrame Microservice Development Suite — the unified port + lifecycle contract layer, structured exceptions, telemetry, and ASGI middleware for any hexagonal architecture Python service. Every ecosystem package pins openframe-core>=3.0,<4.

openframe-core is built around a single unified contract layer: BasePort (Identity + Lifecycle) is the one base every outbound port and every registrable plugin extends — there is no separate health protocol and no separate plugin protocol. The error hierarchy is consolidated under a single OpenFrameError root. The full contract layer, including the capability-specific outbound protocols (BaseRepository, BaseProducer, BaseConsumer), lives in openframe.core.ports. See ADR-006 for the full design rationale.

---

Developer Guide

Section	Contents
Quick Start	Working integration in 5 minutes
How It Works	Hexagonal architecture in plain language
First Code Change	Smallest meaningful change to the package
Debugging Guide	OpenFrameError traces, OTel spans, common failures

Technical Documentation

Section	Contents
System Overview	What the package does, unified contract layer, key design properties
Architecture	Module dependency DAG, both sides of the hexagon
Package Journey	How a request moves from registry wiring through adapter to response
ADRs	Six architectural decision records from the design and review process
Capability Taxonomy	The Capability enum reference
Error Taxonomy	The OpenFrameError hierarchy and domain.kind code convention
Infrastructure	Modal platform, devpi registry, GitHub Actions
Deployment	Environments, secrets, CI/CD pipeline
Operations	Monitoring, runbooks for six failure scenarios

Code Documentation

Section	Contents
Getting Started	Install, configure, smoke test
Modules	Function and class reference for all core modules
CI/CD	GitHub Actions workflows