← All projects

Java

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

Maven Central Build Java Maven License Quality Gate Status Coverage

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+? javac no longer runs annotation processing implicitly — the snippet above is already correct (it requires maven-compiler-plugin ≥ 3.13.0). For Gradle, plain javac, 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

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

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, @EventTrigger chains, multi-module aggregation.
  • Phase 2 — Configuration & distributed events. ✅ Closed. @Configuration v1 + nested records + Set<X> + YAML source anchors, Kafka transport, ErrorContext hook, async event executor + shutdown timeout, System.Logger migration.
  • Phase 3 — Onboarding & tooling. ✅ Closed (30/30 issues, a week ahead of due date). AI-assistant-aware archetype, tiko-test JUnit 5 module, machine-readable topology + MCP server (13 tools today), plus the QA pass #1 follow-ups: examples README cleanup, slf4j routing fix, @PreDestroy LIFO contract honoured across @Component and @Produces, project-wide maven-failsafe-plugin wiring, dotted-prefix @Configuration now 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 RuntimeException subtypes, 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

  1. 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.
  2. Simplicity. Minimal concepts, intuitive API.
  3. Explicitness. No magic, generated code is readable.
  4. Performance. No reflection in wiring — generated code, fast startup, low memory.
  5. Modularity. Use only what you need.
  6. 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.

Continue on GitHub →