harmony/docs/concepts.md

Core Concepts

Harmony's design is based on a few key concepts. Understanding them is the key to unlocking the framework's power.

1. Score

• What it is: A Score is a declarative description of a desired state. It's a "resource" that defines what you want to achieve, not how to do it.
• Example: ApplicationScore declares "I want this web application to be running and monitored."

2. Topology

• What it is: A Topology is the logical representation of your infrastructure and its abilities. It's the "where" your Scores will be applied.
• Key Job: A Topology's most important job is to expose which Capabilities it supports.
• Example: HAClusterTopology represents a bare-metal cluster and exposes Capabilities like NetworkManager and Switch. K8sAnywhereTopology represents a Kubernetes cluster and exposes the K8sClient Capability.

3. Capability

• What it is: A Capability is a specific feature or API that a Topology offers. It's the "how" a Topology can fulfill a Score's request.
• Example: The K8sClient capability offers a way to interact with a Kubernetes API. The Switch capability offers a way to configure a physical network switch.

4. Interpret

• What it is: An Interpret is the execution logic that makes a Score a reality. It's the "glue" that connects the desired state (Score) to the environment's abilities (Topology's Capabilities).
• How it works: When you apply a Score, Harmony finds the matching Interpret for your Topology. This Interpret then uses the Capabilities provided by the Topology to execute the necessary steps.

5. Inventory

• What it is: An Inventory is the physical material (the "what") used in a cluster. This is most relevant for bare-metal or on-premise topologies.
• Example: A list of nodes with their roles (control plane, worker), CPU, RAM, and network interfaces. For the K8sAnywhereTopology, the inventory might be empty or autoloaded, as the infrastructure is more abstract.

---

How They Work Together (The Compile-Time Check)

1. You write a Score (e.g., ApplicationScore).
2. Your Score's Interpret logic requires certain Capabilities (e.g., K8sClient and Ingress).
3. You choose a Topology to run it on (e.g., HAClusterTopology).
4. At compile-time, Harmony checks: "Does HAClusterTopology provide the K8sClient and Ingress capabilities that ApplicationScore needs?"
   • If Yes: Your code compiles. You can be confident it will run.
   • If No: The compiler gives you an error. You've just prevented a "config-is-valid-but-platform-is-wrong" runtime error before you even deployed.