Parts & trails
A part is a related piece of a product or service that has a lifecycle (creation, operation, evolution, deprecation), and can be recursively made of smaller parts. Events and work items must be related to parts. In general, parts are the core objects that almost all other objects will link to, which helps enforce the notion of tying everything back to the product or service.
There are two core categories of parts: rev parts and dev parts.
Rev parts relate to how a product is expressed, integrated, or consumed. These parts may be consumed by external customers (revs) or internal employees (devs). Although they may also be provided/enabled by dev parts running internally, the customer just sees the product, service or feature they are interacting with. Rev parts may also be abstractions on other rev parts exposed by 3rd parties (such as Auth0 or s3).
For example, in the digital world, rather than integrating with code or packages, they may integrate with APIs.
Dev parts are those built internally related to code or something the developer relies on or builds, or a service provided by an or. These may be runnables that may expose APIs or linkables that may be used in other services (such as utils or libraries). Though they may provide the functionality exposed and interacted with by the customer, they are often abstracted and unknown to the user.
Types of parts typically include:
The part hierarchy is at the core of the DevRev platform and is the basis for tying all work and event funnels to a common product or service model and for coordinating across funnels.
The following figure shows the conceptual part hierarchy.
Product or service#
At the highest level of the part hierarchy is a product or service. An organization may have one or more products or services they deliver to their customers. Products can also be delivered through one or more conduits (such as tangible goods or as-a-service).
Products typically have the following characteristics:
- Are a unit of profit and loss (P&L)
- Are where customers (internal or external) are onboarded
- Provide the basis for identity
- May have a notion of billing/chargeback (which can be done at this level or further down the stack)
Services may have the following additional characteristics:
- Provide an API or interface
- Define code-based or business services
One example of the difference between a product and a service is Microsoft Office (software product) versus Office 365 (cloud service).
A key to consider is that all must be considered in the perspective of the Dev Org. A product for them may be a service for another. For example, consider a managed services provider, they may provide a "product" (e.g. Microsoft Exchange) delivered as a managed service.
A service may also be a business service like IT (internal), HR (internal) or Consulting (external.)
Example products delivered as software or tangible goods:
- Hardware products (Lenovo laptops, etc.)
- Software products (MSFT Office, Acrobat, etc.)
- Cloud services (Amazon Web Services, Azure, GCP)
- IT services (Helpdesk, Data center, etc.)
- Facilities services (building services, lunch services)
The following figure shows DevRev's products (some internal, some external).
A capability exists under a product or service and is commonly the main item of interaction for customers.
Capabilities typically have the following characteristics:
- Exist under a product or service
- Provide the ability to do something (verbs) with entities (nouns); for example
- Provide an API namespace
- Provide units of licensing and pricing
- Have its own level of authentication and access control or may inherit from the product
The following figure shows some DevRev product capabilities.
A feature exists under a capability (or feature for sub-features) and is commonly a unit of configuration or "knobs" in a capability.
Features typically have the following characteristics:
- Exist under a capability (or feature for sub-features)
- Provide a unit of configuration (adjective) for entities managed by the capability
- Enable version history (adjective) on object
- May provide a subset of the API namespace
- Are interacted with only inside the context of the capability or not directly interacted with at all
The following figure shows some sample DevRev product features.
You can add a sub-feature to a feature for a more granular breakdown of features. These leverage the same feature object and have the same attributes. The only difference is that their parent will be a feature rather than a capability.
A runnable is a dev part and is something that can be instantiated or do something. Example runnables may be macroservices, microservices, o functions (lambdas). Runnables are things that have some direct execution or lifespan. A runnable may serve one or more features and/or capabilities.
Runnables typically have the following characteristics:
- Are a unit of functionality that can be deployed independently or as part of a larger system
- Have an execution lifecycle be it short (lambda/function) or long (microservice)
- Expose an API
- Are interacted with directly via an API or UI
- Are published in a service registry or load balancer
- Docker image
- Lambda bundle
Example DevRev runnables:
- Wisp (search)
- Codex (work SOR)
- Partiql (parts SOR)
The following figure shows some sample DevRev product runnables.
A linkable is a unit of functionality that is designed to be part of a system or application and not used directly. These commonly refer to things like libraries or utils that may be leveraged by multiple runnables.
Components typically have the following characteristics:
- Linkable items are commonly used as libraries or binary artifacts
- Not commonly exposed to the consumer (but can be)
- Are intended to be used as part of larger services, not on their own
Example linkable parts:
- Golang package
Example DevRev Linkables:
- all clients (e.g. partiql-client, codex-client, mfz-client)
- shared (logging, etc.)
Trails is an extensible interface that allows you to view and manage your part hierarchy and related items. Think of it like a graph canvas that is rendering linkages between items making them easier to navigate and summarize.
The following image shows an example of DevRev's trails view.
The following image shows an example of the trails top contributors.
Parts Discovery [BETA]#
The customer will need to opt into Parts Discovery since it is still a beta offering.
The customer can use any or all of the following options to seed DevRev parts discovery with data.
Custom File Upload
You can provide information about the API paths, services, and routing rules using a
custom_routing.json file that implements a simple schema.
Following is an example of the custom file and the corresponding trail showing the parts discovered through it:
The Import option on the Trails in the product provides an easy interface to download a template file, which can be filled and uploaded.
Link Git repository with API documentation
Features are discovered by analyzing OpenAPI specification files found in the git repository integrated with the DevRev App.
The Trail can be discovered by installing the DevRev Kubernetes Collector on your cluster. Parts Discovery algorithm relies on the Feature APIs exposed via the Kubernetes Ingress context.
The helm charts to install the collector along with the instructions to install are available via our git repository here.
Our collector is a lightweight cronjob which runs once in 6 hours and consumes minimum resources. We cap our utilization and expose the limits in a public helm value file.