docs(schema): add schema documentation and ERD

Document all schema files, entity relationships, and mapping
to the reference arista-evpn-vxlan-clab topology.

Ref: #41

schemas/README.md

@@ -0,0 +1,113 @@
+# Infrahub Schema for EVPN-VXLAN Fabric
+
+This directory contains the Infrahub schema definitions for modeling an EVPN-VXLAN fabric. The schema is designed to represent the [arista-evpn-vxlan-clab](https://gitea.arnodo.fr/Damien/arista-evpn-vxlan-clab) topology.
+
+## Schema Files
+
+| File | Description |
+|------|-------------|
+| `base.yml` | Core infrastructure: Device, Interface types, IP Address, Platform, Site |
+| `vlan_vxlan.yml` | VLAN, VNI, VTEP, EVPN Instance |
+| `vrf.yml` | VRF, Route Target, VRF assignments |
+| `bgp.yml` | Autonomous System, BGP Config, Peer Groups, Sessions |
+| `mlag.yml` | MLAG Domain, Peer Config, MLAG Interfaces |
+| `extensions.yml` | Fabric, Underlay Links, Host Connections |
+
+## Entity Relationship Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              FABRIC TOPOLOGY                                │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+                              ┌──────────────┐
+                              │  InfraFabric │
+                              └──────┬───────┘
+                                     │
+              ┌──────────────────────┼──────────────────────┐
+              │                      │                      │
+              ▼                      ▼                      ▼
+       ┌────────────┐        ┌─────────────┐        ┌────────────┐
+       │ LocationSite│       │ InfraDevice │        │InfraAutono-│
+       └────────────┘        │  (spine/    │        │mousSystem  │
+                             │   leaf)     │        └─────┬──────┘
+                             └──────┬──────┘              │
+                                    │                     │
+       ┌────────────────────────────┼─────────────────────┤
+       │                            │                     │
+       ▼                            ▼                     ▼
+┌──────────────┐            ┌──────────────┐      ┌──────────────┐
+│InfraInterface│            │InfraMlagDomain│     │InfraBGPRouter│
+│  (generic)   │            │  (leaf pair) │     │   Config     │
+└──────┬───────┘            └──────────────┘      └──────┬───────┘
+       │                                                  │
+       │   ┌─────────────────────────┬───────────────────┤
+       │   │                         │                   │
+       ▼   ▼                         ▼                   ▼
+┌──────────────┐            ┌──────────────┐      ┌──────────────┐
+│InterfaceTypes│            │InfraBGPPeer- │      │ InfraBGP-    │
+│ - Ethernet   │            │    Group     │      │  Session     │
+│ - Loopback   │            │ (underlay,   │      │ (neighbors)  │
+│ - Vlan       │            │  evpn)       │      └──────────────┘
+│ - Lag        │            └──────────────┘
+│ - Vxlan      │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│InfraIPAddress│◄────►│  InfraVLAN   │◄────►│   InfraVNI   │
+└──────────────┘      └──────────────┘      └──────────────┘
+                             │
+                             ▼
+                      ┌──────────────┐
+                      │  InfraVTEP   │
+                      └──────────────┘
+```
+
+## Reference Topology Mapping
+
+The schema models this topology from `arista-evpn-vxlan-clab`:
+
+| Physical | Infrahub Model |
+|----------|----------------|
+| spine1, spine2 | InfraDevice (role: spine) |
+| leaf1-8 | InfraDevice (role: leaf) |
+| AS 65000 | InfraAutonomousSystem (spines) |
+| AS 65001-65004 | InfraAutonomousSystem (leaf pairs) |
+| VLAN 40, 34, 78 | InfraVLAN + InfraVNI |
+| VLAN 4090, 4091 | InfraVLAN (vlan_type: mlag_peer/mlag_ibgp) |
+| leaf1+leaf2 pair | InfraMlagDomain |
+| Port-Channel999 | InfraInterfaceLag (peer-link) |
+| Port-Channel1 | InfraMlagInterface (host-facing) |
+| Ethernet1-8 | InfraInterfaceEthernet |
+| Loopback0, Loopback1 | InfraInterfaceLoopback |
+| Vxlan1 | InfraInterfaceVxlan |
+| peer groups | InfraBGPPeerGroup |
+
+## Usage
+
+### Loading the Schema
+
+```bash
+# From the fabric-orchestrator root directory
+infrahubctl schema load schemas/
+```
+
+### Validation
+
+```bash
+infrahubctl schema check schemas/
+```
+
+## Key Design Decisions
+
+1. **Generic Interface**: All interface types inherit from `InfraInterface` generic for polymorphic queries
+2. **MLAG as Domain**: MLAG is modeled as a domain containing exactly 2 devices, with per-device config
+3. **BGP Hierarchy**: BGPRouterConfig → PeerGroups → Sessions allows template-based configuration
+4. **VTEP Independence**: VTEP is separate from Device to support shared VTEP scenarios
+5. **EVPN Instance per VLAN**: Allows device-specific RD/RT while referencing common VLAN/VNI
+
+## Related Issues
+
+- Parent issue: [#41 - Define Infrahub Schema for EVPN-VXLAN Fabric](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues/41)
+- Depends on: Schema being loaded before transforms (#30, #31, #32, #33)