# rjmad1/conductor architecture

> Architecture diagram of the GitHub repository rjmad1/conductor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rjmad1/conductor
- Repository: https://github.com/rjmad1/conductor

## Overview

1. **Repository shape**
This is a Gradle multi-module Java backend platform, not a single application. The runtime code is split into independently deployable services under `platform/`, reusable libraries under `shared/`, and infrastructure/configuration under `environments/`, `observability/`, and `infrastructure/`. The rest of the repository is mostly architecture governance, docs, ADRs, and operational standards.

2. **Core runtime services**
The main services are:
- `platform/tenant` for tenant lifecycle and tenant admin operations
- `platform/identity` for users, memberships, and API keys
- `platform/customer` for the customer domain and CRM-style data
- `platform/integrations` for connector management, credentials, webhooks, and sync
- `platform/workflow` for workflow definitions and execution
- `platform/events` for dead-letter queue and replay operations
- `platform/messaging-core` for stream/messaging primitives

Each service has its own Spring Boot application entrypoint, repository layer, service layer, REST API, and Flyway migrations.

3. **Domain partitioning**
The codebase is organized around clear bounded contexts: tenant, identity, customer, integrations, workflow, and event operations. Those are reinforced by `architecture/DOMAIN_BOUNDARIES.md`, `docs/architecture/*`, and module-specific boundary tests. The architecture is intentionally modular so a diagram should show these as separate business domains rather than one shared monolith.

4. **Tenant and identity boundary**
`platform/tenant` owns tenant records and tenant audit data, and it integrates with Keycloak through `KeycloakAdminService`. `platform/identity` owns user identity, memberships, and API keys, with security tests around authorization and HMAC validation. Shared auth/middleware libraries provide the tenant and security context plumbing used by multiple services.

5. **Customer domain**
`platform/customer` is the richest domain module. It models customers, contacts, identifiers, consents, attributes, preferences, segments, tags, relationships, and timeline events. It exposes controllers for customer, contact, consent, segment, tag, and timeline operations, and persists each sub-entity through dedicated repositories and migrations. Shared customer types contain enums and converters for PII handling and event taxonomy.

6. **Integrations hub**
`platform/integrations` acts as the external-system boundary. It manages connectors, integrations, credentials, mappings, transformations, sync jobs, OAuth connections, and webhook subscriptions. The connector implementations for Razorpay, Shopify, and Zoho live here, along with webhook signature validation and replay protection. This module is where inbound webhooks and outbound connector calls cross the platform boundary.

7. **Workflow execution**
`platform/workflow` owns workflow definitions, executions, histories, step executions, templates, triggers, state transitions, and compensation logic. It also contains a Temporal-based execution layer (`temporal/`) with workflow and worker abstractions, so the orchestration runtime is split between the local application model and the Temporal engine. Shared workflow enums and template definitions support this module.

8. **Event operations and messaging**
`platform/events` is not the primary event bus; it is the operational surface for DLQ inspection and replay auditing. The event transport primitives live in `shared/messaging` and `platform/messaging-core`, which provide NATS connection management, publishers/consumers, health checks, and tenant-aware event publishing. Event schemas in `config/schemas/` define the contracts for customer, identity, integration, tenant, and workflow events.

9. **Shared libraries as architectural seams**
The `shared/` modules carry cross-cutting primitives:
- auth and security: JWT conversion, web security, HMAC validation, authorization engine
- tenant middleware: tenant context, filters, validators, audit logging
- messaging: publisher/consumer abstractions and observability hooks
- contracts: schema validation
- rules/workflow/templates/execution: reusable domain utilities and template payloads

These modules are the main coupling control points; they should be shown as shared libraries feeding multiple services.

10. **Data storage and persistence**
Every service uses its own Flyway-managed relational schema under `src/main/resources/db/migration`, with PostgreSQL implied by the environment configs. The customer service has search indexes, the workflow service keeps execution history, tenant has audit logs, integrations stores credentials and mappings, and identity stores users/memberships/API keys. Qdrant appears in environment configs, suggesting vector/semantic capabilities are planned or supported in the wider platform.

11. **Infrastructure and runtime platform**
The repository includes full environment definitions for local/dev/stage/qa/prod, plus Kubernetes/Helmfile and docker-compose based local composition. The platform stack includes Kong, Keycloak, Dex, PostgreSQL, Redis, NATS, Redpanda, Temporal, Loki, Prometheus, Tempo, Grafana, and Qdrant. Architecturally, this means the services are designed to run in a platformed environment with gateway, identity provider, messaging, workflow engine, cache, observability, and persistence layers.

