Conway's Law Explained: How Team Structure Shapes Your Codebase

/**
 * 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"));
    }
}