# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code.
*By [NationTech](https://nationtech.io)*

[![Build](https://git.nationtech.io/NationTech/harmony/actions/workflows/check.yml/badge.svg)](https://git.nationtech.io/nationtech/harmony)
[![License](https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square)](LICENSE)

### Unify

- **Project Scaffolding**
- **Infrastructure Provisioning**
- **Application Deployment**
- **Day-2 operations**

All in **one strongly-typed Rust codebase**.

### Deploy anywhere

From a **developer laptop** to a **global production cluster**, a single **source of truth** drives the **full software lifecycle.**

---

## 1 · The Harmony Philosophy

Infrastructure is essential, but it shouldn’t be your core business. Harmony is built on three guiding principles that make modern platforms reliable, repeatable, and easy to reason about.

| Principle | What it means for you |
|-----------|-----------------------|
| **Infrastructure as Resilient Code** | Replace sprawling YAML and bash scripts with type-safe Rust. Test, refactor, and version your platform just like application code. |
| **Prove It Works — Before You Deploy** | Harmony uses the compiler to verify that your application’s needs match the target environment’s capabilities at **compile-time**, eliminating an entire class of runtime outages. |
| **One Unified Model** | Software and infrastructure are a single system. Harmony models them together, enabling deep automation—from bare-metal servers to Kubernetes workloads—with zero context switching. |

These principles surface as simple, ergonomic Rust APIs that let teams focus on their product while trusting the platform underneath.

---

## 2 · Quick Start

The snippet below spins up a complete **production-grade LAMP stack** with monitoring. Swap it for your own scores to deploy anything from microservices to machine-learning pipelines.

```rust
use harmony::{
    data::Version,
    inventory::Inventory,
    maestro::Maestro,
    modules::{
        lamp::{LAMPConfig, LAMPScore},
        monitoring::monitoring_alerting::MonitoringAlertingStackScore,
    },
    topology::{K8sAnywhereTopology, Url},
};

#[tokio::main]
async fn main() {
    // 1. Describe what you want
    let lamp_stack = LAMPScore {
        name: "harmony-lamp-demo".into(),
        domain: Url::Url(url::Url::parse("https://lampdemo.example.com").unwrap()),
        php_version: Version::from("8.3.0").unwrap(),
        config: LAMPConfig {
            project_root: "./php".into(),
            database_size: "4Gi".into(),
            ..Default::default()
        },
    };

    // 2. Pick where it should run
    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
        Inventory::autoload(),                // auto-detect hardware / kube-config
        K8sAnywhereTopology::from_env(),      // local k3d, CI, staging, prod…
    )
    .await
    .unwrap();

    // 3. Enhance with extra scores (monitoring, CI/CD, …)
    let mut monitoring = MonitoringAlertingStackScore::new();
    monitoring.namespace = Some(lamp_stack.config.namespace.clone());

    maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring)]);

    // 4. Launch an interactive CLI / TUI
    harmony_cli::init(maestro, None).await.unwrap();
}
```

Run it:

```bash
cargo run
```

Harmony analyses the code, shows an execution plan in a TUI, and applies it once you confirm. Same code, same binary—every environment.

---

## 3 · Core Concepts

| Term | One-liner |
|------|-----------|
| **Score<T>** | Declarative description of the desired state (e.g., `LAMPScore`). |
| **Interpret<T>** | Imperative logic that realises a `Score` on a specific environment. |
| **Topology** | An environment (local k3d, AWS, bare-metal) exposing verified *Capabilities* (Kubernetes, DNS, …). |
| **Maestro** | Orchestrator that compiles Scores + Topology, ensuring all capabilities line up **at compile-time**. |
| **Inventory** | Optional catalogue of physical assets for bare-metal and edge deployments. |

A visual overview is in the diagram below.

[Harmony Core Architecture](docs/diagrams/Harmony_Core_Architecture.drawio.svg)

---

## 4 · Install

Prerequisites:

* Rust 
* Docker (if you deploy locally)
* `kubectl` / `helm` for Kubernetes-based topologies

```bash
git clone https://git.nationtech.io/nationtech/harmony
cd harmony
cargo build --release          # builds the CLI, TUI and libraries
```

---

## 5 · Learning More

* **Architectural Decision Records** – dive into the rationale  
  - [ADR-001 · Why Rust](adr/001-rust.md)  
  - [ADR-003 · Infrastructure Abstractions](adr/003-infrastructure-abstractions.md)  
  - [ADR-006 · Secret Management](adr/006-secret-management.md)  
  - [ADR-011 · Multi-Tenant Cluster](adr/011-multi-tenant-cluster.md)

* **Extending Harmony** – write new Scores / Interprets, add hardware like OPNsense firewalls, or embed Harmony in your own tooling (`/docs`).

* **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!

---

## 6 · License

Harmony is released under the **GNU AGPL v3**.

> We choose a strong copyleft license to ensure the project—and every improvement to it—remains open and benefits the entire community. Fork it, enhance it, even out-innovate us; just keep it open.

See [LICENSE](LICENSE) for the full text.

---

*Made with ❤️ & 🦀 by the NationTech and the Harmony community*