# 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.**

## 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.

## Where to Start

We have a comprehensive set of documentation right here in the repository.

| I want to...      | Start Here                                                         |
| ----------------- | ------------------------------------------------------------------ |
| Get Started       | [Getting Started Guide](./docs/guides/getting-started.md)          |
| See an Example    | [Use Case: Deploy a Rust Web App](./docs/use-cases/rust-webapp.md) |
| Explore           | [Documentation Hub](./docs/README.md)                              |
| See Core Concepts | [Core Concepts Explained](./docs/concepts.md)                      |

## Quick Look: Deploy a Rust Webapp

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

```rust
use harmony::{
    inventory::Inventory,
    modules::{
        application::{
            ApplicationScore, RustWebFramework, RustWebapp,
            features::{PackagingDeployment, rhob_monitoring::Monitoring},
        },
        monitoring::alert_channel::discord_alert_channel::DiscordWebhook,
    },
    topology::K8sAnywhereTopology,
};
use harmony_macros::hurl;
use std::{path::PathBuf, sync::Arc};

#[tokio::main]
async fn main() {
    let application = Arc::new(RustWebapp {
        name: "harmony-example-leptos".to_string(),
        project_root: PathBuf::from(".."), // <== Your project root, usually .. if you use the standard `/harmony` folder
        framework: Some(RustWebFramework::Leptos),
        service_port: 8080,
    });

    // Define your Application deployment and the features you want
    let app = ApplicationScore {
        features: vec![
            Box::new(PackagingDeployment {
                application: application.clone(),
            }),
            Box::new(Monitoring {
                application: application.clone(),
                alert_receiver: vec![
                    Box::new(DiscordWebhook {
                        name: "test-discord".to_string(),
                        url: hurl!("https://discord.doesnt.exist.com"), // <== Get your discord webhook url
                    }),
                ],
            }),
        ],
        application,
    };

    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(), // <== Deploy to local automatically provisioned local k3d by default or connect to any kubernetes cluster
        vec![Box::new(app)],
        None,
    )
    .await
    .unwrap();
}
```

To run this:

- Clone the repository: `git clone https://git.nationtech.io/nationtech/harmony`
- Install dependencies: `cargo build --release`
- Run the example: `cargo run --example try_rust_webapp`

## Documentation

All documentation is in the `/docs` directory.

- [Documentation Hub](./docs/README.md): The main entry point for all documentation.
- [Core Concepts](./docs/concepts.md): A detailed look at Score, Topology, Capability, Inventory, and Interpret.
- [Component Catalogs](./docs/catalogs/README.md): Discover all available Scores, Topologies, and Capabilities.
- [Developer Guide](./docs/guides/developer-guide.md): Learn how to write your own Scores and Topologies.

## Architectural Decision Records

- [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)

## Contribute

Discussions and roadmap live in [Issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!

## 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_