rjmad1/conductor

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.