diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..179980657be2f6306b303ad11ca949ad8f0ef4ef
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+openapi.json
diff --git a/docs/source/api.rst b/docs/source/api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6c371d1539eaad942457b6aac075269c016a187c
--- /dev/null
+++ b/docs/source/api.rst
@@ -0,0 +1,8 @@
+API specification
+==================
+
+Generated by openapi.json file obtained from fastapi.
+Docs are also available at the /docs route of a running server.
+
+
+.. openapi:: ./openapi.json
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2bc9fa9e4a69b2b8298c912a4b17f89cd2c19e2c..d52fe2040888b5fcd07aa1b3c59ca5e1e0f15b6b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -3,26 +3,57 @@
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
+from datetime import datetime
+import json
+import os
+import sys
+
+sys.path.insert(
+ 0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+)
+
+from mapping_provider import create_app
+
+
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'GÉANT Mapping Provider'
-copyright = '2025, swd@geant.org'
+copyright = f"{datetime.now().year}, GÉANT"
author = 'swd@geant.org'
release = '0.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-extensions = []
+extensions = [
+ "sphinx_rtd_theme",
+ # "sphinx.ext.autodoc",
+ "sphinx.ext.coverage",
+ "sphinxcontrib.plantuml",
+ "sphinxcontrib.openapi",
+]
+
+# tags is injected by sphinx into conf.py
+# toggle this by running ``sphinx-build -t drawio``
+if tags.has("drawio"): # noqa F821
+ extensions.append("sphinxcontrib.drawio")
templates_path = ['_templates']
exclude_patterns = []
+plantuml = f'java -jar {os.path.expanduser("~/bin/plantuml.jar")}'
+
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
+
+
+api_schema = create_app().openapi()
+openapi_filename = os.path.join(os.path.dirname(__file__), "openapi.json")
+with open(openapi_filename, 'w') as f:
+ json.dump(api_schema, f, indent=4)
diff --git a/docs/source/diagrams.drawio b/docs/source/diagrams.drawio
new file mode 100644
index 0000000000000000000000000000000000000000..2fa3e7478218d57f4fed3e4baeeff9734c38630d
--- /dev/null
+++ b/docs/source/diagrams.drawio
@@ -0,0 +1,122 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/26.0.9 Chrome/128.0.6613.186 Electron/32.2.5 Safari/537.36" version="26.0.9">
+ <diagram name="hl-arch" id="52Qc7nEq3IphXZwXqFKS">
+ <mxGraphModel dx="1579" dy="543" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-1" value="mapping provider" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=bottom;align=right;spacingRight=5;" vertex="1" parent="1">
+ <mxGeometry x="110" y="30" width="240" height="240" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-2" value="map web server" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=bottom;align=right;spacingRight=5;" vertex="1" parent="1">
+ <mxGeometry x="-230" y="70" width="270" height="260" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-3" value="processor<div>web</div><div>service</div>" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+ <mxGeometry x="-120" y="170" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-4" value="mapping-provider" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+ <mxGeometry x="170" y="170" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-5" value="GSO" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+ <mxGeometry x="460" y="50" width="110" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-6" value="" style="endArrow=classic;startArrow=classic;html=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-3" target="qRnl4kCob0Xuz_cL3leS-4">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="110" y="260" as="sourcePoint" />
+ <mxPoint x="160" y="210" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-7" value="REST" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+ <mxGeometry x="50" y="175" width="60" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-8" value="template" style="shape=note;whiteSpace=wrap;html=1;backgroundOutline=1;darkOpacity=0.05;size=12;dashed=1;dashPattern=1 2;" vertex="1" parent="1">
+ <mxGeometry x="-100" y="270" width="80" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-9" value="" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-8" target="qRnl4kCob0Xuz_cL3leS-3">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="110" y="280" as="sourcePoint" />
+ <mxPoint x="160" y="230" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-10" value="Client" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;" vertex="1" parent="1">
+ <mxGeometry x="-400" y="105" width="30" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-11" value="map/gui" style="shape=note;whiteSpace=wrap;html=1;backgroundOutline=1;darkOpacity=0.05;size=12;" vertex="1" parent="1">
+ <mxGeometry x="-210" y="120" width="80" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-12" value="" style="endArrow=classic;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0;entryY=0;entryDx=80;entryDy=21;entryPerimeter=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-3" target="qRnl4kCob0Xuz_cL3leS-11">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="30" y="270" as="sourcePoint" />
+ <mxPoint x="80" y="220" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="-60" y="141" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-13" value="" style="endArrow=classic;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-11" target="qRnl4kCob0Xuz_cL3leS-10">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="30" y="250" as="sourcePoint" />
+ <mxPoint x="80" y="200" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-14" value="" style="endArrow=classic;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-5" target="qRnl4kCob0Xuz_cL3leS-4">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="170" y="230" as="sourcePoint" />
+ <mxPoint x="480" y="200" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="420" y="80" />
+ <mxPoint x="420" y="200" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-15" value="Inventory Provider" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+ <mxGeometry x="460" y="130" width="110" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-16" value="Dashboard" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+ <mxGeometry x="460" y="205" width="110" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-17" value="BRIAN (InfluxDB)" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+ <mxGeometry x="460" y="280" width="110" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-18" value="" style="endArrow=classic;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-17" target="qRnl4kCob0Xuz_cL3leS-4">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="470" y="90" as="sourcePoint" />
+ <mxPoint x="300" y="210" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="420" y="310" />
+ <mxPoint x="420" y="200" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-19" value="" style="endArrow=classic;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-15" target="qRnl4kCob0Xuz_cL3leS-4">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="470" y="90" as="sourcePoint" />
+ <mxPoint x="300" y="210" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="420" y="160" />
+ <mxPoint x="420" y="200" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-20" value="" style="endArrow=classic;html=1;rounded=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;exitPerimeter=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-16" target="qRnl4kCob0Xuz_cL3leS-4">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="470" y="170" as="sourcePoint" />
+ <mxPoint x="300" y="210" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="420" y="235" />
+ <mxPoint x="420" y="200" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-21" value="cache/state" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;" vertex="1" parent="1">
+ <mxGeometry x="170" y="50" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="qRnl4kCob0Xuz_cL3leS-22" value="" style="endArrow=none;html=1;rounded=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;entryPerimeter=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;strokeWidth=3;fillColor=#0050ef;strokeColor=#001DBC;" edge="1" parent="1" source="qRnl4kCob0Xuz_cL3leS-4" target="qRnl4kCob0Xuz_cL3leS-21">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="170" y="190" as="sourcePoint" />
+ <mxPoint x="220" y="140" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 83423577b815fd86dd47031ffadbc95404c94544..9c2aca8206114c6708ef485b1ba1de22cf9cf27e 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,12 +6,11 @@
GÉANT Mapping Provider documentation
====================================
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
-
.. toctree::
:maxdepth: 2
:caption: Contents:
+ api
+ planning
+
diff --git a/docs/source/planning.rst b/docs/source/planning.rst
new file mode 100644
index 0000000000000000000000000000000000000000..121a6584385785879747ade73bfc0d47b20c2a86
--- /dev/null
+++ b/docs/source/planning.rst
@@ -0,0 +1,11 @@
+Planning, Design, etc
+=====================================
+
+
+High-Level Architecture
+-------------------------
+
+.. only:: drawio
+
+ .. drawio-image:: diagrams.drawio
+ :page-name: hl-arch
diff --git a/requirements.txt b/requirements.txt
index e6911e139c290806f815a36209d8a9d869d17e5b..8cedf04a6b774601a712430bfb7494d302f9fb80 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,13 @@
fastapi
uvicorn[standard]
+
sphinx
+sphinx-rtd-theme
+sphinxcontrib-plantuml
+sphinxcontrib-drawio
+sphinxcontrib-openapi
+
ruff
mypy
tox
-pre-commit
\ No newline at end of file
+pre-commit