# harness/harness-schema architecture

> Architecture diagram of the GitHub repository harness/harness-schema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harness/harness-schema
- Repository: https://github.com/harness/harness-schema

## Overview

##### Project Type & Purpose
- This is an open-source “schema store” and generation tool for Harness NextGen Pipeline YAML.
- It provides JSON/YAML schema definitions (v0/v1) for pipelines, templates, triggers, events, etc., and a bundler to generate `pipeline.json` and `template.json`.
- Consumers include:
- Harness Pipeline Service & Template Service (prod/QA/local)
- IDEs/Text editors (VS Code, Sublime) via YAML extension
- Devspaces environment (fetches remote schema)

##### File Structure Analysis
- Top-level:
- `bundler/` – Java code & Bazel rules to assemble schema modules (`SchemaBundleTool`, `SchemaBundlerRegistrar`).
- `v0/`, `v1/` – Versioned schema directories containing:
– `pipeline.json`, `template.json` (root schemas)
– `pipeline/`, `template/`, `trigger/`, `steps/`, etc. subdirectories of YAML schema definitions.
- `cdevents/` – Conformance templates and event examples.
- `scripts/` – Node.js scripts for generating Markdown docs or aiding bundler.
- Build config: `WORKSPACE`, `BUILD.bazel`, `.bazelversion`, plus `bundler/tools/bazel` macros.

##### README Insights
- Explains how to embed schemas in VS Code/Sublime via remote URLs.
- Describes a runtime flag (`USE_SCHEMA_FROM_HARNESS_SCHEMA_REPO`) to toggle between local and remote schema consumption.
- Defines the Bazel command to regenerate schemas:
`bazel run bundler/schema_store:module`

a. Main Components
- Schema Generation Pipeline
- Bundler Module (Java + Bazel)
- Input: YAML schema source files (`v*/.../*.yaml`)
- Output: `v*/pipeline.json`, `v*/template.json`
- Schema Store Repositories
- GitHub harness-schema repo with versioned folders
- Consumers
- Harness Pipeline Service & Template Service (microservices)
- IDE/Text Editor Plugins (YAML extension in VS Code/Sublime)
- Devspaces/CI environments
b. Relationships & Interactions
- Bundler → Schema Store: on commit, Bazel build triggers Java tool to produce JSON schemas under `v0/`, `v1/`.
- Harness Services (Pipeline/Template) load schema:
- If `USE_SCHEMA_FROM_HARNESS_SCHEMA_REPO=false`, read `v*/pipeline.json` locally.
- If `USE_SCHEMA_FROM_HARNESS_SCHEMA_REPO=true`, fetch remote JSON from GitHub.
- IDEs consume remote URLs directly for auto-intelliSense.
c. Architectural Patterns & Principles
- Code-generation pipeline: source YAML → Java tool → JSON Schema artifacts.
- Versioned API schema: v0/v1 directories to support backward compatibility.
- Flag-driven configuration for flexibility (local vs remote schema).
- Clear separation of concerns: schema definition vs schema consumption.
d. Key Technologies & Frameworks
- Bazel build system & custom Starlark macros
- Java (bundler code) + Maven metadata (main_maven_install.json)
- JSON Schema & YAML definitions
- Node.js scripts (Markdown generation)
- cdevents specification files for event conformance

##### Detailed Coverage
- Bundler’s internal flow: Java classes → registration → module output.
- Versioning folder structure and that both v0 and v1 are maintained in parallel.
- Where cdevents and scripts fit in (optional extensions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Schema Generation Pipeline
    subgraph "Schema Generation Pipeline"
        direction TB
        SchemaBundleTool["SchemaBundleTool (Java)"]:::code
        SchemaBundlerRegistrar["SchemaBundlerRegistrar (Java)"]:::code
        BUILD_WS["BUILD.bazel & WORKSPACE"]:::code
        Macros["Starlark Macros"]:::code
        V0Src["YAML Sources v0"]:::artifact
        V1Src["YAML Sources v1"]:::artifact
        SchemaBundleTool -->|invokes| SchemaBundlerRegistrar
        BUILD_WS -->|configures| SchemaBundleTool
        Macros -->|used by Bazel| SchemaBundleTool
        V0Src -->|input| SchemaBundleTool
        V1Src -->|input| SchemaBundleTool
    end

    %% Generated Schema Artifacts
    subgraph "Schema Artifacts" 
        direction TB
        GenV0["v0/pipeline.json, template.json, trigger.json"]:::artifact
        GenV1["v1/pipeline.json, template.json, trigger.json"]:::artifact
        SchemaBundleTool -->|"bazel run schema_store"| GenV0
        SchemaBundleTool -->|"bazel run schema_store"| GenV1
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        direction TB
        CDEvents["cdevents/"]:::artifact
        GenMD["generateMarkdown.js"]:::code
        Templates["templates.js"]:::code
        Onboard["developer-onboarding.md"]:::artifact
    end

    %% Consumers
    subgraph "Consumers" 
        direction TB
        PipelineService["Harness Pipeline Service"]:::consumer
        TemplateService["Harness Template Service"]:::consumer
        IDEs["IDEs/Text Editors"]:::consumer
        Devspaces["Devspaces/CI Environments"]:::consumer
    end

    %% Remote Schema Repo
    GitHub["GitHub Schema Repo"]:::external

    %% Interactions to Consumers
    GenV0 -->|flag=false local load| PipelineService
    GenV1 -->|flag=false local load| PipelineService
    GenV0 -->|flag=false local load| TemplateService
    GenV1 -->|flag=false local load| TemplateService

    GitHub -->|flag=true remote fetch| PipelineService
    GitHub -->|flag=true remote fetch| TemplateService

    GitHub -->|remote fetch| IDEs
    GitHub -->|remote fetch| Devspaces

    %% Click Events
    click SchemaBundleTool "https://github.com/harness/harness-schema/blob/main/bundler/schema_store/src/main/java/io/harness/SchemaBundleTool.java"
    click SchemaBundlerRegistrar "https://github.com/harness/harness-schema/blob/main/bundler/schema_store/src/main/java/io/harness/bundler/SchemaBundlerRegistrar.java"
    click BUILD_WS "https://github.com/harness/harness-schema/blob/main/BUILD.bazel"
    click Macros "https://github.com/harness/harness-schema/blob/main/bundler/tools/bazel/macros.bzl"
    click V0Src "https://github.com/harness/harness-schema/tree/main/v0/"
    click V1Src "https://github.com/harness/harness-schema/tree/main/v1/"
    click GenV0 "https://github.com/harness/harness-schema/blob/main/v0/pipeline.json"
    click GenV1 "https://github.com/harness/harness-schema/blob/main/v1/pipeline.json"
    click CDEvents "https://github.com/harness/harness-schema/tree/main/cdevents/"
    click GenMD "https://github.com/harness/harness-schema/blob/main/scripts/generateMarkdown.js"
    click Templates "https://github.com/harness/harness-schema/blob/main/scripts/templates.js"
    click Onboard "https://github.com/harness/harness-schema/blob/main/developer-onboarding.md"

    %% Styles
    classDef code fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef artifact fill:#e6ffe6,stroke:#33cc33,color:#000;
    classDef consumer fill:#ffe6cc,stroke:#ff9933,color:#000;
    classDef external fill:#f2f2f2,stroke:#999999,color:#000;
```
