# Claude Code Instructions — fabric-orchestrator

## Project Context

Fabric-orchestrator manages Arista EVPN-VXLAN fabrics using Infrahub as the source of truth.
Gitea: https://gitea.arnodo.fr/Damien/fabric-orchestrator
Branch: `feature/41-infrahub-schema`

## Reference Topology (overlaid.net)

- 2 spines (AS 65000), 8 leafs in 4 MLAG pairs (AS 65001–65004)
- Loopback0: BGP router-id per device, Loopback1: shared VTEP IP per MLAG pair
- VLANs 4090 (MLAG peer) / 4091 (MLAG iBGP) with trunk groups
- Underlay: eBGP point-to-point (spine↔leaf) + iBGP (leaf↔leaf peer)
- Overlay: EVPN eBGP multihop on loopbacks, spines as route-reflectors with next-hop-unchanged
- L2VXLAN (EVPN Type-2): VLAN→VNI mapping, redistribute learned
- L3VXLAN (EVPN Type-5): VRF→VNI mapping, redistribute connected
- Border peering: BGP sessions inside VRF (leaf7/8 → AS 64999 in VRF gold)

## Schema Files (Infrahub YAML format, in `schemas/`)

| File             | Content                                                                       |
| ---------------- | ----------------------------------------------------------------------------- |
| `base.yml`       | Device, Interfaces (Ethernet, Loopback, Vlan, Lag, Vxlan), IPAddress          |
| `bgp.yml`        | AutonomousSystem, BGPRouterConfig, BGPPeerGroup, BGPSession, BGPAddressFamily |
| `vlan_vxlan.yml` | VLAN, VNI, VTEP, VlanVniMapping, EVPNInstance                                 |
| `vrf.yml`        | VRFConfig, RouteTarget, VRFDeviceAssignment                                   |
| `mlag.yml`       | MlagDomain, MlagPeerConfig, MlagInterface                                     |
| `extensions.yml` | UnderlayLink, HostConnection, FabricSettings                                  |

## Infrahub Schema Rules

1. `human_friendly_id` fields MUST have `unique: true` — globally unique across all instances
2. To scope human_friendly_id per-device, traverse Parent relationships:
   `parent_rel__parent_attr__value` (e.g. `device__name__value`)
3. Parent relationships (`kind: Parent`) need `optional: false` explicitly
4. Self-referencing relationships need `direction: outbound`
5. Multiple relationships to the same peer type need distinct `identifier` values
6. Don't model the same concept twice (e.g. VTEP source_address vs InterfaceVxlan source_interface)
7. `kind: Attribute` for association, `kind: Component` for ownership (lifecycle-coupled)
8. `kind: Parent` implies the child cannot exist without the parent

## Validation

```bash
infrahubctl schema check schemas/
```

Always run before committing. Fix any errors before pushing.

## Commit Convention

```
fix(schema): short description — refs #<issue>
feat(schema): short description — refs #<issue>
```

- One logical change per commit
- Reference the Gitea issue number
- Comment on the issue after implementation with changes summary

## Open Issues (prioritized)

Check https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues for current backlog.
Critical issues (blocking data load) take priority over functional improvements.
Dependency chain: resolve critical → significant → minor sequentially.

## Workflow

1. Read the issue description fully before starting
2. Read relevant schema files to understand current state
3. Make minimal, targeted changes
4. Validate with `infrahubctl schema check schemas/`
5. Commit with proper message referencing the issue
6. Comment on the Gitea issue with what was changed

## Don'ts

- Don't add fields not needed by the reference topology
- Don't change `human_friendly_id` without checking uniqueness implications
- Don't remove existing relationships without checking reverse dependencies
- Don't create new schema files without discussing first