Skip to content
timbl

Architecture

Package Map

  • timbl: public runtime package for config authoring, startup, request handling, and official defaults
  • @timbl/core: public contract package for schema definitions, query primitives, plugin types, and adapter interfaces
  • @timbl/client: public framework-agnostic REST client built on top of the HTTP contract
  • @timbl/adapter-better-auth: official Better Auth integration
  • @timbl/plugin-rss: official optional RSS plugin
  • @timbl/plugin-seo: official optional SEO plugin

Dependency Direction

  • @timbl/core defines durable contracts
  • timbl depends on @timbl/core
  • @timbl/client depends on documented HTTP behavior, not runtime internals
  • optional packages depend on timbl and/or @timbl/core
  • applications depend on public packages only
  • examples and docs must not import from src/...

Layering

Core

Core contains:

  • schema and registry rules
  • validation and normalization
  • query contracts
  • serialization pipeline
  • plugin contracts
  • adapter interfaces

Runtime

Runtime contains:

  • config loading
  • adapter resolution
  • route construction
  • request handling
  • startup and shutdown behavior
  • official default integration wiring

HTTP Boundary

The stable runtime boundary is:

  • Request -> Response for serving CMS behavior
  • optional listen() for owning the process lifecycle

Hono is the official default delivery integration. The framework contract is the observable fetch/listen boundary, not Hono internals.

Public Surface Rules

  • timbl is the default package for most users
  • @timbl/core is the advanced contract package
  • unsafe is available for deliberate escape hatches only
  • undocumented internals are not semver-stable
  • ErrorCodes (in @timbl/core) is the canonical enum of error response codes; new codes are additive and semver-stable

Extraction Rule

A boundary only earns its own package when it has:

  • a clear independent user
  • a stable public API
  • dedicated documentation
  • dedicated tests
  • a release and compatibility story separate from repo internals

See also