Conway's Law — When Shared Databases Break Silently

/**
 * ConwaysLawDemo.java
 *
 * This demo simulates two teams (Payments and Notifications) that are
 * organizationally siloed. Notice how their integration point — the
 * interface between them — ends up overly broad and poorly defined,
 * exactly as Conway's Law predicts when communication is low.
 *
 * Run this to see the symptom: the Notifications team has to handle
 * events it doesn't understand because nobody sat down to define
 * a clean contract.
 */

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.HashMap;

// -----------------------------------------------------------------------
// PAYMENTS TEAM CODE: They publish events when a payment completes.
// Because they had little time to coordinate with Notifications,
// they just shove everything into a generic Map and fire it off.
// -----------------------------------------------------------------------
class PaymentEvent {
    // Generic map = zero shared contract. Classic siloed-team smell.
    private final Map<String, Object> rawEventData;
    private final String eventType;

    public PaymentEvent(String eventType, Map<String, Object> rawEventData) {
        this.eventType = eventType;
        this.rawEventData = rawEventData;
    }

    public String getEventType() { return eventType; }
    public Map<String, Object> getRawEventData() { return rawEventData; }
}

class PaymentsService {
    private final List<PaymentEvent> publishedEvents = new ArrayList<>();

    public void processPayment(String orderId, double amountUsd, String customerEmail) {
        System.out.println("[PaymentsTeam] Processing payment for order: " + orderId);

        // Payment logic would go here...

        // Build a loosely-typed event because there was no design meeting
        Map<String, Object> eventData = new HashMap<>();
        eventData.put("order_id", orderId);
        eventData.put("amount",   amountUsd);  // Is this dollars? Cents? The Notifications team has no idea.
        eventData.put("email",    customerEmail);
        eventData.put("ts",       System.currentTimeMillis()); // What timezone? Who knows.

        PaymentEvent event = new PaymentEvent("PAYMENT_DONE", eventData); // Vague event name — intentional smell
        publishedEvents.add(event);
        System.out.println("[PaymentsTeam] Published event: " + event.getEventType() + " -> " + eventData);
    }

    public List<PaymentEvent> getPublishedEvents() { return publishedEvents; }
}

// -----------------------------------------------------------------------
// NOTIFICATIONS TEAM CODE: They consume events and send emails.
// Because the contract is unclear, they have to add defensive guesswork.
// This is the architectural scar of poor inter-team communication.
// -----------------------------------------------------------------------
class NotificationsService {

    public void handleEvent(PaymentEvent event) {
        System.out.println("\n[NotificationsTeam] Received event: " + event.getEventType());

        Map<String, Object> data = event.getRawEventData();

        // Defensive casting — the Notifications team doesn't trust the contract
        // because there effectively IS no contract. Pure Conway's Law in action.
        String recipientEmail = (String) data.getOrDefault("email", "unknown@example.com");
        Object rawAmount = data.get("amount");

        // Is 'amount' a Double? An Integer? A String? Nobody specified.
        double confirmedAmount = 0.0;
        if (rawAmount instanceof Number) {
            confirmedAmount = ((Number) rawAmount).doubleValue();
        } else {
            System.out.println("[NotificationsTeam] WARNING: could not parse amount. Defaulting to 0.");
        }

        System.out.println("[NotificationsTeam] Sending confirmation email to: " + recipientEmail);
        System.out.println("[NotificationsTeam] Email body: Your payment of $" +
                String.format("%.2f", confirmedAmount) + " was received.");

        // The Notifications team added 'PAYMENT_DONE' as a magic string
        // because nobody agreed on an enum or constant. Fragile coupling.
        if (!event.getEventType().equals("PAYMENT_DONE")) {
            System.out.println("[NotificationsTeam] Unknown event type — ignoring.");
        }
    }
}

// -----------------------------------------------------------------------
// MAIN: Wire both services together to show the gap
// -----------------------------------------------------------------------
public class ConwaysLawDemo {
    public static void main(String[] args) {
        PaymentsService     paymentsService      = new PaymentsService();
        NotificationsService notificationsService = new NotificationsService();

        // A real payment flows through the system
        paymentsService.processPayment("ORD-9921", 149.99, "alex@example.com");

        // The Notifications team consumes whatever the Payments team published
        for (PaymentEvent event : paymentsService.getPublishedEvents()) {
            notificationsService.handleEvent(event);
        }
    }
}

