diff --git a/README.md b/README.md
index 1560c04..89e2f0e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,34 @@
 # ip-svc
+Go service that will show user IPv4 and IPv6 addresses
 
+![IP page screenshot](./docs/ip-svc-screenshot.png)
+
+```mermaid
+flowchart TD
+    A[net/http]
+    A --> B{get request RemoteAddress}
+    B --> C{is ipv6?}
+    C -->|yes| D[render template with IPv6 address]
+    C -->|no| E[render template with IPv4 address]
+    D --> F{request ipv4 address from ip4.mziesel.nl}
+    F -->|success| G[add address to page]
+    E --> H{request ipv6 address from ip6.mziesel.nl}
+    H -->|success| G[add address to page]
+```
+
+works by creating four dns records
+
+```
+A		ip.mziesel.nl		<server ipv4>
+AAAA	ip.mziesel.nl		<server ipv6>
+A		ip4.mziesel.nl		<server ipv4>
+AAAA	ip6.mziesel.nl		<server ipv6>
+```
+
+#### endpoints
+
+| Endpoint | Description      |
+| -------- | -----------      |
+| `/`      | HTML page        |
+| `/raw`   | Just the raw IP  |
+| `/json`  | Data in json     |
diff --git a/docs/ip-svc-screenshot.png b/docs/ip-svc-screenshot.png
new file mode 100644
index 0000000..a685588
Binary files /dev/null and b/docs/ip-svc-screenshot.png differ