Setting up a development environment📜
- Start by creating a directory for your project. Then clone each repository within the newly created
directory: dev-environment, Holocron API, Holocron Dashboard, and the collectors from here.
# mkdir holocron
# cd holocron
# git clone https://<link to organization repo>/holocron/dev-environment.git
# git clone https://<link to organization repo>/holocron/holocron-dashboard.git ...etc
Example directory structure for holocron with gitlab instance and collectors below.
holocron/
│
└───holocron-dashboard/
│
└───holocron-api/
│
└───dev-environment/
│
└───collector-gitlab-build/
│
└───collector-gitlab-scm/
│
└───collector-gitlab-workflow/
System architecture📜
Holocron’s system architecture consists of these main components: 1. Holocron UI (also known as Holocron Dashboard): the front-end which shows all the metrics in an interpretable UI. 2. Holocron API: the back-end which is used by the front-end to get metrics from. 3. Collectors: an arbitrary number of microservices whose only purpose is to collect data from a source api (such as Jira, GitLab etc.), transform that data into database schema data and insert into the database record for the Holocron API to use to calculate metrics. It also removes irrelevant data (data that is now older than 1 year or data that no longer exists in the source). 4. Postgres database: the database that is used to store data collected by collectors.
Metrics structure📜
Holocron follows a three-tier structure for metrics aggregation: organization, value stream, and team.
- Organization: The top-level aggregation of all valuestream-level metrics to provide an overview of organizational health.
- Value Stream: A value stream can be thought of as a line of business or product line. This view shows the aggregate metrics for all the teams within that value stream.
- Team: The delivery metrics for a team with additional information needed for tracking the health of delivery pipelines. Additionally, it contains information to help teams achieve a continuous integration workflow. It is a feature of Holocron that metrics between teams cannot be compared.
Access control📜
Holocron has the following access control setup which are turned off in dev-environment. You can also fork your own instance of Holocron and adjust these access controls to your liking.
- Admin: This role has all the global rights to the app with the exception of seeing and updating pay data.
- OrgLeadership: This role only gives the permission to view and update pay data.
- OrgAdmin (Organization Admin): This role gives the permission to view metrics, update, and delete organization. It also give rights to create, view metrics, update, and delete teams and value streams within the organization the person is OrgAdmin for.
- VSAdmin (Value Stream Admin): This role gives the the permission to view metrics, update and delete value stream. It also gives rights to create, view, update, and delete teams within the value stream the person is VSAdmin for.
- TeamAdmin (Team Admin): This role gives the permission to view metrics, update, and delete team the person is TeamAdmin for.
More on these roles access control is show in the matrix below.
Please be aware that the following roles: Organization Leader, Organization Admin, Value Stream Admin, and Team Admin, are granted and relevant only within the confines of their respective organizations.
Y 1 user must also be admin of organization
Y 2 user must also be admin of value stream
Y 3 user must also be admin of Organization which contains value stream
Y 4 user must also be admin of Team
Y 5 user must also be admin of Value stream which contains Team
| Permissions | Admin + OrgLeadership | Admin | Org admin | Org admin + OrgLeadership | VS Admin | VS Admin + OrgLeadership | Team Admin | Team Admin + OrgLeadership |
|---|---|---|---|---|---|---|---|---|
| Create Organization | Y | Y | ||||||
| Read Organization Metrics | Y | Y | Y 1 | Y 1 | ||||
| Read Organization Cost Metrics | Y | Y 1 | ||||||
| Update Organization | Y | Y | Y 1 | Y 1 | ||||
| Delete Organization | Y | Y | Y 1 | Y 1 | ||||
| Create Value Stream | Y | Y | Y | Y | ||||
| Read Value Stream Metrics | Y | Y | Y 1 | Y 1 | Y 2 | Y 2 | ||
| Read Value Stream Cost Metrics | Y | Y 3 | Y 2 | |||||
| Update Value Stream | Y | Y | Y 3 | Y 3 | Y 2 | Y 2 | ||
| Delete Value Stream | Y | Y | Y 3 | Y 3 | Y 2 | Y 2 | ||
| Create Team | Y | Y | Y | Y | Y | Y | ||
| Read Team Metrics | Y | Y | Y 1 | Y 1 | Y 5 | Y 5 | Y 4 | Y 4 |
| Read Team Cost Metrics | Y | Y 1 | Y 2 | Y 4 | ||||
| Update Team | Y | Y | Y 1 | Y 1 | Y 2 | Y 2 | Y 4 | Y 4 |
| Delete Team | Y | Y | Y 1 | Y 1 | Y 2 | Y 2 | Y 4 | Y 4 |
| Delete User | Y | Y |
Semantic Versioning📜
Holocron semantic versioning changes revolve around the Holocron API. As such, the following statements are applicable whenever you are using an older or new version of the Holocron API.
- MAJOR version: when we make incompatible API changes (example: refactoring changes such as what the front-end gets as data, or what the collectors get as model). Whenever the Holocron API does a major update, all other services (collectors and front-end) also update their current major version.
- MINOR version: when we add functionality in a backwards compatible manner (example: adding new models that are unrelated, new features etc for the API). Whenever the Holocron API does a minor update, all other services (collectors and front-end) also update their current minor version.
- PATCH version: when we make backwards compatible bug fixes (example: pretty self explanatory, just fixing dependency vulnerabilities as well as bugs). Whenever the Holocron API does a patch update, all other services (collector and front-end) are left unchanged in the version.