Objects overview

Objects are the building blocks of GitLab. They exist within users' mental models for our product, and are consistently referenced across all levels of the product stack: database, code, user interface (UI), documentation, customer support, sales, marketing, and more.

Examples of objects from products you may know:

  • Facebook: friend, post, message, event, page, group.
  • Airbnb: listing, host, guest, trip, experience.
  • Slack: team, member, channel, message, reaction, thread.
  • Intercom: customer, teammate, message, conversation, article.

GitLab's objects include: repository, issue, merge request, job, and others.

Object thinking

Thinking in terms of objects is about abstracting concepts (meaning) from the UI (representation). It doesn't matter how users interact with the objects to achieve their goals. We can use the same objects to build any kind of interface: a mobile app, a web app, a plugin for another app, an API, a voice-controlled app, etc.

GitLab is a large and complex product. It is sometimes difficult to understand how the experience that you are designing fits into the broader picture. Object thinking may bring clarity on how our product fits together. There are many benefits to this:

  • Identify inconsistencies and duplication in the system.
  • Identify opportunities for feature additions or enhancements.
  • Design features that work well from a conceptual point of view, regardless of how they are represented in the UI.
  • Improve communication and understanding about how the system works.

Above all, object thinking helps build a solid foundation for the user experiences we're creating.

Learn more about objects in “The full stack design system”, where Intercom shares the need, benefits, and how they use objects to build their product.


There are two main ways to document objects, each with its purpose: the conceptual model and semantic layouts.

Conceptual model

The conceptual model is the visual representation of object thinking. It helps us visualize GitLab's objects and their relationships, and unlocks the benefits of object thinking. The result is an easy-to-navigate diagram of GitLab's object architecture. To better understand this visualization, see below the annotated example of a tweet or the GitLab-specific example of a merge request.

View tweet conceptual model in Figma →

For each object, we document its attributes, actions, and how it relates to other objects in the system. The resulting diagram is independent of how we represent the objects in the UI or implement them in code. It should be as simple and accessible as possible, even if people aren't familiar with these kinds of diagrams. Learn more about conceptual models in “Object Modeling for Designers”.

Semantic layouts

Objects can be presented in the UI through different visual layouts. To give meaning to each part of those visual layouts, from the smallest components to the largest regions, we can document them as “semantic layouts”. In practice, a semantic layout places the objects (and their relationships, attributes, and actions) over the layout, so we can see their meaning and purpose. As an example, see the merge request semantic layout.


To add or update an object's documentation, conceptual model, or semantic layout, create an issue with the “Object documentation” template and follow its instructions.

Learn more

Last updated at: