diff --git a/src/main/java/org/juv25d/filter/IpFilter.java b/src/main/java/org/juv25d/filter/IpFilter.java
index b020a6ac..0f638622 100644
--- a/src/main/java/org/juv25d/filter/IpFilter.java
+++ b/src/main/java/org/juv25d/filter/IpFilter.java
@@ -9,6 +9,23 @@
 import java.nio.charset.StandardCharsets;
 import java.util.HashSet;
 import java.util.Set;
+
+/**
+ * Global IP-based request filter.
+ *
+ * <p>The filter runs early in the request pipeline and determines whether a request
+ * should be allowed to continue based on the client's IP address.</p>
+ *
+ * <p>Decision rules:</p>
+ * <ul>
+ *     <li>If an IP is present in the whitelist, it is allowed.</li>
+ *     <li>If an IP is present in the blacklist, it is denied.</li>
+ *     <li>If an IP is present in both lists, {@code allowByDefault} is used.</li>
+ *     <li>If an IP is present in neither list, {@code allowByDefault} is used.</li>
+ * </ul>
+ *
+ * <p>The default constructor loads configuration from {@link IpFilterConfig}.</p>
+ */
 @Global(order = 2)
 public class IpFilter implements Filter {
 
@@ -17,6 +34,14 @@ public class IpFilter implements Filter {
 
     private final boolean allowByDefault;
 
+    /**
+     * Creates an {@code IpFilter} with explicit configuration.
+     *
+     * @param whitelist IP addresses that should be allowed (may be {@code null})
+     * @param blacklist IP addresses that should be denied (may be {@code null})
+     * @param allowByDefault fallback decision when an IP is not listed, or listed in both sets
+     */
+
     public IpFilter(Set<String> whitelist, Set<String> blacklist,  boolean allowByDefault) {
         if (whitelist != null) {
             this.whitelist.addAll(whitelist);
@@ -27,6 +52,10 @@ public IpFilter(Set<String> whitelist, Set<String> blacklist,  boolean allowByDe
         this.allowByDefault = allowByDefault;
     }
 
+    /**
+     * Creates an {@code IpFilter} using configuration loaded from {@link IpFilterConfig}
+     */
+
     public IpFilter() {
         IpFilterConfig config = new IpFilterConfig();
         this.whitelist.addAll(config.whitelist());
@@ -45,8 +74,16 @@ public void doFilter(HttpRequest req, HttpResponse res, FilterChain chain) throw
         }
     }
 
+    /**
+     * Evaluates whether the given IP address should be allowed.
+     *
+     * @param ip client IP address
+     * @return {@code true} if the request is allowed, {@code false} otherwise
+     */
+
     public boolean isAllowed(String ip) {
 
+        // If an IP exists in both lists, fall back to allowByDefault
         if (whitelist.contains(ip) && blacklist.contains(ip)) return allowByDefault;
 
         if (whitelist.contains(ip)) return true;