# OpenRig — Architecture Overview

## What is a rig?

A system that translates animator **inputs** into deformation **outputs** through a **process**. OpenRig never assumes what inputs, outputs, or processes look like. The library provides the tools; the rigger decides what to build.

---

## Core Principles

- **Modular** — the fundamental unit is a *solution*. A full rig is a composition of solutions.
- **Extensible** — new solutions or operations can be added without modifying what already exists.
- **Reconstructable** — a rig can always be rebuilt from its description.

---

## Workflow

```text
DESCRIPTION  →  BUILD  →  SCENE
(JSON)          (Maya)    (rig + metadata)
```

1. **Description** — the rig is defined as data outside Maya. A JSON file says what to build.
2. **Build** — the description is materialized in Maya.
3. **Scene** — the built rig includes metadata, so its description can be recovered.

---

## Package Structure

```text
openrig/
├── naming/        ← naming system (config-driven)
├── conventions/   ← rigging convention defaults (config-driven)
│
├── maya/
│   ├── core/      ← base classes every solution must implement
│   ├── ops/       ← atomic Maya operations
│   ├── solutions/ ← concrete rig components (arm, spine, twist…)
│   └── build/     ← build pipeline (description → Maya scene)
│
└── builder/       ← high-level interface to drive builds
```

---

## Module Summary

| Module | Description |
| --- | --- |
| `naming/` | Generates and validates names for all rig objects. Config-driven via `naming/config.json`. |
| `conventions/` | Rigging defaults (axes, rotate order, default side). Config-driven via `conventions/config.json`. Singleton: `get_conventions()`. |
| `maya/core/` | Base classes every solution must implement: inputs, outputs, `build()`. |
| `maya/ops/` | Atomic Maya operations. One function does one thing. Building blocks for solutions. |
| `maya/solutions/` | Concrete rig components (arm, spine, twist…). Each implements the `maya/core/` contract. |
| `maya/build/` | Orchestrates the full build: reads the description, instantiates solutions, assembles the rig. |
| `builder/` | High-level interface to manage and trigger builds without writing code directly. |

---

## Layer Rules

Each layer only depends on the layer below it:

- `builder/` → uses `maya/build/`
- `maya/build/` → uses `maya/solutions/` and `naming/`
- `maya/solutions/` → implements `maya/core/`, uses `maya/ops/`, uses `conventions/`
- `maya/ops/` → calls Maya API directly
- `naming/` → no dependencies on Maya
- `conventions/` → no dependencies on Maya

This means any addition is local:

- **New solution or variant** → new file in `maya/solutions/`. Nothing else is touched.
- **New Maya operation** → new function in `maya/ops/`. Existing solutions are unaffected.

---

## Development Order

1. `naming/`
2. `maya/core/` — base classes: what every solution must expose
3. `maya/ops/` — atomic operations
4. `maya/solutions/` — concrete solutions
5. `maya/build/` — build pipeline
6. `builder/` — high-level interface

---

## Open Questions

- What exactly must a solution expose in `maya/core/`? Inputs, outputs, a `build()` method?
- How does a solution declare what it needs vs what it produces?
- How are solutions composed to form a complete rig?