DEV Community: Ruben Rangel

What I Learned from Domain Modeling in a Team

Ruben Rangel — Sun, 02 Jun 2024 23:10:40 +0000

Introduction

In my division at Guild, we've started a working group to develop and iterate on a new domain model, aiming to create the ideal topography for the next evolution of our space. The process incorporates zero-start thinking (starting from a blank slate) and considers inputs such as what product features we want to support now and in the future, how to design the domain to easily adapt to new requirements, and how to align the domain to maximize ownership and the flow of work. The spirit of the exercise is rooted in Domain-Driven Design. Using this model, we aim to provide a North Star of sorts to guide design decisions, trade-off discussions, investments, and what directionally correct choices look like.

The group consists of leaders in the technology and product organizations. I'm excited to work with them on this large project and learn from them. I work closely alongside the Software Architect in the group, helping to author the model using feedback from stakeholders and our own knowledge and understanding of the domain.

Communicating with Stakeholders

With a task as complex as designing a domain, communicating with others is crucial. Failure to do so dashes any chances of achieving the project's goals. Nobody truly has the "whole picture" in their heads. Getting other people's perspectives on the domain, listening to their concerns with the model, teasing out information by asking thought-provoking questions, and gathering requirements are just some examples of the process of effective communication. If you can do this with people in various roles (especially in Product and Engineering), you increase your chances of success. Just be sure not to get stuck in analysis paralysis.

In our group, the revisions of the model have happened in various ways. We've done some small iterations in synchronous meetings, I've facilitated one-on-one sessions with stakeholders, and we've also collaborated asynchronously using Miro. Getting feedback early and often helps reduce the chances of creating something that doesn't fit our needs.

Making Brave Decisions

Essentially, all models are wrong, but some are useful.

- George E. P. Box

As my career has progressed, I've taken on more responsibility and decision-making, which can be uncomfortable. I often wonder, "Is this decision the right one?" During this domain modeling exercise, I create concepts based on my understanding of different contexts, and that question frequently arises.

In a conceptual model like the one we're building, where the time horizon is at least a year out if the model had perfect clarity, the answer may not be known for a long time. Even then, by the time we get there, the definition of correct may be entirely different from what it was before. My VP of Engineering gave me great advice though: "Make a decision and get feedback on it. If it doesn't work, we've eliminated one incorrect option." This made me realize that though I may be drawing some boxes in the model, the overall decision and direction belong to the team, not a single person. I shouldn't be hung up on being right. The point of the model is to help inform and provide context, not to be 100% accurate in all regards. Modeling is cheap, and we should be comfortable throwing away ideas now, when it's easy.

Balancing Ideal vs. Current State

As I stated earlier, the modeling exercise uses some of the current functionality we want to support as an input. Another is future functionality we want to support. It's hard to keep the former from influencing your thinking too much. These are things we've built; it's easy to reason about and understand them since they're real and these concepts already exist. Striking the balance and allowing ourselves to question everything is key to envisioning what could be. Yes, sometimes we keep some domain objects from the current state around because they make sense, but other times, we take the scary step of not including those objects in the new world. Envisioning what could be is the goal, and we should use the past to inform the future, but not couple them.

The Ever-Evolving Model

I've never been part of a project where the final delivery turns out exactly like the initial design. The completeness of the model is not 100%, and the time horizon for any kind of implementation is long-term. Revisiting and evolving the model is necessary to keep it relevant and useful. Contexts will shift over time: new features will be necessary to accomplish the company's goals, domains may become deprecated, and we'll keep gaining understanding of our product's sector.

After the initial model is built, one of the follow-on efforts will be to see how we can get from point A to point B and do that in an iterative fashion. Think of things like product release milestones or an architecture modification. We should use these checkpoints to pause and revisit the model. We will have certainly learned more along the way, and building that understanding back into the model will adjust it to be more "correct" than it was. I've seen many diagrams and models that are made once and never updated again, reducing their usefulness and potentially leading to suboptimal decision-making.

Continuous Communication and Adaptation

Even though the modeling is done by a working group, the outcomes affect a larger set of people and the systems they work on. Shopping around the model, setting up its context, and getting people's thoughts on it are important for gaining buy-in on the effort. In an organizational culture that emphasizes ownership, "throwing things over the wall" is a mistake. I personally am still learning how to do this well. Who do I share information with, and at what time? How do I make sure their input is heard but also not distract them from their current priorities?

I don't think there's a one-size-fits-all answer for this. Generally speaking though, I think it's hard to over-communicate, especially in things that are high in scope. There's probably nuance here with the particular people you work with and organizational structures. That pushes more importance on staying aware of how communication flows within the organization and doing what you can to ensure everyone is on the same page.

Conclusion

In conclusion, the domain modeling project at Guild has underscored the importance of clear communication, decisive action, and the ability to adapt to changing conditions. This work has taught me to balance current realities with our future vision, continuously refine our models, and engage our entire team in the evolution process.

Have you been part of large-scale domain exercises like this? What strategies did you employ to achieve your goals?

Crafting a Unified GraphQL Experience with AWS AppSync Merged APIs

Ruben Rangel — Tue, 07 May 2024 04:24:08 +0000

Lately, Ive been exploring AWS AppSync Merged APIs to better understand the complexities and tradeoffs involved in creating a unified GraphQL API experience that can be supported by various subdomain teams.