/**
 * InverseConwayDemo.java
 *
 * This demo shows what the Payments + Notifications integration looks like
 * AFTER applying the Inverse Conway Maneuver:
 *
 * Step 1: The two teams held a joint API design session.
 * Step 2: They agreed on a strongly-typed, versioned event contract.
 * Step 3: The architecture now reflects that healthy communication.
 *
 * Compare this to ConwaysLawDemo.java — same business logic, vastly
 * cleaner integration, because the team dynamic changed first.
 */

import java.time.Instant;
import java.util.ArrayList;
import java.util.List;

// -----------------------------------------------------------------------
// SHARED CONTRACT MODULE: Both teams agreed to own this together.
// In a real system this would be a versioned shared library or a
// Protobuf/Avro schema in a schema registry.
// -----------------------------------------------------------------------

/**
 * PaymentCompletedEvent — v1
 * Jointly designed by Payments and Notifications teams on 2024-06-10.
 * Any breaking changes require a version bump and a joint review.
 */
record PaymentCompletedEvent(
    String  orderId,          // Canonical order identifier, always UUID format
    long    amountCents,      // Amount in CENTS to avoid floating-point ambiguity — teams agreed on this explicitly
    String  customerEmail,    // Validated email address of the paying customer
    Instant occurredAt,       // UTC instant of payment confirmation — never local time
    String  eventSchemaVersion // Allows consumers to handle migrations gracefully
) {}

// -----------------------------------------------------------------------
// PAYMENTS TEAM: Clean publisher — no ambiguity in what they emit
// -----------------------------------------------------------------------
class PaymentsServiceV2 {
    private final List<PaymentCompletedEvent> publishedEvents = new ArrayList<>();

    public void processPayment(String orderId, long amountCents, String customerEmail) {
        System.out.println("[PaymentsTeam-v2] Processing payment for order: " + orderId);

        // Payment processing logic...

        // Publish a strongly-typed event — no ambiguity, no magic strings
        PaymentCompletedEvent event = new PaymentCompletedEvent(
            orderId,
            amountCents,
            customerEmail,
            Instant.now(),
            "v1"             // Explicit schema version so consumers can handle future v2 gracefully
        );

        publishedEvents.add(event);
        System.out.println("[PaymentsTeam-v2] Published: " + event);
    }

    public List<PaymentCompletedEvent> getPublishedEvents() { return publishedEvents; }
}

// -----------------------------------------------------------------------
// NOTIFICATIONS TEAM: Clean consumer — no defensive guesswork needed
// -----------------------------------------------------------------------
class NotificationsServiceV2 {

    public void handlePaymentCompleted(PaymentCompletedEvent event) {
        System.out.println("\n[NotificationsTeam-v2] Handling: PaymentCompletedEvent " + event.eventSchemaVersion());

        // No type-casting, no null-checking a Map — the contract does that work
        double amountInDollars = event.amountCents() / 100.0;

        System.out.println("[NotificationsTeam-v2] Sending email to: " + event.customerEmail());
        System.out.println("[NotificationsTeam-v2] Email body: Hi! Your payment of $" +
                String.format("%.2f", amountInDollars) +
                " for order " + event.orderId() + " was confirmed at " + event.occurredAt() + " UTC.");
    }
}

// -----------------------------------------------------------------------
// MAIN: Same business scenario, drastically cleaner integration
// -----------------------------------------------------------------------
public class InverseConwayDemo {
    public static void main(String[] args) {
        PaymentsServiceV2      paymentsService      = new PaymentsServiceV2();
        NotificationsServiceV2 notificationsService = new NotificationsServiceV2();

        // 14999 cents = $149.99 — no floating-point ambiguity, teams agreed on this
        paymentsService.processPayment("ORD-9921", 14999L, "alex@example.com");

        // The Notifications team's handler is typed — can't accidentally pass the wrong event
        for (PaymentCompletedEvent event : paymentsService.getPublishedEvents()) {
            notificationsService.handlePaymentCompleted(event);
        }
    }
}

/**
 * ConwayDiagnosticExample.java
 *
 * A diagnostic scenario: a single growing team (the "Platform Team")
 * owns authentication, billing, and user profiles — three concerns that
 * should belong to three separate teams.
 *
 * The code shows how this produces a tightly coupled, hard-to-test
 * class — not because the engineers were bad, but because the team
 * structure had no natural seams to reflect.
 *
 * Then we show what the SAME logic looks like when split across
 * three small, focused teams with clean interfaces.
 */

