How Orazaka is built: a Ports & Adapters (hexagonal) engine, every module in its ring. The map and the messaging topology below are drawn from the same generated model as the tables that follow — select a module to see what it depends on.
Architecture Reference
🤖 Generated from code by
scripts/generate-docs.mjs— do not hand-edit. Runorazaka docs buildto refresh.
Ports & Adapters: dependencies point toward the core. Each module has one role — one ring of the hexagon, outermost first — read from the code by the rule beside it.
| Role | Rule | Modules |
|---|---|---|
| Clients | a UI repository of the workspace manifest (layer app, kind npm) | orazaka-cli, orazaka-mobile-client, orazaka-web-admin, orazaka-web-client |
| Services & workers | a module with a main (SpringApplication.run), or a native worker | orazaka-automation-service, orazaka-conversation-service, orazaka-edge, orazaka-job-service, orazaka-knowledge-service, orazaka-studio-service, orazaka-worker-media, krizaka-billing-service, krizaka-notifications-service, krizaka-users-service |
| Adapters | an imported module that is none of the below: persistence, typed HTTP clients, asset store, bridge | orazaka-assets, orazaka-persistence-app, orazaka-persistence-bridge, orazaka-studio-client, krizaka-billing-client, krizaka-users-client, krizaka-users-persistence |
| Application | the orchestration, pipeline and capability libraries around the core (AGENTS.md §2: business, interceptors, tools) | orazaka-business, orazaka-interceptors, orazaka-tools |
| Domain core | a *-core module — the centre of its hexagon, depending on no outer layer | orazaka-core, krizaka-users-core |
| Contracts | a Tier-1 *-api module — pure interfaces and records | orazaka-jobs-api, orazaka-persistence-app-api, orazaka-studio-api, krizaka-billing-api, krizaka-notifications-api, krizaka-users-api |
| Krizaka platform kit | a module of krizaka-platform-kit — the cross-cutting code with one author (ADR-073), starters included | krizaka-messaging, krizaka-observability, krizaka-security, krizaka-spring-boot-starter-observability, krizaka-spring-boot-starter-rabbitmq, krizaka-spring-boot-starter-security, krizaka-spring-boot-starter-web, krizaka-web |
Modules
| Module | Role | Repository | Version | Inbound ports | Outbound ports |
|---|---|---|---|---|---|
orazaka-cli | client | orazaka-cli | — | — | — |
orazaka-mobile-client | client | orazaka-mobile-client | — | — | — |
orazaka-web-admin | client | orazaka-web-admin | — | — | — |
orazaka-web-client | client | orazaka-web-client | — | — | — |
orazaka-automation-service | service | orazaka-automation-service | 1.0.0-SNAPSHOT | — | — |
orazaka-conversation-service | service | orazaka-conversation-service | 1.0.0-SNAPSHOT | — | — |
orazaka-edge | service | orazaka-edge | 1.0.0-SNAPSHOT | — | — |
orazaka-job-service | service | orazaka-job-service | 1.0.0-SNAPSHOT | — | — |
orazaka-knowledge-service | service | orazaka-knowledge-service | 1.0.0-SNAPSHOT | — | — |
orazaka-studio-service | service | orazaka-studio | 1.0.0-SNAPSHOT | — | — |
orazaka-worker-media | service | orazaka-worker-media | — | — | — |
krizaka-billing-service | service | krizaka-billing | 0.2.0 | — | — |
krizaka-notifications-service | service | krizaka-notifications | 0.2.0 | — | — |
krizaka-users-service | service | krizaka-users | 0.2.0 | — | — |
orazaka-assets | adapter | orazaka-ai-engine | 1.0.0-SNAPSHOT | — | — |
orazaka-persistence-app | adapter | orazaka-ai-engine | 1.0.0-SNAPSHOT | — | — |
orazaka-persistence-bridge | adapter | orazaka-ai-engine | 1.0.0-SNAPSHOT | — | — |
orazaka-studio-client | adapter | orazaka-studio | 1.0.0-SNAPSHOT | — | — |
krizaka-billing-client | adapter | krizaka-billing | 0.2.0 | — | — |
krizaka-users-client | adapter | krizaka-users | 0.2.0 | — | — |
krizaka-users-persistence | adapter | krizaka-users | 0.2.0 | — | — |
orazaka-business | application | orazaka-ai-engine | 1.0.0-SNAPSHOT | — | — |
orazaka-interceptors | application | orazaka-ai-engine | 1.0.0-SNAPSHOT | — | — |
orazaka-tools | application | orazaka-ai-engine | 1.0.0-SNAPSHOT | — | — |
orazaka-core | domain | orazaka-ai-engine | 1.0.0-SNAPSHOT | AiClient, CatalogModelService, ChatSessionService, JobService, McpService | AudioGeneratorClient, CapabilityProvider, ChatGeneratorClient, ChatMemoryStore, ImageGeneratorClient, InfrastructureStatusProvider, KnowledgeService, McpOrchestrator, ModelCatalogProvider, ModelEndpointResolver, PipelineConfigProvider, PlatformMcpServerProvider, PlatformToolConfigProvider, SemanticClassifierPort, TestShaperPort, ToolRegistry, UserCredentialsProvider, UserMcpServerProvider, ValidationPipelineRepository |
krizaka-users-core | domain | krizaka-users | 0.2.0 | ApiKeyService, IdentityReconciliationService, IdentityService, PasswordRecoveryService, RateLimitProvider, TokenService, UserProfileProvider | ApiKeyRepositoryPort, AuthorityRepositoryPort, CryptographyPort, OAuth2ProviderVerifier, PasswordEventPublisher, PasswordResetTokenRepositoryPort, UserCredentialRepositoryPort, UserEventPublisher, UserInterceptionRepositoryPort, UserProfileRepositoryPort, UserRepositoryPort, VerificationTokenRepositoryPort |
orazaka-jobs-api | contract | orazaka-contracts | 1.0.0-SNAPSHOT | — | — |
orazaka-persistence-app-api | contract | orazaka-contracts | 1.0.0-SNAPSHOT | CapabilityManager, CatalogModelManager, ChatMemoryPersistenceProvider, ChatSessionPersistenceProvider, JobPersistenceProvider, OutboxStore, PipelineConfigManager, PlatformMcpServerPersistenceProvider, PlatformToolConfigPersistenceProvider, RuntimeConfigProvider, SpeechVoiceManager, UserMcpServerPersistenceProvider, ValidationPipelineManager | — |
orazaka-studio-api | contract | orazaka-studio | 1.0.0-SNAPSHOT | — | — |
krizaka-billing-api | contract | krizaka-billing | 0.2.0 | — | — |
krizaka-notifications-api | contract | krizaka-notifications | 0.2.0 | — | — |
krizaka-users-api | contract | krizaka-users | 0.2.0 | — | — |
krizaka-messaging | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-observability | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-security | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-spring-boot-starter-observability | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-spring-boot-starter-rabbitmq | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-spring-boot-starter-security | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-spring-boot-starter-web | platform | krizaka-platform-kit | 0.2.0 | — | — |
krizaka-web | platform | krizaka-platform-kit | 0.2.0 | — | — |
Dependencies
Build dependencies between the modules above (test scope excluded): who packages whom.
| Module | Depends on |
|---|---|
orazaka-automation-service | krizaka-billing-client, krizaka-messaging |
orazaka-conversation-service | krizaka-billing-client, krizaka-spring-boot-starter-observability, krizaka-spring-boot-starter-rabbitmq, krizaka-spring-boot-starter-security, krizaka-spring-boot-starter-web, krizaka-users-api, krizaka-users-client, orazaka-assets, orazaka-business, orazaka-core, orazaka-interceptors, orazaka-jobs-api, orazaka-persistence-app, orazaka-persistence-bridge, orazaka-studio-client, orazaka-tools |
orazaka-edge | krizaka-security |
orazaka-job-service | krizaka-billing-client, krizaka-messaging, krizaka-security, krizaka-users-api, krizaka-users-client, orazaka-assets, orazaka-business, orazaka-core, orazaka-interceptors, orazaka-jobs-api, orazaka-persistence-app, orazaka-persistence-bridge, orazaka-tools |
orazaka-knowledge-service | krizaka-messaging, krizaka-security |
orazaka-studio-service | krizaka-billing-api, krizaka-billing-client, krizaka-messaging, krizaka-security, orazaka-jobs-api, orazaka-studio-api |
krizaka-billing-service | krizaka-billing-api, krizaka-messaging, krizaka-security |
krizaka-notifications-service | krizaka-messaging, krizaka-notifications-api |
krizaka-users-service | krizaka-security, krizaka-users-core |
orazaka-persistence-app | krizaka-messaging, orazaka-jobs-api, orazaka-persistence-app-api |
orazaka-persistence-bridge | orazaka-core, orazaka-persistence-app-api |
orazaka-studio-client | krizaka-security, orazaka-studio-api |
krizaka-billing-client | krizaka-billing-api, krizaka-security |
krizaka-users-client | krizaka-security, krizaka-users-api |
krizaka-users-persistence | krizaka-messaging |
orazaka-business | orazaka-core, orazaka-studio-api, orazaka-studio-client |
orazaka-interceptors | krizaka-billing-api, orazaka-core, orazaka-jobs-api |
orazaka-tools | orazaka-core |
orazaka-core | krizaka-security, orazaka-persistence-app-api |
krizaka-users-core | krizaka-users-api, krizaka-users-persistence |
orazaka-persistence-app-api | orazaka-jobs-api |
orazaka-studio-api | orazaka-jobs-api |
krizaka-spring-boot-starter-observability | krizaka-observability |
krizaka-spring-boot-starter-rabbitmq | krizaka-messaging |
krizaka-spring-boot-starter-security | krizaka-security |
krizaka-spring-boot-starter-web | krizaka-web |
Runtime flows
Who calls whom while the platform runs: HTTP (UI defaults, the edge route table, the typed clients a service packages) and AMQP (a published routing key that reaches a queue).
| From | To | Kind | Via |
|---|---|---|---|
krizaka-users-service | krizaka-notifications-service | amqp | krizaka.notifications.password-events (evt.password.reset) |
krizaka-users-service | krizaka-notifications-service | amqp | krizaka.notifications.user-events (evt.user.registered) |
orazaka-automation-service | orazaka-studio-service | amqp | orazaka.events.studio.connector (evt.automation.telemetry) |
orazaka-conversation-service | orazaka-automation-service | amqp | orazaka.jobs.automation (job.automation.approved) |
orazaka-conversation-service | orazaka-job-service | amqp | orazaka.jobs.batch (job.media.generate) |
orazaka-conversation-service | orazaka-job-service | amqp | orazaka.jobs.interactive (job.text.*, job.media.analyze) |
orazaka-conversation-service | orazaka-studio-service | amqp | orazaka.events.studio.capability (evt.capability.changed) |
orazaka-conversation-service | orazaka-worker-media | amqp | orazaka.jobs.video (job.video.*, job.compose.*) |
orazaka-job-service | krizaka-billing-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | krizaka-notifications-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | krizaka-users-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | orazaka-automation-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | orazaka-conversation-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | orazaka-conversation-service | amqp | orazaka.events.job-relay (job.{…}.done) |
orazaka-job-service | orazaka-knowledge-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | orazaka-studio-service | amqp | krizaka.billing.settlements (job.{…}.done) |
orazaka-job-service | orazaka-studio-service | amqp | orazaka.events.studio (job.{…}.done) |
orazaka-job-service | orazaka-studio-service | amqp | orazaka.events.studio.capability (evt.capability.changed) |
orazaka-studio-service | orazaka-automation-service | amqp | orazaka.jobs.automation (job.automation.approved) |
orazaka-studio-service | orazaka-job-service | amqp | orazaka.jobs.batch (job.media.generate) |
orazaka-studio-service | orazaka-job-service | amqp | orazaka.jobs.interactive (job.text.*, job.media.analyze) |
orazaka-studio-service | orazaka-worker-media | amqp | orazaka.jobs.video (job.video.*, job.compose.*) |
orazaka-automation-service | krizaka-billing-service | http | krizaka-billing-client |
orazaka-cli | orazaka-conversation-service | http | localhost:8080 |
orazaka-cli | orazaka-edge | http | localhost:8088 |
orazaka-conversation-service | krizaka-billing-service | http | krizaka-billing-client |
orazaka-conversation-service | krizaka-users-service | http | krizaka-users-client |
orazaka-conversation-service | orazaka-studio-service | http | orazaka-studio-client |
orazaka-edge | krizaka-billing-service | http | route /api/v1/billing |
orazaka-edge | krizaka-users-service | http | route /api/v1/api-keys |
orazaka-edge | krizaka-users-service | http | route /api/v1/auth |
orazaka-edge | krizaka-users-service | http | route /api/v1/credentials |
orazaka-edge | krizaka-users-service | http | route /api/v1/interceptions |
orazaka-edge | krizaka-users-service | http | route /api/v1/profile |
orazaka-edge | orazaka-conversation-service | http | route / |
orazaka-edge | orazaka-studio-service | http | route /api/v1/studios |
orazaka-job-service | krizaka-billing-service | http | krizaka-billing-client |
orazaka-job-service | krizaka-users-service | http | krizaka-users-client |
orazaka-job-service | orazaka-studio-service | http | orazaka-studio-client |
orazaka-mobile-client | orazaka-edge | http | localhost:8088 |
orazaka-studio-service | krizaka-billing-service | http | krizaka-billing-client |
orazaka-web-admin | orazaka-edge | http | localhost:8088 |
orazaka-web-client | orazaka-conversation-service | http | localhost:8080 |
orazaka-web-client | orazaka-edge | http | localhost:8088 |
Interceptor pipeline
Phase 1 — core chain (fixed in code, non-bypassable, ADR-051)
| # | Interceptor | Concern |
|---|---|---|
| 1 | SafetyInterceptor | validation |
| 2 | ScopeGuardInterceptor | governance |
| 3 | UserContextResolver | context |
| 4 | SystemContextInjector | context |
| 5 | RagInterceptor | enrichment |
Phase 2 — configured chain (order and switch in pipeline_interceptor_config)
| Order | Interceptor | Enabled | Implemented |
|---|---|---|---|
| 4 | EntitlementInterceptor | ✅ | ✅ |
| 5 | McpInterceptor | ✅ | ✅ |
| 6 | BrandContextInterceptor | ✅ | ✅ |
| 7 | MemoryInterceptor | ✅ | ✅ |
| 8 | RefinerInterceptor | ✅ | ✅ |
| 9 | RouterInterceptor | ✅ | ✅ |
| 9 | ToolInterceptor | ✅ | ✅ |
| 10 | MediaInterceptor | ✅ | ⚠ no class |
| 11 | UserContextInterceptor | ✅ | ✅ |
Messaging topology (AGENTS.md §6)
Exchanges
orazaka.jobs(topic)orazaka.events(topic)orazaka.dlx(direct)
Retry, then dead letter — a listener on the kit's container (krizaka-messaging, krizaka.messaging.retry) runs up to 5 times, waiting 500 ms ×2 up to 10 s, then the message goes to <queue>.dlq.
Queues
| Queue | Exchange | Binding | DLQ | Declared by | Consumed by |
|---|---|---|---|---|---|
krizaka.billing.settlements | orazaka.events | job.*.done, job.*.error | krizaka.billing.settlements.dlq | krizaka-billing-service | krizaka-billing-service, krizaka-messaging |
krizaka.billing.unmetered | orazaka.events | evt.turn.unmetered | krizaka.billing.unmetered.dlq | krizaka-billing-service | krizaka-billing-service |
krizaka.notifications.password-events | orazaka.events | evt.password.* | krizaka.notifications.password-events.dlq | krizaka-notifications-service | krizaka-notifications-service |
krizaka.notifications.requests | orazaka.events | evt.notification.requested | krizaka.notifications.requests.dlq | krizaka-notifications-service | krizaka-notifications-service |
krizaka.notifications.user-events | orazaka.events | evt.user.* | krizaka.notifications.user-events.dlq | krizaka-notifications-service | krizaka-notifications-service |
orazaka.events.job-relay | orazaka.events | job.# | orazaka.events.job-relay.dlq | orazaka-persistence-app | orazaka-conversation-service |
orazaka.events.studio | orazaka.events | job.*.done, job.*.error | orazaka.events.studio.dlq | orazaka-studio-service | orazaka-studio-service |
orazaka.events.studio.capability | orazaka.events | evt.capability.* | orazaka.events.studio.capability.dlq | orazaka-studio-service | orazaka-studio-service |
orazaka.events.studio.connector | orazaka.events | evt.automation.telemetry | orazaka.events.studio.connector.dlq | orazaka-studio-service | orazaka-studio-service |
orazaka.events.studio.subscription | orazaka.events | evt.subscription.* | orazaka.events.studio.subscription.dlq | orazaka-studio-service | orazaka-studio-service |
orazaka.jobs.automation | orazaka.jobs | job.automation.* | orazaka.jobs.automation.dlq | orazaka-automation-service | orazaka-automation-service |
orazaka.jobs.batch | orazaka.jobs | job.media.generate | orazaka.jobs.batch.dlq | orazaka-persistence-app | orazaka-job-service |
orazaka.jobs.interactive | orazaka.jobs | job.text.*, job.media.analyze | orazaka.jobs.interactive.dlq | orazaka-persistence-app | orazaka-job-service |
orazaka.jobs.rag | orazaka.jobs | job.rag.* | orazaka.jobs.rag.dlq | orazaka-knowledge-service | orazaka-knowledge-service |
orazaka.jobs.video | orazaka.jobs | job.video.*, job.compose.* | orazaka.jobs.video.dlq | orazaka-persistence-app | orazaka-worker-media (own retry) |
Producers
| Module | Exchange | Routing key |
|---|---|---|
krizaka-billing-service | orazaka.events | (dynamic) |
krizaka-users-core | orazaka.events | evt.password.reset |
krizaka-users-core | orazaka.events | evt.user.registered |
orazaka-automation-service | orazaka.jobs | (dynamic) |
orazaka-automation-service | orazaka.events | evt.automation.telemetry |
orazaka-conversation-service | orazaka.jobs | (capability route) |
orazaka-conversation-service | orazaka.events | (dynamic) |
orazaka-conversation-service | orazaka.events | evt.agent.presence |
orazaka-conversation-service | orazaka.events | evt.capability.changed |
orazaka-conversation-service | orazaka.jobs | job.automation.approved |
orazaka-job-service | orazaka.events | (dynamic) |
orazaka-job-service | orazaka.events | evt.capability.changed |
orazaka-job-service | orazaka.events | job.{…}.done |
orazaka-job-service | orazaka.events | job.{…}.error |
orazaka-studio-service | orazaka.jobs | (capability route) |
orazaka-studio-service | orazaka.events | evt.studio.run.failed |
orazaka-studio-service | orazaka.events | evt.studio.run.started |
orazaka-studio-service | orazaka.events | evt.studio.run.succeeded |
orazaka-studio-service | orazaka.jobs | job.automation.approved |
Capability routes (orazaka_capabilities: where a job of each capability is published)
| Capability | Handler | Routing key |
|---|---|---|
orazaka.studio.media.compose | media.compose | job.compose.assemble |
orazaka.core.media.vision | image.analyze | job.media.analyze |
orazaka.core.media.audio.analysis | audio.analyze | job.media.generate |
orazaka.core.media.image | image.generate | job.media.generate |
orazaka.core.media.video.analysis | video.analyze | job.media.generate |
orazaka.core.chat.completion | text.generate | job.text.process |
orazaka.core.media.speech | speech.synthesize | job.text.process |
orazaka.core.media.video | video.generate | job.video.generate |