Teams

Teams are organizational units that group people together. They represent departments, working groups, project teams, or any other collection of individuals who collaborate on shared goals.

What Is a Team Entity?

A team entity captures the structure and composition of an organizational unit. Teams provide the “who works together” layer in your knowledge graph, connecting individual people to collective responsibility.

Every team entity has:

• A name (e.g., “Platform Engineering”, “Product Design”)
• An optional description of the team’s purpose
• An optional parent team for hierarchical organization
• An optional email address for team contact
• An optional icon for visual identification
• Members (people who belong to this team)
• Owned landmarks (services, projects, or resources the team is responsible for)

Key Features

Hierarchical Structure

Teams can have parent-child relationships, creating an organizational hierarchy. Hierarchy is optional and can be as shallow or deep as needed.

Team Membership

Connect people to teams. Membership is defined on person entities, and team cards automatically reflect their members.

Landmark Ownership

Teams can own landmarks, establishing clear responsibility for services, projects, and resources.

Team Properties

Required properties:

• Name: The team’s display name (e.g., “Engineering”, “Customer Success”)

Optional properties:

• Description: A brief summary of the team’s purpose and responsibilities
• Parent Team: The team this team reports to or falls under in the hierarchy
• Email: Contact email address for the team (e.g., [email protected])
• Icon: A visual identifier from FontAwesome or a custom URL
• Links: Quick-access URLs to team dashboards, shared drives, or collaboration spaces
• Documentation: Markdown files for team charters, onboarding guides, or process documentation
• Pinned: Whether the team appears at the top of lists
• Featured: Whether the team is highlighted in special views

Hierarchical Structure

Teams can have parent-child relationships, creating an organizational hierarchy. This structure helps you understand reporting lines, escalation paths, and how teams relate to each other.

Parent Team: When you create a team, you can optionally assign a parent team. For example:

• “Platform Engineering” might be a child of “Engineering”
• “Frontend” might be a child of “Platform Engineering”
• “Engineering” might have no parent (it’s a top-level team)

Hierarchy in the UI:

• Team cards display the parent team name in the subtitle
• The topology explorer visualizes the hierarchy as a tree structure
• Search results show the full path (e.g., “Engineering > Platform Engineering > Frontend”)

Best Practices for Hierarchy:

• Keep hierarchies shallow (2-3 levels maximum) to avoid complexity
• Use parent teams to represent organizational structure, not project relationships
• Not every team needs a parent; top-level teams are valid

Hierarchy Is Optional

You don’t need to define a complete organizational hierarchy. Create teams at whatever level makes sense for your organization. Some teams are standalone; others fit into a larger structure. Both approaches work.

Team Membership

Team membership connects people to teams. A person can belong to multiple teams, and a team can have multiple members.

How Membership Works:

• Membership is defined on the person entity, not the team entity
• When you create or edit a person, you select which teams they belong to
• The team entity automatically reflects its members based on these assignments
• Team cards display the member count and show member avatars

Viewing Members:

• Click a team card to open the detail drawer
• The detail drawer shows all team members with their names and titles
• Click any member to navigate to their person entity

Managing Membership:

• To add someone to a team, edit their person entity and select the team
• To remove someone from a team, edit their person entity and deselect the team
• Changes take effect immediately and are reflected on both the person and team cards

Owned Landmarks

Teams can own landmarks, establishing clear responsibility for services, projects, and resources.

What Ownership Means:

• The team is responsible for maintaining, updating, and answering questions about the landmark
• Ownership is displayed on the landmark card (e.g., “Owner: Platform Engineering”)
• The team’s detail drawer shows all landmarks it owns
• The topology explorer visualizes ownership relationships

Assigning Ownership:

• When creating or editing a landmark, select a team as the owner
• A landmark can have one owner (either a team or a person, not both)
• Ownership can be transferred by editing the landmark and changing the owner field

Why Ownership Matters:

• Clear accountability: Everyone knows who to contact about a service
• Impact analysis: When a team changes, you can see which landmarks are affected
• Onboarding: New team members can quickly see what their team is responsible for

When to Create a Team Entity

Create a team entity when:

• A group of people collaborates regularly: If multiple people work together on shared goals, create a team to represent that collaboration.

• The team owns something: If a group is responsible for services, projects, or resources, create a team so you can assign ownership.

• You need to track organizational structure: If your organization has departments, squads, or working groups, create teams to map that structure.

• People reference the team: If people say “I’m on the Platform team” or “Contact the Design team,” create a team entity to make that explicit.

Teams in the User Interface

Team entities appear throughout Legend:

• Dashboard: Team cards display alongside landmarks and people in the main grid
• Search: Search for teams by name, description, or member names
• Filters: Filter the dashboard to show only teams using the type filter
• Person cards: Person cards show team membership count and team names
• Landmark cards: Landmark cards show the owner team name
• Topology: Visualize team hierarchy, membership, and ownership relationships
• Detail drawer: Click a team card to see members, owned landmarks, and parent team

Teams vs Other Entity Types

Understanding the distinction between entity types:

• Team: An organizational unit that groups people together (the “who together”)
• Person: An individual contributor (the “who”)
• Landmark: Something in your organization that teams and people work on (the “what”)

Teams own landmarks and have members. This creates a clear structure: teams are responsible for services, projects, and resources, and people belong to teams. When you need to find who owns something, you trace from the landmark to the team to the team members.

Related

People

Landmarks

Creating Entities