// -----------------------------------------------------------------------
// BEFORE: One big team, one big class. Conway's Law as a liability.
// Every concern is tangled because nobody on the team "owns" a boundary.
// -----------------------------------------------------------------------
class MonolithicPlatformService {

    // Authentication concern
    public boolean authenticateUser(String username, String passwordHash) {
        System.out.println("[PlatformTeam] Authenticating: " + username);
        // Imagine 300 lines of session management, token logic, MFA handling...
        return true; // Simplified
    }

    // Billing concern — directly calls authentication internals (the coupling trap)
    public void chargeSubscription(String username, double monthlyFeeDollars) {
        // This method KNOWS about authentication state — wrong layer entirely
        boolean isAuthenticated = authenticateUser(username, "cached-hash");
        if (isAuthenticated) {
            System.out.println("[PlatformTeam] Charging $" + monthlyFeeDollars + " to: " + username);
        }
    }

    // Profile concern — also tangled in here
    public String getUserDisplayName(String username) {
        System.out.println("[PlatformTeam] Fetching profile for: " + username);
        return "Alex Johnson"; // Simplified
    }

    // A change to auth logic risks breaking billing. A change to billing risks
    // breaking profiles. Tests for each concern require standing up ALL the others.
    // This is the architectural scar of an oversized, under-structured team.
}

// -----------------------------------------------------------------------
// AFTER: Three small teams, three focused classes, clean interfaces.
// Each class can be tested, deployed, and changed independently.
// -----------------------------------------------------------------------

// Team 1: Identity Team owns authentication only
interface IdentityService {
    boolean isSessionValid(String sessionToken);
}

class IdentityServiceImpl implements IdentityService {
    @Override
    public boolean isSessionValid(String sessionToken) {
        System.out.println("[IdentityTeam] Validating session token: " + sessionToken.substring(0, 8) + "...");
        return sessionToken.startsWith("valid-"); // Real logic would hit a session store
    }
}

// Team 2: Billing Team owns charging — depends on identity via interface, not implementation
class BillingService {
    private final IdentityService identityService; // Injected — the team boundary becomes a constructor seam

    public BillingService(IdentityService identityService) {
        this.identityService = identityService;
    }

    public void chargeSubscription(String sessionToken, String customerId, double monthlyFeeDollars) {
        // Billing talks to Identity through a clean contract — not by calling internal methods
        if (!identityService.isSessionValid(sessionToken)) {
            System.out.println("[BillingTeam] Rejected charge — invalid session for customer: " + customerId);
            return;
        }
        System.out.println("[BillingTeam] Charging $" + String.format("%.2f", monthlyFeeDollars) +
                " to customer: " + customerId);
    }
}

// Team 3: Profile Team owns user data independently
class ProfileService {
    public String getDisplayName(String customerId) {
        System.out.println("[ProfileTeam] Fetching display name for: " + customerId);
        return "Alex Johnson";
    }
}

// -----------------------------------------------------------------------
// MAIN: Demonstrate both approaches for comparison
// -----------------------------------------------------------------------
public class ConwayDiagnosticExample {
    public static void main(String[] args) {
        System.out.println("=== BEFORE: One team, one tangled class ===");
        MonolithicPlatformService platformService = new MonolithicPlatformService();
        platformService.chargeSubscription("alex", 9.99);
        platformService.getUserDisplayName("alex");

        System.out.println("\n=== AFTER: Three focused teams, clean interfaces ===");
        IdentityService identityService = new IdentityServiceImpl();
        BillingService  billingService  = new BillingService(identityService); // Billing depends on Identity interface
        ProfileService  profileService  = new ProfileService();

        String sessionToken = "valid-abc123def456"; // Would come from login flow
        billingService.chargeSubscription(sessionToken, "CUST-441", 9.99);
        System.out.println("[Main] Display name: " + profileService.getDisplayName("CUST-441"));
    }
}

package io.thecodeforge.conway;

import java.util.*;

/**
 * ConwayDiagnosticTool.java
 *
 * A simple diagnostic tool that scans a codebase for Conway's Law signals.
 * It looks for shared database connections, generic event maps, and
 * cross-team dependency patterns.
 */
public class ConwayDiagnosticTool {

