diff --git a/docs/diagrams/ipam_hierarchy_model.svg b/docs/diagrams/ipam_hierarchy_model.svg
new file mode 100644
index 0000000..76379d7
--- /dev/null
+++ b/docs/diagrams/ipam_hierarchy_model.svg
@@ -0,0 +1,167 @@
+<svg width="100%" viewBox="0 0 680 520" xmlns="http://www.w3.org/2000/svg">
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+    <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+  </marker>
+  <style>
+    .th { font-family: sans-serif; font-size: 14px; font-weight: 500; fill: #2C2C2A; }
+    .ts { font-family: sans-serif; font-size: 12px; fill: #5F5E5A; }
+    .arr { stroke: #888780; stroke-width: 1.5; }
+    .leader { stroke: #B4B2A9; stroke-width: 0.5; stroke-dasharray: 4 3; }
+
+    /* Gray */
+    .c-gray rect { fill: #F1EFE8; stroke: #5F5E5A; }
+    .c-gray .th { fill: #2C2C2A; }
+    .c-gray .ts { fill: #5F5E5A; }
+
+    /* Purple */
+    .c-purple rect { fill: #EEEDFE; stroke: #534AB7; }
+    .c-purple .th { fill: #3C3489; }
+    .c-purple .ts { fill: #534AB7; }
+
+    /* Teal */
+    .c-teal rect { fill: #E1F5EE; stroke: #0F6E56; }
+    .c-teal .th { fill: #085041; }
+    .c-teal .ts { fill: #0F6E56; }
+
+    /* Coral */
+    .c-coral rect { fill: #FAECE7; stroke: #993C1D; }
+    .c-coral .th { fill: #712B13; }
+    .c-coral .ts { fill: #993C1D; }
+
+    /* Amber */
+    .c-amber rect { fill: #FAEEDA; stroke: #854F0B; }
+    .c-amber .th { fill: #633806; }
+    .c-amber .ts { fill: #854F0B; }
+
+    /* Green */
+    .c-green rect { fill: #EAF3DE; stroke: #3B6D11; }
+    .c-green .th { fill: #27500A; }
+    .c-green .ts { fill: #3B6D11; }
+  </style>
+</defs>
+
+<!-- Level 0 - Supernets -->
+<g class="c-gray">
+  <rect x="40" y="20" width="280" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="180" y="42" text-anchor="middle" dominant-baseline="central">10.0.0.0/8 (infra)</text>
+</g>
+<g class="c-gray">
+  <rect x="360" y="20" width="280" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="500" y="42" text-anchor="middle" dominant-baseline="central">172.16.0.0/12 (services)</text>
+</g>
+<text class="ts" x="12" y="46">N0</text>
+
+<!-- Arrows L0 → L1 -->
+<line x1="180" y1="64" x2="180" y2="100" class="arr" marker-end="url(#arrow)"/>
+<line x1="500" y1="64" x2="500" y2="100" class="arr" marker-end="url(#arrow)"/>
+
+<!-- Level 1 - Site allocation -->
+<text class="ts" x="12" y="130">N1</text>
+<text class="ts" x="340" y="90" text-anchor="middle">SiteGenerator</text>
+<g class="c-purple">
+  <rect x="40" y="100" width="280" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="180" y="120" text-anchor="middle" dominant-baseline="central">site-paris-infra /16</text>
+  <text class="ts" x="180" y="138" text-anchor="middle" dominant-baseline="central">CoreIPPrefixPool</text>
+</g>
+<g class="c-purple">
+  <rect x="360" y="100" width="280" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="500" y="120" text-anchor="middle" dominant-baseline="central">site-paris-services /16</text>
+  <text class="ts" x="500" y="138" text-anchor="middle" dominant-baseline="central">CoreIPPrefixPool</text>
+</g>
+
+<!-- Arrows L1 → L2 (fan out from infra) -->
+<line x1="80" y1="156" x2="80" y2="210" class="arr" marker-end="url(#arrow)"/>
+<line x1="140" y1="156" x2="140" y2="210" class="arr" marker-end="url(#arrow)"/>
+<line x1="210" y1="156" x2="210" y2="210" class="arr" marker-end="url(#arrow)"/>
+<line x1="270" y1="156" x2="270" y2="210" class="arr" marker-end="url(#arrow)"/>
+
+<!-- Fan out from services -->
+<line x1="430" y1="156" x2="430" y2="210" class="arr" marker-end="url(#arrow)"/>
+<line x1="570" y1="156" x2="570" y2="210" class="arr" marker-end="url(#arrow)"/>
+
+<!-- Level 2 - Fabric pools -->
+<text class="ts" x="12" y="240">N2</text>
+<text class="ts" x="340" y="196" text-anchor="middle">FabricGenerator (ou SiteGenerator)</text>
+
+<g class="c-teal">
+  <rect x="40" y="210" width="110" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="95" y="230" text-anchor="middle" dominant-baseline="central">Loopback0</text>
+  <text class="ts" x="95" y="248" text-anchor="middle" dominant-baseline="central">/24 → /32</text>
+</g>
+<g class="c-teal">
+  <rect x="160" y="210" width="90" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="205" y="230" text-anchor="middle" dominant-baseline="central">VTEP</text>
+  <text class="ts" x="205" y="248" text-anchor="middle" dominant-baseline="central">/24 → /32</text>
+</g>
+<g class="c-teal">
+  <rect x="260" y="210" width="90" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="305" y="230" text-anchor="middle" dominant-baseline="central">P2P</text>
+  <text class="ts" x="305" y="248" text-anchor="middle" dominant-baseline="central">/24 → /31</text>
+</g>
+
+<!-- MLAG pools (smaller, below) -->
+<line x1="80" y1="266" x2="80" y2="296" class="arr" marker-end="url(#arrow)"/>
+<line x1="180" y1="266" x2="180" y2="296" class="arr" marker-end="url(#arrow)"/>
+
+<g class="c-teal">
+  <rect x="40" y="296" width="110" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="95" y="318" text-anchor="middle" dominant-baseline="central">MLAG peer /31</text>
+</g>
+<g class="c-teal">
+  <rect x="160" y="296" width="110" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="215" y="318" text-anchor="middle" dominant-baseline="central">MLAG iBGP /31</text>
+</g>
+
+<!-- Service pools -->
+<g class="c-coral">
+  <rect x="380" y="210" width="100" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="430" y="230" text-anchor="middle" dominant-baseline="central">L2 VXLAN</text>
+  <text class="ts" x="430" y="248" text-anchor="middle" dominant-baseline="central">/24 par VLAN</text>
+</g>
+<g class="c-coral">
+  <rect x="520" y="210" width="100" height="56" rx="8" stroke-width="0.5"/>
+  <text class="th" x="570" y="230" text-anchor="middle" dominant-baseline="central">L3 VXLAN</text>
+  <text class="ts" x="570" y="248" text-anchor="middle" dominant-baseline="central">/24 par VRF</text>
+</g>
+
+<!-- Level 3 - Actual allocations -->
+<text class="ts" x="12" y="400">N3</text>
+<line x1="305" y1="266" x2="305" y2="380" class="arr" marker-end="url(#arrow)"/>
+<line x1="95" y1="340" x2="95" y2="380" class="arr" marker-end="url(#arrow)"/>
+<text class="ts" x="340" y="370" text-anchor="middle">FabricGenerator</text>
+
+<g class="c-green">
+  <rect x="40" y="380" width="600" height="56" rx="12" stroke-width="0.5"/>
+  <text class="th" x="340" y="400" text-anchor="middle" dominant-baseline="central">Objets créés : devices, interfaces, IPs, BGP, MLAG, underlay links</text>
+  <text class="ts" x="340" y="418" text-anchor="middle" dominant-baseline="central">identifier déterministe → idempotent (ex: loopback0-evpnlab-leaf1)</text>
+</g>
+
+<!-- NumberPools side -->
+<g class="c-amber">
+  <rect x="380" y="296" width="100" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="430" y="318" text-anchor="middle" dominant-baseline="central">ASN pool</text>
+</g>
+<g class="c-amber">
+  <rect x="520" y="296" width="100" height="44" rx="8" stroke-width="0.5"/>
+  <text class="th" x="570" y="318" text-anchor="middle" dominant-baseline="central">VNI pool</text>
+</g>
+<line x1="430" y1="340" x2="430" y2="380" class="arr" marker-end="url(#arrow)"/>
+<line x1="570" y1="340" x2="570" y2="380" class="arr" marker-end="url(#arrow)"/>
+
+<!-- Legend -->
+<g transform="translate(40,465)">
+  <rect class="c-gray" x="0" y="0" width="14" height="14" rx="3" stroke-width="0.5"/>
+  <text class="ts" x="20" y="11">Supernets</text>
+  <rect class="c-purple" x="100" y="0" width="14" height="14" rx="3" stroke-width="0.5"/>
+  <text class="ts" x="120" y="11">Pools site</text>
+  <rect class="c-teal" x="210" y="0" width="14" height="14" rx="3" stroke-width="0.5"/>
+  <text class="ts" x="230" y="11">Pools fabric</text>
+  <rect class="c-coral" x="330" y="0" width="14" height="14" rx="3" stroke-width="0.5"/>
+  <text class="ts" x="350" y="11">Services</text>
+  <rect class="c-amber" x="430" y="0" width="14" height="14" rx="3" stroke-width="0.5"/>
+  <text class="ts" x="450" y="11">NumberPools</text>
+  <rect class="c-green" x="540" y="0" width="14" height="14" rx="3" stroke-width="0.5"/>
+  <text class="ts" x="560" y="11">Objets</text>
+</g>
+</svg>