12. **Security and trust boundaries**
Security is a first-class architectural axis. The repo contains explicit standards for authentication, authorization, secrets, supply chain, data protection, and multi-tenancy, plus service-level security configs and tests. The main trust boundaries are: external caller to gateway, gateway to service APIs, service to Keycloak, service to external connectors, and tenant-scoped data isolation inside each module.

13. **Observability and operations**
Observability is built into the platform through Grafana dashboards, Prometheus, Loki, Tempo, and OpenTelemetry collector configuration. There are runbooks, health checks, incident-management docs, and workflow/event observability documents, indicating the system is designed for operational visibility across services and asynchronous processing.

14. **Governance and architecture documentation**
A large part of the repository is governance: ADRs, standards, scorecards, plans, backlog, and detailed docs for each domain and integration. These documents don’t participate in runtime flow, but they define the intended boundaries, contracts, and platform decisions. For an architecture diagram, they are best treated as the control plane that governs how the runtime platform is built and operated.

Main entry points: [`infrastructure/kubernetes`](https://github.com/rjmad1/conductor/tree/main/infrastructure/kubernetes) (K8s deploy), [`platform/tenant`](https://github.com/rjmad1/conductor/tree/main/platform/tenant) (Tenant), [`platform/identity`](https://github.com/rjmad1/conductor/tree/main/platform/identity) (Identity), [`observability`](https://github.com/rjmad1/conductor/tree/main/observability) (Observability)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_root["Conductor"]
  node_governance_docs["Arch docs<br/>architecture docs"]
  node_governance_guides["Ops docs<br/>governance docs"]
end

subgraph group_runtime["Runtime"]
  node_tenant_service["Tenant"]
  node_identity_service["Identity"]
  node_customer_service["Customer"]
  node_integrations_service["Integrations"]
  node_workflow_service["Workflow"]
  node_events_service["Events ops<br/>ops service"]
  node_messaging_core(("Messaging core<br/>messaging runtime"))
end

subgraph group_shared["Shared libs"]
  node_auth_lib["Auth<br/>shared security"]
  node_security_lib["Security"]
  node_tenant_middleware["Tenant middleware<br/>shared middleware"]
  node_messaging_lib["Messaging"]
  node_contracts_lib["Contracts"]
  node_customer_shared["Customer shared<br/>shared domain"]
  node_workflow_shared["Workflow shared<br/>shared domain"]
end

subgraph group_platforming["Platform"]
  node_platform_env["Environments<br/>platform config"]
  node_schemas["Event schemas<br/>schema catalog"]
  node_infra_k8s["K8s deploy<br/>infra"]
  node_observability[("Observability<br/>platform ops")]
end

node_root -->|"documents"| node_governance_docs
node_root -->|"governs"| node_governance_guides
node_root -->|"contains"| node_tenant_service
node_root -->|"contains"| node_identity_service
node_root -->|"contains"| node_customer_service
node_root -->|"contains"| node_integrations_service
node_root -->|"contains"| node_workflow_service
node_root -->|"contains"| node_events_service
node_root -->|"contains"| node_messaging_core
node_tenant_service -->|"uses"| node_auth_lib
node_identity_service -->|"uses"| node_security_lib
node_tenant_service -->|"uses"| node_tenant_middleware
node_identity_service -->|"uses"| node_tenant_middleware
node_customer_service -->|"uses"| node_customer_shared
node_workflow_service -->|"uses"| node_workflow_shared
node_tenant_service -->|"validates"| node_schemas
node_identity_service -->|"validates"| node_schemas
node_customer_service -->|"publishes"| node_messaging_lib
node_integrations_service -->|"publishes"| node_messaging_lib
node_workflow_service -->|"publishes"| node_messaging_lib
node_events_service -->|"consumes"| node_messaging_lib
node_messaging_lib -->|"builds on"| node_messaging_core
node_platform_env -->|"feeds"| node_infra_k8s
node_observability -->|"watches"| node_tenant_service
node_observability -->|"watches"| node_identity_service
node_observability -->|"watches"| node_customer_service
node_observability -->|"watches"| node_integrations_service
node_observability -->|"watches"| node_workflow_service
node_infra_k8s -->|"deploys"| node_tenant_service
node_infra_k8s -->|"deploys"| node_identity_service
node_infra_k8s -->|"deploys"| node_customer_service
node_infra_k8s -->|"deploys"| node_integrations_service
node_infra_k8s -->|"deploys"| node_workflow_service

click node_governance_docs "https://github.com/rjmad1/conductor/tree/main/architecture"
click node_governance_guides "https://github.com/rjmad1/conductor/tree/main/docs"
click node_tenant_service "https://github.com/rjmad1/conductor/tree/main/platform/tenant"
click node_identity_service "https://github.com/rjmad1/conductor/tree/main/platform/identity"
click node_customer_service "https://github.com/rjmad1/conductor/tree/main/platform/customer"
click node_integrations_service "https://github.com/rjmad1/conductor/tree/main/platform/integrations"
click node_workflow_service "https://github.com/rjmad1/conductor/tree/main/platform/workflow"
click node_events_service "https://github.com/rjmad1/conductor/tree/main/platform/events"
click node_messaging_core "https://github.com/rjmad1/conductor/tree/main/platform/messaging-core"
click node_auth_lib "https://github.com/rjmad1/conductor/tree/main/shared/auth"
click node_security_lib "https://github.com/rjmad1/conductor/tree/main/shared/security"
click node_tenant_middleware "https://github.com/rjmad1/conductor/tree/main/shared/middleware/tenant"
click node_messaging_lib "https://github.com/rjmad1/conductor/tree/main/shared/messaging"
click node_contracts_lib "https://github.com/rjmad1/conductor/tree/main/shared/contracts"
click node_customer_shared "https://github.com/rjmad1/conductor/tree/main/shared/customer"
click node_workflow_shared "https://github.com/rjmad1/conductor/tree/main/shared/workflow"
click node_platform_env "https://github.com/rjmad1/conductor/tree/main/environments"
click node_schemas "https://github.com/rjmad1/conductor/tree/main/config/schemas"
click node_infra_k8s "https://github.com/rjmad1/conductor/tree/main/infrastructure/kubernetes"
click node_observability "https://github.com/rjmad1/conductor/tree/main/observability"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_governance_docs,node_governance_guides toneBlue
class node_tenant_service,node_identity_service,node_customer_service,node_integrations_service,node_workflow_service,node_events_service,node_messaging_core toneAmber
class node_auth_lib,node_security_lib,node_tenant_middleware,node_messaging_lib,node_contracts_lib,node_customer_shared,node_workflow_shared toneMint
class node_platform_env,node_schemas,node_infra_k8s,node_observability toneRose
```

## Components

### Governance

Architecture standards, ADRs, and documentation that define boundaries and operating rules.

- **Conductor**: repo · Gradle multi-module backend platform with services, shared libraries, and platform definitions.
- [Arch docs](https://github.com/rjmad1/conductor/tree/main/architecture): architecture docs · Domain boundaries, architecture plans, and standards that govern the platform. · `architecture`
- [Ops docs](https://github.com/rjmad1/conductor/tree/main/docs): governance docs · ADRs, standards, runbooks, and policy documents. · `docs`

### Runtime

Deployable services and core execution components.

- [Tenant](https://github.com/rjmad1/conductor/tree/main/platform/tenant): service · Tenant lifecycle, admin operations, and Keycloak integration. · `platform/tenant`
- [Identity](https://github.com/rjmad1/conductor/tree/main/platform/identity): service · Users, memberships, API keys, and authorization-facing identity data. · `platform/identity`
- [Customer](https://github.com/rjmad1/conductor/tree/main/platform/customer): service · Customer domain, contacts, consent, segmentation, tags, and timeline. · `platform/customer`
- [Integrations](https://github.com/rjmad1/conductor/tree/main/platform/integrations): service · Connectors, credentials, webhooks, sync jobs, and external-system boundary. · `platform/integrations`
- [Workflow](https://github.com/rjmad1/conductor/tree/main/platform/workflow): service · Workflow definitions, execution, history, templates, triggers, and Temporal orchestration. · `platform/workflow`
- [Events ops](https://github.com/rjmad1/conductor/tree/main/platform/events): ops service · DLQ inspection and replay auditing for operational event handling. · `platform/events`
- [Messaging core](https://github.com/rjmad1/conductor/tree/main/platform/messaging-core): messaging runtime · Stream and messaging primitives used by services and shared messaging layers. · `platform/messaging-core`

### Shared libs

Cross-cutting libraries reused across services.

- [Auth](https://github.com/rjmad1/conductor/tree/main/shared/auth): shared security · JWT conversion and web security configuration. · `shared/auth`
- [Security](https://github.com/rjmad1/conductor/tree/main/shared/security): shared security · Authorization engine and HMAC validation primitives. · `shared/security`
- [Tenant middleware](https://github.com/rjmad1/conductor/tree/main/shared/middleware/tenant): shared middleware · Tenant context, filters, validators, and audit logging. · `shared/middleware/tenant`
- [Messaging](https://github.com/rjmad1/conductor/tree/main/shared/messaging): shared messaging · Event publisher/consumer abstractions, NATS connection management, and observability hooks. · `shared/messaging`
- [Contracts](https://github.com/rjmad1/conductor/tree/main/shared/contracts): shared contracts · Schema validation for event and API contract boundaries. · `shared/contracts`
- [Customer shared](https://github.com/rjmad1/conductor/tree/main/shared/customer): shared domain · Reusable customer enums, converters, event taxonomy, and PII handling. · `shared/customer`
- [Workflow shared](https://github.com/rjmad1/conductor/tree/main/shared/workflow): shared domain · Reusable workflow enums, trigger types, and event types. · `shared/workflow`

### Platform

Environment, infrastructure, and observability layers.

- [Environments](https://github.com/rjmad1/conductor/tree/main/environments): platform config · Local, dev, QA, stage, and prod platform values. · `environments`
- [Event schemas](https://github.com/rjmad1/conductor/tree/main/config/schemas): schema catalog · Versioned event contracts for tenant, identity, customer, integration, and workflow events. · `config/schemas`
- [K8s deploy](https://github.com/rjmad1/conductor/tree/main/infrastructure/kubernetes): infra · Helmfile and Kubernetes deployment composition. · `infrastructure/kubernetes`
- [Observability](https://github.com/rjmad1/conductor/tree/main/observability): platform ops · Grafana, Prometheus, Loki, Tempo, and OpenTelemetry configuration. · `observability`

## Connections

- Conductor → Arch docs: documents · Architecture guidance and domain boundaries.
- Conductor → Ops docs: governs · Standards, ADRs, runbooks, and policy.
- Conductor → Tenant: contains · Deployable tenant service.
- Conductor → Identity: contains · Deployable identity service.
- Conductor → Customer: contains · Deployable customer service.
- Conductor → Integrations: contains · Deployable integrations service.
- Conductor → Workflow: contains · Deployable workflow service.
- Conductor → Events ops: contains · Operational event tooling.
- Conductor → Messaging core: contains · Core messaging runtime primitives.
- Tenant → Auth: uses · Spring security and JWT conversion.
- Identity → Security: uses · Authorization and HMAC validation.
- Tenant → Tenant middleware: uses · Tenant context and audit plumbing.
- Identity → Tenant middleware: uses · Tenant-scoped request handling.
- Customer → Customer shared: uses · Shared customer enums and converters.
- Workflow → Workflow shared: uses · Shared workflow types and events.
- Tenant → Event schemas: validates · Event and contract schemas.
- Identity → Event schemas: validates · Identity event schemas.
- Customer → Messaging: publishes · Domain events and async notifications.
- Integrations → Messaging: publishes · Webhook and integration events.
- Workflow → Messaging: publishes · Workflow execution events.
- Events ops → Messaging: consumes · DLQ and replay workflows operate on event streams.
- Messaging → Messaging core: builds on · Shared messaging abstractions depend on core stream management.
- Environments → K8s deploy: feeds · Environment-specific runtime values.
- Observability → Tenant: watches · Service metrics, logs, and traces.
- Observability → Identity: watches · Service metrics, logs, and traces.
- Observability → Customer: watches · Service metrics, logs, and traces.
- Observability → Integrations: watches · Service metrics, logs, and traces.
- Observability → Workflow: watches · Service metrics, logs, and traces.
- K8s deploy → Tenant: deploys · Kubernetes deployment target.
- K8s deploy → Identity: deploys · Kubernetes deployment target.
- K8s deploy → Customer: deploys · Kubernetes deployment target.
- K8s deploy → Integrations: deploys · Kubernetes deployment target.
- K8s deploy → Workflow: deploys · Kubernetes deployment target.