    // Simulate scanning two service modules
    public static List<String> findConwayScars(Module paymentsModule, Module notificationsModule) {
        List<String> scars = new ArrayList<>();

        // Check for shared database
        if (paymentsModule.getDatabaseName().equals(notificationsModule.getDatabaseName())) {
            scars.add("SHARED_DATABASE: Both modules use " + paymentsModule.getDatabaseName());
        }

        // Check for generic event types
        for (Event event : paymentsModule.getPublishedEvents()) {
            if (event.getPayloadType().equals(Map.class)) {
                scars.add("GENERIC_EVENT: Event '" + event.getName() + "' uses Map<String,Object> payload");
            }
        }

        // Check for shared configuration service
        if (paymentsModule.getConfigService() == notificationsModule.getConfigService()) {
            scars.add("SHARED_CONFIG: Both modules read from same configuration source");
        }

        return scars;
    }

    // Helper classes
    static class Module {
        private final String name;
        private final String databaseName;
        private final List<Event> publishedEvents = new ArrayList<>();
        private Object configService;

        public Module(String name, String databaseName) {
            this.name = name;
            this.databaseName = databaseName;
        }

        public String getDatabaseName() { return databaseName; }
        public List<Event> getPublishedEvents() { return publishedEvents; }
        public Object getConfigService() { return configService; }

        public void addEvent(Event event) { publishedEvents.add(event); }
        public void setConfigService(Object configService) { this.configService = configService; }
    }

    static class Event {
        private final String name;
        private final Class<?> payloadType;

        public Event(String name, Class<?> payloadType) {
            this.name = name;
            this.payloadType = payloadType;
        }

        public String getName() { return name; }
        public Class<?> getPayloadType() { return payloadType; }
    }

    public static void main(String[] args) {
        Module payments = new Module("Payments", "payments_db");
        Module notifications = new Module("Notifications", "payments_db"); // Same DB – shared!

        payments.addEvent(new Event("PaymentCompleted", HashMap.class)); // Generic map – scar
        notifications.addEvent(new Event("NotificationSent", String.class));

        Object sharedConfig = new Object();
        payments.setConfigService(sharedConfig);
        notifications.setConfigService(sharedConfig); // Same config – scar

        List<String> scars = findConwayScars(payments, notifications);
        System.out.println("Conway's Law Scars Found: " + scars.size());
        for (String scar : scars) {
            System.out.println("  - " + scar);
        }
        // Output:
        // SHARED_DATABASE: Both modules use payments_db
        // GENERIC_EVENT: Event 'PaymentCompleted' uses Map<String,Object> payload
        // SHARED_CONFIG: Both modules read from same configuration source
    }
}

package io.thecodeforge.conway;

import java.util.*;

/**
 * IntentionalArchitectureDemo.java
 *
 * Demonstrates how to design an intentional architecture that respects
 * Conway's Law by using team topologies and explicit contracts.
 */
public class IntentionalArchitectureDemo {

    // Step 1: Define team boundaries before coding
    static class Team {
        private final String name;
        private final List<String> ownedServices;

        public Team(String name, List<String> ownedServices) {
            this.name = name;
            this.ownedServices = ownedServices;
        }

        public String getName() { return name; }
        public List<String> getOwnedServices() { return ownedServices; }
    }

    // Step 2: Define interfaces between teams as shared contracts
    interface PaymentProcessing {
        record PaymentCompletedEvent(String orderId, long amountCents, String customerEmail) {}
        PaymentCompletedEvent processPayment(String orderId, long amountCents, String customerEmail);
    }

    interface NotificationSending {
        record SendNotificationCommand(String recipientEmail, String subject, String body) {}
        void sendNotification(SendNotificationCommand cmd);
    }

    // Step 3: Implement services within team boundaries
    static class PaymentsService implements PaymentProcessing {
        @Override
        public PaymentCompletedEvent processPayment(String orderId, long amountCents, String customerEmail) {
            System.out.println("[PaymentsService] Charging " + amountCents + " cents for order " + orderId);
            return new PaymentCompletedEvent(orderId, amountCents, customerEmail);
        }
    }

    static class NotificationsService implements NotificationSending {
        @Override
        public void sendNotification(SendNotificationCommand cmd) {
            System.out.println("[NotificationsService] Sending email to " + cmd.recipientEmail());
            System.out.println("[NotificationsService] Subject: " + cmd.subject());
            System.out.println("[NotificationsService] Body: " + cmd.body());
        }
    }