Motivation

GraphQL is all about the graph formed by the Types in the schema. Forming relationships between Types allows clients to connect these different entities. This enables enhanced client experiences and can result in more efficient server interactions.

However, as the number of Types (vertices in the graph) increases, so does the maintenance of the API. Maybe the API holds all the functionality for a scaling business, and so the capabilities of the API and the number of engineers supporting the API grow. If the GraphQL API is implemented in AppSync, Merged APIs can help lower the cognitive load of maintenance by allowing subsections of the API to be powered by Source APIs (and possibly a single domain team).

Example

Our simplified example involves the API of a fictional car manufacturer called Wheely. Wheely has software teams supporting two areas of the business: Parts Manufacturing and Car Assembly. Due to various reasons, the two teams prefer not to maintain their shared AppSync API in a single codebase (possibly due to differences like spaces vs. tabs). They decide to split the codebase to better suit their domains' needs but still aim to collectively provide support for a unified GraphQL API to maximize its benefits for the business.

They opt to use AppSync Merged APIs to create a single Wheely API supported by a single AppSync API for each domain. The Car Assembly team wants to manage the core information about Wheely's car offerings, while the Parts Manufacturing team focuses on overseeing the inventory of parts used in the cars. Both teams also see the value in being able to retrieve all parts used in a specific car as a key feature of the API.

API Design

Both source APIs will provide their parts of the overall GraphQL API and each leverage the @canonical annotation to avoid conflicts on Types and Fields.

Car Assembly

The Car Assembly API owns the Car Type and the getCar Query. This schema also has the Car.parts Field, but makes note to other engineers that it does not own it, so other engineers can be aware of this dependency. The same is true for the Part Type.

# Owned by the Parts Manufacturing AppSync API
type Part {
    id: ID!
}

type Car @canonical {
    id: ID!
    make: String!
    model: String!
    # Owned by the Parts Manufacturing AppSync API
    parts: [Part!]!
}

type Query {
    getCar(id: ID!): Car @canonical
}

Parts Manufacturing

The Parts Manufacturing API owns the Part Type and the getPart Field. It also owns the Car.parts Field even though it doesn't own the Car Type. This AppSync API has a resolver for the Car.parts Field and no other source API can add a resolver for that Field, making this API the source of truth for this piece of data.

# Owned by the Car Assembly AppSync API
type Car {
    parts: [Part!]! @canonical
}

type Part @canonical {
    id: ID!
    name: String!
}

type Query {
    getPart(id: ID!): Part @canonical
}

`Car.parts` Resolver

This resolver relies on the IDs of the parts to retrieve being passed to it either via the source or stash in the context. It then uses those IDs to filter its datastore to retrieve the parts needed to fulfill the parts Field for the request.

/**
 * This resolver assumes the part IDs will be a field from the parent field OR be included in the stash.
 */
export function request(ctx) {
    /**
     * @type {string[] | undefined}
     */
    const partIds = ctx.source.partIds ? ctx.source.partIds : ctx.stash.partIds;

    if (partIds === undefined) {
        util.error('No part IDs supplied.')
    }

    const parts = [
        {
            id: "1",
            name: "Headlights"
        },
        {
            id: "2",
            name: "Sunroof"
        },
        {
            id: "3",
            name: "Leather Seats"
        },
        {
            id: "4",
            name: "Cloth Seats"
        }
    ];

    return {
        payload: parts.filter(part => partIds.includes(part.id))
    };
}

export function response(ctx) {
    return ctx.result
}

Merged API

This is the final merged API that the client would depend on. The client doesn't see that the implementation of this is spread across multiple APIs. We've really leaned into the "Interface" part of the API here.

type Car {
  id: ID!
  make: String!
  model: String!
  parts: [Part!]!
}

type Part {
  id: ID!
  name: String!
}

type Query {
  getCar(id: ID!): Car
  getPart(id: ID!): Part
}

Tradeoffs and Considerations

Managing API Design

With the nested Type dependency from the merged APIs, communication between owners of the Source APIs is important. GraphQL design (and any API for that matter) should have time put into the "how" it should work. Doing that over disparate teams and evolving the API over time increases complexity.

Collaboration is always important in software engineering. However, using Merged APIs without a plan of how to drive changes, who owns which parts, or which parts live in which AppSync APIs could hinder success.

Contract Coordination

As you can see in the Car.parts resolver, it expects the partIds data to be passed in either from the parent Field resolver (in the source) or inserted earlier in the request's stash. The implementation in the repository will have the Query.getCar resolver always return the partIds Field to AppSync, even if the client doesn't request the Car.parts Field. It's returning the entire data model.

This works fine for this simple example. But, maybe in the future, the Car Assembly team makes a design decision to only return to AppSync Fields that the client requests, so they can increase performance. If the client doesn't request Car.parts, then the resolver will not return partIds, and then the implicit contract between that API and the Parts Manufacturing API will break.

Similar to the API design consideration above, the software teams need to be aware of the interactions between dependencies and dependents.

"Unowned" API Resources

In AppSync Merged APIs, the resulting API is the combination of all the source APIs. Not everything in the Merged API needs the @canonical annotation though. Source APIs can contribute any Type, Query, Mutation, etc. and not provide any conflict-resolution through the @canonical annotation. Conflicting definitions could result in unexpected behaviors for clients and bugs.