tiko-di
Compile-time orchestrator for Java 21+
A compile-time orchestrator for Java 21+. An annotation processor validates and generates all the wiring: no reflection, no classpath scanning. DI and an event bus ship in the core; HTTP, databases and caches plug in directly via @Produces.
On Maven Central · Java 21–27
From the README
A compile-time orchestrator for Java 21+: dependency injection and an event bus in the core, your libraries plugged in through
@Produces
Website: tomas-samek.github.io/tiko-di · Status: on Maven Central (latest version in the badge above). Suitable for early-adopter experimentation. See docs/roadmap.md for what ships today and what’s next.
What Tiko is
A compile-time orchestrator with an integrated event model and full compile-time validation.
Tiko orchestrates, it doesn’t bundle — direct access, compile-time safe, nothing wrapped.
The container, the scopes, the event bus, and the wiring graph ship as the framework. HTTP servers, databases, caches, template engines, security libraries, and any other library — you bring directly, and tiko orchestrates the seam via @Produces. Nothing is wrapped or rewritten on the library side; nothing is re-invented on the framework side.
For the design principles behind it — three-layer architecture, event-pipeline trade-offs, and the direction it is headed — see docs/VISION.md.
Quick example
// 1. Define your components
@Component(scope = Scope.SINGLETON)
public class UserRepository {
public User findById(String id) { /* ... */ return null; }
}
@Component(scope = Scope.SINGLETON)
public class UserService {
private final UserRepository repository;
@Inject
public UserService(UserRepository repository) {
this.repository = repository;
}
public User getUser(String id) {
return repository.findById(id);
}
}
// 2. Use the container
public class Main {
public static void main(String[] args) {
try (Container container = Tiko.create()) {
UserService service = container.get(UserService.class);
User user = service.getUser("123");
}
}
}
The annotation processor validates all dependencies at compile-time and generates the wiring code — plain Java you can read and step through. No reflection, no classpath scanning in your wiring.
Lifecycle & imperative publish. Tiko.create(...) returns an AutoCloseable container you manage (try-with-resources above). For a long-lived process — an HTTP service, a Kafka consumer, a scheduler — use Tiko.daemon(...) (it installs a graceful-shutdown hook so @PreDestroy runs on Ctrl+C / SIGTERM) and keep the process alive with the one canonical idiom daemon.awaitShutdown(); an HTTP server is a component the container starts and stops (HTTP cookbook). To publish events imperatively from inside a component, inject EventBus as a constructor dependency — it is built-in, no plain-class workaround. Details: the tiko-build skill and events.md.
Installation
Tiko ships to Maven Central. Import the BOM once — then declare the artifacts (and the annotation-processor path) without restating the version:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.tomas-samek</groupId>
<artifactId>tiko-bom</artifactId>
<version>0.7.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.tomas-samek</groupId>
<artifactId>tiko-api</artifactId>
</dependency>
<dependency>
<groupId>io.github.tomas-samek</groupId>
<artifactId>tiko-runtime</artifactId>
</dependency>
<!-- Optional, only if you use @Configuration -->
<dependency>
<groupId>io.github.tomas-samek</groupId>
<artifactId>tiko-config</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>io.github.tomas-samek</groupId>
<artifactId>tiko-processor</artifactId>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
The tiko-bom import is the single place the version lives; maven-compiler-plugin ≥ 3.12.0 resolves the annotationProcessorPaths version from it too (3.13.0 pinned above for JDK 23+ — see the note below). The BOM also manages the optional tiko-kafka / tiko-mcp / tiko-test modules.
On JDK 23+?
javacno longer runs annotation processing implicitly — the snippet above is already correct (it requiresmaven-compiler-plugin≥ 3.13.0). For Gradle, plainjavac, and the legacy<proc>full</proc>opt-in, see docs/jdk-23-setup.md.
Scaffold a new project (archetype)
The fastest way to start a fresh project — generates a runnable single-module Tiko DI project with a minimal Main + one @Component, plus AI-assistant context files:
mvn archetype:generate \
-DarchetypeGroupId=io.github.tomas-samek \
-DarchetypeArtifactId=tiko-archetype \
-DarchetypeVersion=0.7.0 \
-DgroupId=com.example \
-DartifactId=my-app \
-DinteractiveMode=false
cd my-app
mvn compile exec:java # prints: Hello, world!
The generated project ships with AI-context files for the major coding agents — CLAUDE.md (canonical), AGENTS.md, .cursor/rules/tiko.md, .github/copilot-instructions.md, .junie/guidelines.md, .ai-skills/SKILL.md, and .ai-skills/tiko-build/SKILL.md (the orchestrator-model skill — decision tree + @Produces cookbook + anti-pattern redirects). Each tool-specific file points at the canonical sources, so edit one file when conventions change.
Your first service
- Step by step: docs/getting-started.md builds a small HTTP + database + event service with a test, one file at a time.
- Reference shape?
tiko-examples/15_quickstart— the finished service from that page, and the canonical small service the skill cites. Copy it out of a release tag, 0.8.0 or later, to start your own. - Scaffold a fresh project? Maven archetype — see Scaffold a new project above.
- Long-form prose?
docs/orchestrator-model.md, the recipes behind the shape. - Kotlin? Gradle + KSP is supported — setup, construct rules and nullability rules are in
reference/kotlin.md; runnable builds:tiko-examples-gradle/(quickstart, Ktor + Exposed REST API, Kafka consumer, transactional outbox). Coroutines are the next Kotlin milestone:suspendhandlers and bridges (Kotlin K2).
The three buckets
Every concern in a tiko-built service lands in exactly one bucket. Classify, then write code.
Core — what tiko ships
DI container, scopes (SINGLETON / EVENT / PROTOTYPE), event bus, @EventHandler + @EventTrigger, compile-time validation, lifecycle hooks (@PostConstruct, @PreDestroy, ApplicationStartedEvent, ApplicationEndingEvent), @Configuration typed records.
Plug in — you bring the library; tiko orchestrates the seam
HTTP (Javalin, Jetty, Spark, Vert.x), DataSource (HikariCP, Agroal), schema migrations (Flyway, Liquibase), caching (Caffeine), templates (FreeMarker, Pebble), security (JWT / OAuth via the library of your choice), schedulers, retries, any SDK client. Pattern: declare a factory method annotated @Produces, return the library’s value, consume as a constructor parameter. A server that receives the application’s requests is a @Component the container starts and stops instead (HTTP cookbook). No wrapper, no adapter layer, no annotation-driven dispatch.
Open design questions
Scheduling-as-tick-event, units of work that nest — the small set of unresolved questions about extending the event model itself. An honest scope note, not a deferral promise.
What you plug in
Lookup-table answer to “does tiko support X?”:
| Need | Pattern | Recipe in |
|---|---|---|
| HTTP layer | A server @Component owning Javalin (or your choice) + plain route methods, one unit of work per request |
docs/cookbooks/http.md, example 15_quickstart |
| Postgres / MySQL | @Produces DataSource returning HikariDataSource |
tiko-build skill, example 15_quickstart |
| Schema migrations | Flyway.migrate() in the DataSource producer, before it returns the pool |
tiko-build skill, example 15_quickstart |
| Kafka | @KafkaSource / @KafkaSink — tiko-native module with compile-time validation |
tiko-kafka, example 08_kafka_order_warehouse |
| In-process cache | @Produces Cache<K,V> (Caffeine) |
tiko-build skill |
| Templates | @Produces freemarker.template.Configuration (or Pebble, Mustache) |
tiko-build skill |
| Security | Javalin before handler + Context attributes (open-design caveat in the model doc §6) |
docs/orchestrator-model.md §6 |
| Scheduling | @EventHandler on a Tick event published by a small scheduler thread |
docs/orchestrator-model.md §4.2 |
| Async work | @EventHandler(async = true) for event-shaped work; CompletableFuture / virtual threads for ad-hoc |
docs/orchestrator-model.md §4.3 |
| Retry | Small utility wrapper — visible code, no AOP | docs/orchestrator-model.md §4.4 |
| Configuration | Typed @Configuration records |
tiko-config, example 02_config |
| Metrics / tracing | Plug in your library; expose via routes on your HTTP layer | — |
Annotations at a glance
| Annotation | Purpose | Deep dive |
|---|---|---|
@Component(scope, name, profiles) |
Marks a class for DI | di-and-scopes.md |
@Inject |
Marks the constructor to wire (constructor-only — no field injection) | di-and-scopes.md |
@Named("...") / @Pick(Class) |
Disambiguate when multiple impls exist (string vs class-literal) | di-and-scopes.md |
@Produces(scope, name, profiles) |
Factory method — instance or static | di-and-scopes.md |
@PostConstruct / @PreDestroy |
Lifecycle hooks (AutoCloseable is the recommended cleanup form) |
di-and-scopes.md |
@Configuration(prefix) |
Marks a record as a YAML-backed config root | configuration.md |
@EventHandler(async, eventType) |
Subscribe to events (sync by default, opt-in async) | events.md |
@EventTrigger(eventName, ...) |
Declarative event chains — return-as-payload, guards, spread, async | events.md |
Scopes: SINGLETON > EVENT > PROTOTYPE (longest to shortest lifetime). An EVENT bean injected into a SINGLETON is proxied automatically; every other combination is injected directly — see docs/di-and-scopes.md.
Runnable examples
Worked examples ship under tiko-examples/, each a Maven module of this repository’s build: it builds against the repository’s current snapshot, so run mvn install -DskipTests from the root first. 15_quickstart is a standalone project as well: copy it out of a release tag, 0.8.0 or later, and it builds against that release from Maven Central. So do the Gradle builds under tiko-examples-gradle/.
| # | Module | Demonstrates |
|---|---|---|
| 01 | 01_basic_di |
@Component, scopes, cross-scope proxies, @Produces, @Named, @Pick, Provider<T>, Picker<T>, pick() |
| 02 | 02_config |
@Configuration records, layered ConfigSources, ${VAR} interpolation |
| 03 | 03_events |
Lifecycle events, @EventTrigger chains with guards/spread/async, Event<?> origin tracking |
| 04 | 04_api_impl |
API/impl split — app compiles against an interface jar, impl supplied at runtime |
| 05 | 05_multi_module |
Multi-module aggregation via AggregatingContainer |
| 06 | 06_config_multi_module |
Module-baked META-INF/tiko/defaults.yaml discovery + user override |
| 07 | 07_async_start |
@EventHandler(async = true) on ApplicationStartedEvent — keep slow warmup off the critical path |
| 08 | 08_kafka_order_warehouse |
Cross-JVM Kafka demo — @KafkaSource / @KafkaSink, shared event class, Testcontainers e2e |
| 09 | 09_http_javalin |
TikoJavalin.scoped opens a unit of work per request through UnitOfWork, in a server the container starts and stops; sync request→response independent of the bus |
| 10 | 10_persistence_jdbc |
Persistence cookbook — an EVENT-scoped JDBC transaction across a batch loop (docs) |
| 11 | 11_custom_logger |
Routing framework logs through slf4j + logback via System.LoggerFinder |
| 12 | 12_testing |
@TikoTest JUnit 5 extension — parameter resolution, RecordingEventBus assertions, scope helpers, awaitAsyncDispatch |
| 13 | 13_mcp_introspection |
Runnable demo of the tiko-mcp topology server reading a built project’s META-INF/tiko/ artifacts |
| 14 | 14_profiles |
@Component(profiles = "...") — dev/prod implementation switching with default-profile resolution |
| 15 | 15_quickstart |
Orchestrator-model reference app — HikariCP + Javalin + event-driven handler the tiko-build skill cites |
| 16 | 16_async_scope |
Separate EVENT units for synchronous and asynchronous handlers |
| 17 | 17_transactional_outbox |
HTTP to Kafka across two databases, transactional outbox, durable deduplication and crash recovery |
Modules
| Module | Purpose |
|---|---|
tiko-api |
Core annotations and interfaces. The only compile-time dependency your code needs. |
tiko-processor |
Annotation processor — runs at compile-time to validate dependencies and generate wiring code. |
tiko-runtime |
Minimal runtime container. Zero dependencies beyond tiko-api. Ships the in-memory LocalEventBus. |
tiko-config |
YAML-backed configuration injection. The only module that depends on SnakeYAML. Required when your project uses @Configuration; not pulled otherwise. |
tiko-test |
JUnit 5 extension + compile-time @TestComponent overrides + runtime TikoOptions.override(...) + RecordingEventBus spy. Test-scope dependency only. |
tiko-coroutines |
Kotlin coroutine support: inEventScope runs suspending code in one unit of work across suspension points and dispatcher changes, and it runs suspend @EventHandlers and suspend @KafkaSource bridges, which need it on the classpath. Opt-in; depends on kotlinx-coroutines-core. |
tiko-kafka + tiko-kafka-processor |
Kafka transport via the universal TransportBootstrap SPI — @KafkaSource / @KafkaSink, JSON serializer, per-record commit + seek-back. Opt-in. |
tiko-archetype |
Maven archetype that scaffolds a runnable single-module Tiko project in seconds. |
tiko-bom |
Bill-of-materials for version-aligned dependency management. |
Event abstractions (EventBus, EventCallback, Subscription, @EventHandler, @EventTrigger, Event<T>) live in tiko-api; the in-memory implementation lives in tiko-runtime. Kafka ships as a separate, opt-in module pair (tiko-kafka + tiko-kafka-processor); further transports (RabbitMQ, JMS) are unscheduled — see the roadmap.
Logging
Tiko logs through java.lang.System.Logger — the JDK-standard SPI introduced in
Java 9. There is no tiko-side configuration knob, no SPI to implement, no
adapter module.
Default: routes through java.util.logging. Nothing to configure for “just works.”
Routing to slf4j: add slf4j-jdk-platform-logging + your slf4j backend
(logback, log4j-slf4j2-impl, slf4j-simple, etc.). See
tiko-examples/11_custom_logger for a
runnable example.
Routing to log4j2: add log4j-jpl + the log4j2 core. Same mechanism, different bridge.
Routing to JBoss Logging: JBoss Logging uses JulLogManager rather than a
LoggerFinder — set -Djava.util.logging.manager=org.jboss.logmanager.LogManager.
The single tiko-side knob remains TikoOptions.errorHandler(...) for handler-exception
policy — a different layer than framework logging.
Documentation
| Document | What’s in it |
|---|---|
| docs/getting-started.md | Your first service, step by step: HTTP, database, a transaction per request, an event, a test. |
| docs/cookbooks/ | Recipes for what you plug in: persistence, HTTP, Kafka, Ktor. |
| docs/VISION.md | Design principles, three-layer architecture, event-pipeline trade-offs, and direction. |
| docs/di-and-scopes.md | Full DI reference — scopes, cross-scope proxies, lifecycle hooks, qualifiers, @Produces. |
| docs/configuration.md | @Configuration deep-dive — nested records, layered sources, module-baked defaults. |
| docs/events.md | Event bus, error handling, async executor, lifecycle events, @EventTrigger chains. |
| docs/testing.md | tiko-test JUnit 5 extension — @TikoTest, parameter resolution, RecordingEventBus, scope helpers, boundary notes. |
| docs/jdk-23-setup.md | Annotation processing on JDK 23+ — Maven / Gradle / plain javac. |
| docs/roadmap.md | What ships today and what’s planned per phase. |
| docs/releasing.md | Release engineering reference (maintainers): what is published and how it is wired. |
| docs/qa-playbook.md | Structured QA passes over the framework + examples; issue body template; rules for what to file and what not to. |
| docs/issue-fix-playbook.md | Counterpart to the QA playbook — how to work a filed issue without anchoring on its framing. Four-phase fix workflow + common traps. |
| comparisons/README.md | Side-by-side cold-start benchmarks across 8 DI frameworks. |
Measured cold-start
The comparisons/ directory holds eight self-contained, side-by-side implementations of the same four-singleton, two-module workload — plain Java (no DI), Tiko, Dagger 2, Avaje Inject, HK2, Guice, Spring, and Micronaut (micronaut-inject only). Median of 10 cold JVM invocations, default JVM, default GC, Java 21, on a development laptop. These numbers move on different hardware — re-run locally before drawing conclusions.
| Framework | Wall-clock (ms) | total_ns (ms) |
Style |
|---|---|---|---|
jvm baseline (java -version) |
104 | — | — |
| plain (no DI) | 172 | 36 | floor reference |
| dagger | 186 | 44 | compile-time, lazy |
| tiko | 202 | 61 | compile-time, lazy |
| avaje | 228 | 105 | compile-time, eager |
| hk2 | 307 | 159 | runtime, reflection, lazy |
| guice | 373 | 230 | runtime, reflection, lazy |
| micronaut (inject-only) | 459 | 308 | compile-time, eager + AOP |
| spring | 529 | 368 | runtime, reflection, eager |
The total_ns column sums the four phases the bench measures (create + first_get_a + first_get_b + close) and is the apples-to-apples comparison: it accounts for both eager (Avaje, Spring, Micronaut) and lazy (Tiko, Dagger, Guice, HK2) initialisation strategies. See comparisons/README.md for full per-phase tables, methodology, caveats, and reproduction.
The honest reading: the dominant axis is lazy vs eager init, not “compile-time vs runtime.” Four clusters emerge — lean compile-time-lazy (plain, Dagger, Tiko at 36–61 ms total_ns), compile-time-eager (Avaje at 105 ms), runtime-reflection-lazy (HK2, Guice at 159–230 ms), and eager-with-overhead (Micronaut, Spring at 308–368 ms). Within each laziness class the compile-time framework is cheaper (Tiko < Guice; Avaje < Spring), but Avaje (compile-time + eager) is slower than HK2 and Guice (runtime + lazy) — eagerness costs more than reflection saves at this scale.
Working with AI agents
Benchmarked for AI-friendliness
llm-framework-benchmark: on an external-oracle-graded build task (a Kafka → H2 → merged-notification service), run across three models (Claude Sonnet 4.6 / Fable 5 / Opus 4.8, n=5). tiko — absent from the models’ training data — reaches 86–100% median compliance, on par with Spring on versions the models know, and clears the brand-new Spring Boot 4.0.6 wall that broke Sonnet 4.6 (median 0%). See the benchmark for the full picture, per-build token cost, and caveats.
Agent skills
- New service? Read
.ai-skills/tiko-build/SKILL.md— decision tree,@Producescookbook, anti-pattern redirect table so an agent reaches for the tiko-native primitive. - Library not in the cookbook? Read
.ai-skills/tiko-cookbook-extension/SKILL.md— the procedural skill for adding a new recipe. Load-bearing rule: ask, don’t fabricate.
AI-agent topology server (MCP)
Every Tiko build emits machine-readable topology + config schema to
META-INF/tiko/. The tiko-mcp companion jar exposes them to any
MCP-aware coding agent (Claude Code, Cursor, …):
java -jar tiko-mcp.jar /path/to/your/project
The metadata ships inside the jar so MCP can also introspect Tiko
dependencies you didn’t build yourself. To suppress emission for a
module (closed-source service, sensitive jars), add
-Atiko.topology.bundle=false to the annotation processor args.
See tiko-examples/13_mcp_introspection
for a runnable demo. Projects scaffolded from tiko-archetype ship a
ready-to-use .mcp.json (jbang-resolved) — MCP-aware agents auto-connect
on open with no setup beyond installing jbang.
Roadmap (summary)
- Phase 1 — Alpha completion. ✅ Closed. Core DI, scopes, lifecycle events,
@EventTriggerchains, multi-module aggregation. - Phase 2 — Configuration & distributed events. ✅ Closed.
@Configurationv1 + nested records +Set<X>+ YAML source anchors, Kafka transport,ErrorContexthook, async event executor + shutdown timeout,System.Loggermigration. - Phase 3 — Onboarding & tooling. ✅ Closed (30/30 issues, a week ahead of due date). AI-assistant-aware archetype,
tiko-testJUnit 5 module, machine-readable topology + MCP server (13 tools today), plus the QA pass #1 follow-ups: examples README cleanup, slf4j routing fix,@PreDestroyLIFO contract honoured across@Componentand@Produces, project-widemaven-failsafe-pluginwiring, dotted-prefix@Configurationnow binds naturally-nested YAML. QA discipline codified in qa-playbook.md + issue-fix-playbook.md. - Phase 4 — Runtime hardening. ✅ Closed, shipped in 0.1.0. Typed
RuntimeExceptionsubtypes, checked-exception propagation through@Produces/@PostConstruct, framework-managed JVM shutdown hook, JaCoCo coverage + SonarCloud static analysis. - Phase 5 — Publish to Maven Central. ✅ Closed. On Maven Central since 0.1.0 (2026-06-04) as
io.github.tomas-samek:tiko-*: POM metadata, GPG signing, sources/javadoc jars, CI release deploy. - Phase 6 — MCP enrichment. ✅ Closed, shipped in 0.2.0.
get_generated_artifact,list_lifecycle_hooks,explain_proxy,topology_overview. - Phase 7 — Resiliency layer. ✅ Closed, shipped in 0.3.0. Handler timeouts, retries with backoff, bounded-queue backpressure (
OverflowPolicy), executor pool settings, dead-letter routing. - Phase 8 — Distributed transports. ✅ Closed. The pluggable serializer SPI (
EventSerializer) shipped in 0.4.0; RabbitMQ and JMS adapters are unscheduled. - Phase 9 — Examples & docs polish. ✅ Closed. Profiles demo, strict-mode config demo, advanced-feature examples (
@EventTriggers, scoped suppliers, origin chain,TikoOptions). - Since then. 0.4.0 (Kafka test seam), 0.5.0 (async handlers own their unit of work), 0.6.0 (hardening), 0.7.0 (Kotlin on Gradle and KSP2).
- Planned. 0.8.0 together with Kotlin K2 — coroutines.
Full detail in docs/roadmap.md.
Building from source
git clone https://github.com/tomas-samek/tiko-di.git
cd tiko-di
mvn clean install # build all modules
mvn test # run tests
mvn clean install -DskipTests # build without tests
mvn clean install -pl tiko-api # build specific module
Requires Java 21+ and Maven 3.8+. CI builds on JDK 21, 25, 26 and 27. On JDK 27 the Spotless format check is skipped until palantir-java-format supports it (#465), so run mvn spotless:apply on an earlier JDK before committing.
Philosophy
- Compile-time safety. Wiring errors — unresolved dependencies, circular dependencies, scope violations — are compile-time errors and never survive the build. Runtime failures are reserved for what the compiler cannot see: requesting a component that is not in the graph, or touching an EVENT-scoped dependency outside an open unit of work.
- Simplicity. Minimal concepts, intuitive API.
- Explicitness. No magic, generated code is readable.
- Performance. No reflection in wiring — generated code, fast startup, low memory.
- Modularity. Use only what you need.
- Event-driven. First-class support for decoupled communication.
Contributing
Contributions are welcome. CONTRIBUTING.md covers building from source, the module layout, code style, tests and how a change becomes a pull request.
Bug reports should include Java version, Maven version, and a minimal reproducer. State symptoms and observable facts only — no “probable cause” or “suggested fix” sections, those bias whoever picks the issue up. The full format and rationale are in docs/qa-playbook.md; the counterpart workflow for working a filed issue is docs/issue-fix-playbook.md.
Security vulnerabilities are the exception: report them privately as described in SECURITY.md, not as an issue.
Security
Report vulnerabilities privately through GitHub’s private vulnerability reporting, not in a public issue. SECURITY.md covers supported versions, what to expect, and scope.
Every pull request runs CodeQL code scanning and GitHub Dependency Review, and Dependabot watches the dependencies declared in our poms (shaded transitive modules such as jackson-core are outside its view — see SECURITY.md). Untrusted input is handled conservatively by default:
- YAML configuration is loaded with SnakeYAML’s
SafeConstructor. - The Kafka JSON serializer reads each record into the bridge method’s declared payload type, with Jackson default typing off.
- The framework uses no Java object serialization.
License
MIT — see LICENSE.
Acknowledgments
Built on lessons learned from existing DI frameworks:
- Dagger 2 — compile-time validation approach
- Guice — clean, type-safe API design
- Spring — comprehensive feature set and ecosystem thinking
- Micronaut — cloud-native optimization strategies
Contact
Tomas Samek — GitHub
Project: https://github.com/tomas-samek/tiko-di
Tiko — Compile-time dependency injection for Java 21+, with first-class event handling.