    // Step 4: Compose the system using interfaces, not shared state
    public static void main(String[] args) {
        // Define teams (in real life, these would be separate microservices)
        Team paymentsTeam = new Team("Payments", List.of("PaymentProcessing"));
        Team notificationsTeam = new Team("Notifications", List.of("NotificationSending"));

        System.out.println("=== System Architecture Aligned with Team Boundaries ===");
        System.out.println("Payments team owns: " + paymentsTeam.getOwnedServices());
        System.out.println("Notifications team owns: " + notificationsTeam.getOwnedServices());
        System.out.println();

        // Use the interfaces
        PaymentProcessing payments = new PaymentsService();
        NotificationSending notifications = new NotificationsService();

        var paymentEvent = payments.processPayment("ORD-1138", 1999L, "user@example.com");

        // Notifications team receives typed event explicitly
        var notificationCmd = new NotificationSending.SendNotificationCommand(
            paymentEvent.customerEmail(),
            "Payment Confirmed",
            "Your payment of $" + (paymentEvent.amountCents() / 100.0) + " for order " + paymentEvent.orderId() + " was successful."
        );
        notifications.sendNotification(notificationCmd);

        // No shared database, no generic maps, no coordination needed
        System.out.println();
        System.out.println("Result: Teams deploy independently using shared interfaces.");
    }
}

#!/usr/bin/env python3
# io.thecodeforge
# Detect Conway violations: services that change together but teams don't talk

def conway_cost_matrix(team_graph, service_dependencies):
    """Returns services where coupling exceeds team communication."""
    cost = []
    for service_a, deps in service_dependencies.items():
        for service_b in deps:
            team_a = team_graph.get(service_a)
            team_b = team_graph.get(service_b)
            if team_a and team_b and team_a != team_b:
                # Check if teams have direct communication channel
                if not teams_communicate(team_a, team_b):
                    cost.append((service_a, service_b, 'HIGH'))
    return cost

def teams_communicate(team_a, team_b):
    # Replace: check shared Slack, daily standup, or tech lead sync
    return False  # Assume not for demo

# Real example: inventory and orders owned by different teams, no cross-team chat
print(conway_cost_matrix(
    {'orders': 'team-alpha', 'inventory': 'team-beta', 'payments': 'team-alpha'},
    {'orders': ['inventory'], 'payments': ['orders']}
))
# Output: [('orders', 'inventory', 'HIGH')]

// io.thecodeforge
// BEFORE: three teams, one shared database, tight coupling

// Team A: Customer Service
class CustomerService {
    // Team A needs to update payment status in the shared Orders database
    // because their communication model forces them to couple
    public void activatePremium(int customerId) {
        // calls Table orders set payment_status = 'premium' via direct JDBC
        // This is the old way — mirrors the old team structure
    }
}

// Team B: Payment Service
class PaymentService {
    // Team B also writes to the same Orders table
    public void processRefund(int orderId) {
        // updates orders.payment_status — collision risk
    }
}

// Expected: Both teams now use a dedicated Payments bounded context
// Actual: They still share the same dumb table because they share a DBA team

teams:
  - name: Payments Team
    services: [payment-service, billing-service]
    members: [frontend, backend, db, QA]
  - name: Inventory Team
    services: [inventory-service, warehouse-service]
    members: [frontend, backend, db, QA]
  - name: User Management Team
    services: [user-service, auth-service]
    members: [frontend, backend, db, QA]

class Team:
    def __init__(self, name, services, size):
        self.name = name
        self.services = services  # list of service names
        self.size = size

# Example teams aligned with microservices
teams = [
    Team("Recommendations", ["recommendation-engine", "personalization-api"], 8),
    Team("Payments", ["payment-gateway", "billing-service"], 6),
    Team("Notifications", ["email-service", "push-notifications"], 4)
]

{
  "platform_teams": [
    {
      "name": "Developer Experience",
      "owned_services": ["kubernetes-cluster", "monitoring-stack", "ci-cd-pipeline"],
      "customer_teams": ["payments", "inventory", "user-management"]
    },
    {
      "name": "Data Platform",
      "owned_services": ["data-lake", "streaming-platform", "analytics-db"],
      "customer_teams": ["recommendations", "billing"]
    }
  ]
}