Module Design

TramAI 0.6.0 classifies 60 Gradle projects across 10 layers. The authoritative inventory is config/quality/module-catalog.yml, verified against settings.gradle.kts on every build — so this page does not maintain a second copy of the module list. It explains how to choose, and why the split looks the way it does.

For the layer model, the boundary rules, and how the architecture gate enforces them, see Module Architecture.

Compatibility Classes

Every module declares a maturity and an API stability class. What matters to you is the second one:

Class	Meaning for your build
Stable	Safe to build against. The public signature dump is frozen for the release; any change is a release-level decision. Only `tramai-core` and `tramai-bom` are stable in 0.6.0.
Preview	Usable and supported. The shape may still change, and a change ships with an exact migration entry describing what you must do.
Internal	Implementation or support surface. Not covered by the compatibility gate. Some internal modules are published (`tramai-testing`), some are not (`tramai-server`, `tramai-mcp`, `tramai-dashboard`, `tramai-memory-store`).
Excluded	Not part of the API surface at all: the `examples:*` projects.

The full mapping and the mechanism behind it are in API and Binary Compatibility.

Current Module Shape

Layer	Modules	What you get
`core-contracts`	`tramai-core`, `tramai-bom`	Annotations, request models, provider registry, exceptions, version alignment
`runtime-execution`	`tramai-engine`, `tramai-structured`, `tramai-standalone`, `tramai-orchestration`	Proxy dispatch and execution, structured output, the framework-free runtime, workflows
`governance-security`	`tramai-security`, `tramai-sovereign`	Policy, approval, audit, evidence, and the sovereign runtime profile
`persistence`	`tramai-persistence-file`, `tramai-persistence-jdbc`	Durable stores for sovereign state
`provider-adapters`	the seven provider modules	Vendor transport behind the provider SPI
`framework-integrations`	18 `tramai-spring*` modules	Spring core, the unified starter, provider starters, secrets
`operations-observability`	`tramai-observability`, `tramai-platform`, `tramai-server`, `tramai-mcp`, `tramai-dashboard`*	Telemetry and the operational surfaces
`higher-capabilities`	`tramai-memory`, `tramai-memory-store`, `tramai-rag`, `tramai-embedding`, `tramai-scheduler`, `tramai-vectorstore-`	Memory, retrieval, embeddings, scheduling
`applications-examples`	9 `examples:*` projects	Executable reference applications, excluded from the release
`testing-support`	`tramai-testing`, `tramai-spring-consumer-boundary`, `tramai-spring-consumer-selective`	Mock providers, TCKs, consumer boundary tests

* internal and not published in 0.6.0 — there is no coordinate to depend on.

Dependency Direction

The layer order is a conceptual orientation, not a strictly enforced hierarchy. Exact policy lives in each module's dependencyPolicy and in config/quality/module-boundaries.yml.

core-contracts
  └─ runtime-execution
       ├─ governance-security
       ├─ persistence
       └─ provider-adapters
            └─ framework-integrations
                 └─ operations-observability / higher-capabilities
                      └─ applications-examples

testing-support → supports contracts without entering the runtime dependency flow

Three corrections matter here:

tramai-openai is not the umbrella for Azure OpenAI, DeepSeek, and Bedrock at the packaging level. Those are dedicated modules, each with its own adapter.
tramai-security, tramai-sovereign, and the sovereign persistence modules are implemented modules in preview, not "planned".
The operational modules compose the core runtime — they never fork it. A green field read is: tramai-core → tramai-engine → your entry point → one provider, then add optional layers only as the need appears.

The v0.5.0-era dependency graph document in the repository is a historical snapshot; the catalog plus the boundaries file are the current policy, and ./gradlew verify060Architecture verifies the current resolved edges.

Design Rules

tramai-core remains the shared contract layer and stays as close to zero-dependency as practical.
Execution semantics belong in tramai-engine and tramai-orchestration, not in provider modules.
Structured-output mechanics belong in tramai-structured.
Providers stay thin and provider-specific; they must not implement retry, fallback, or circuit-breaker logic.
Transport surfaces such as HTTP and MCP layer on top of workflow/runtime modules instead of redefining execution semantics.
tramai-observability stays optional and off the core happy path.
Framework adapters stay thin and depend inward.
Sovereign/security concerns remain explicit modules rather than hidden flags inside the core runtime.

Reading Guidance

If you are trying to understand the project quickly:

Read tramai-core, tramai-engine, and tramai-structured as the base.
Pick your entry point: tramai-standalone for plain JVM, or tramai-spring-boot-starter for Spring Boot.
Pick a provider module.
Add tramai-testing in tests, tramai-observability for telemetry.
Add orchestration and runtime modules only when you need workflow execution outside a single typed call.
Treat sovereign/security modules as current capabilities in preview, not as roadmap placeholders.

Module Architecture — layers, catalog fields, boundary rules, enrolment
Architecture Overview — runtime execution flow
Modules Catalog — the consumer-facing module inventory
Spring Boot Integration — the unified starter and profiles