refactor: reorganize project into src layout and update API documentation

Update project structure to use a src/ directory layout and
improve documentation across multiple files.

- Update README.md build command to use ./src
- Add directory structure documentation
- Update status endpoint to include DB health status
- Add pagination support (limit/offset) to whitelist list endpoints
- Document new query parameters with examples
- Update deployment guide to mark API token as required
- Add testing instructions
- Clarify audit log rotation in design documentation

openapi.yaml

@@ -39,17 +39,32 @@ paths:
   /status:
     get:
       summary: Health check
-      description: Simple health check endpoint.
+      description: Returns JSON with uptime, DB status, and whitelist counts.
       operationId: healthCheck
       security: []
       responses:
         '200':
           description: OK
           content:
-            text/plain:
+            application/json:
               schema:
-                type: string
-                example: "ok\n"
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: "ok"
+                  uptime:
+                    type: string
+                    example: "1h30m0s"
+                  perm_whitelist_count:
+                    type: integer
+                    example: 15
+                  temp_whitelist_count:
+                    type: integer
+                    example: 3
+                  db_ok:
+                    type: boolean
+                    example: true
 
   /api/whitelist/temp:
     post:
@@ -99,6 +114,24 @@ paths:
       summary: List temporary whitelisted IPs
       description: List all currently active temporary whitelisted IPs.
       operationId: listTempWhitelist
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 200
+          description: Number of entries to return (default 200, max 1000)
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Number of entries to skip (default 0)
       responses:
         '200':
           description: List of temporary whitelisted IPs
@@ -168,7 +201,7 @@ paths:
         '204':
           description: Created
         '400':
-          description: Bad request — entry required
+          description: Bad request — missing entry or invalid entry (must be valid IP or CIDR range)
         '401':
           description: Unauthorized — invalid API token
         '409':
@@ -186,6 +219,24 @@ paths:
       summary: List permanent whitelisted IPs
       description: List all currently active permanent whitelisted IPs.
       operationId: listPermWhitelist
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 200
+          description: Number of entries to return (default 200, max 1000)
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Number of entries to skip (default 0)
       responses:
         '200':
           description: List of permanent whitelisted IPs
@@ -233,6 +284,7 @@ paths:
         Retrieve the last 200 audit log entries (up to 1000 with `limit`).
         Each entry records a whitelist operation with its timestamp, action, affected IP,
         and the IP of the API client that performed the action.
+        The audit log is automatically rotated to a maximum of 200,000 entries.
       operationId: getLogs
       parameters:
         - name: action