docs: improvements

Author: evansims

docs/architecture.md

@@ -15,8 +15,9 @@ graph TB
     end
 
     subgraph "API Layer"
-        REST[REST API<br/>Port 3000]
-        GRPC[gRPC API<br/>Port 3001]
+        REST[Public REST API<br/>Port 9090]
+        GRPC[Public gRPC API<br/>Port 9091]
+        Internal[Internal REST API<br/>Port 9092]
     end
 
     subgraph "Application Layer"
@@ -99,7 +100,7 @@ graph LR
     end
 
     subgraph "Management API"
-        API[inferadb-management<br/>HTTP: 3000<br/>gRPC: 3001<br/>Storage: In-Memory]
+        API[inferadb-management<br/>Public REST: 9090<br/>Public gRPC: 9091<br/>Internal REST: 9092<br/>Storage: In-Memory]
     end
 
     subgraph "Services"

docs/audit-logs.md

@@ -186,35 +186,35 @@ Query parameters:
 **Get recent audit logs**:
 
 ```bash
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?limit=50" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?limit=50" \
   -H "Cookie: infera_session={session_id}"
 ```
 
 **Filter by event type**:
 
 ```bash
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?event_type=vault_access_granted" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?event_type=vault_access_granted" \
   -H "Cookie: infera_session={session_id}"
 ```
 
 **Filter by user**:
 
 ```bash
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?user_id=456" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?user_id=456" \
   -H "Cookie: infera_session={session_id}"
 ```
 
 **Filter by date range**:
 
 ```bash
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?start_date=2025-11-01T00:00:00Z&end_date=2025-11-18T23:59:59Z" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?start_date=2025-11-01T00:00:00Z&end_date=2025-11-18T23:59:59Z" \
   -H "Cookie: infera_session={session_id}"
 ```
 
 **Combine filters**:
 
 ```bash
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?event_type=user_login&start_date=2025-11-01T00:00:00Z&limit=100" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?event_type=user_login&start_date=2025-11-01T00:00:00Z&limit=100" \
   -H "Cookie: infera_session={session_id}"
 ```
 
@@ -259,7 +259,7 @@ Investigate suspicious login activity:
 
 ```bash
 # Find all failed login attempts in the last 24 hours
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?event_type=user_login&start_date=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ)" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?event_type=user_login&start_date=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ)" \
   -H "Cookie: infera_session={session_id}"
 ```
 
@@ -269,7 +269,7 @@ Review vault access grants:
 
 ```bash
 # List all vault access grants this month
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?event_type=vault_access_granted&start_date=2025-11-01T00:00:00Z" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?event_type=vault_access_granted&start_date=2025-11-01T00:00:00Z" \
   -H "Cookie: infera_session={session_id}"
 ```
 
@@ -279,7 +279,7 @@ Track a specific user's activity:
 
 ```bash
 # Get all actions by user 456
-curl -X GET "http://localhost:3000/v1/organizations/{org}/audit-logs?user_id=456&limit=100" \
+curl -X GET "http://localhost:9090/v1/organizations/{org}/audit-logs?user_id=456&limit=100" \
   -H "Cookie: infera_session={session_id}"
 ```
 
@@ -299,7 +299,7 @@ def export_audit_logs(org_id: str, start_date: datetime, end_date: datetime):
 
     while True:
         response = requests.get(
-            f"http://localhost:3000/v1/organizations/{org_id}/audit-logs",
+            f"http://localhost:9090/v1/organizations/{org_id}/audit-logs",
             params={
                 "limit": limit,
                 "offset": offset,
@@ -354,7 +354,7 @@ def monitor_security_events(org_id: str, poll_interval: int = 60):
     while True:
         for event_type in critical_events:
             response = requests.get(
-                f"http://localhost:3000/v1/organizations/{org_id}/audit-logs",
+                f"http://localhost:9090/v1/organizations/{org_id}/audit-logs",
                 params={
                     "event_type": event_type,
                     "start_date": last_check.isoformat(),

docs/authentication.md

@@ -1253,12 +1253,12 @@ Response:
 
 The Management API runs **two separate HTTP servers** for security isolation:
 
-- **Public Server** (port 3000): User-facing API with session authentication and permission checks
-- **Internal Server** (port 9091): Server-to-server API with JWT authentication for privileged operations
+- **Public Server** (port 9090): User-facing API with session authentication and permission checks
+- **Internal Server** (port 9092): Server-to-server API with JWT authentication for privileged operations
 
 This architecture ensures that privileged endpoints are only accessible via the internal network and cannot be reached from the public internet.
 
-#### Public Endpoints (Port 3000)
+#### Public Endpoints (Port 9090)
 
 User-facing endpoints with session authentication and permission enforcement:
 
@@ -1268,9 +1268,9 @@ User-facing endpoints with session authentication and permission enforcement:
 **User Request Example**:
 
 ```bash
-# Request to public server (port 3000)
-curl -X GET http://localhost:3000/v1/organizations/123456789 \
-  -H "Cookie: session_id=987654321"
+# Request to public server (port 9090)
+curl -X GET http://localhost:9090/v1/organizations/123456789 \
+  -H "Cookie: infera_session=sess_abc123..."
 ```
 
 **Authorization**:
@@ -1279,7 +1279,7 @@ curl -X GET http://localhost:3000/v1/organizations/123456789 \
 - User must be a member of the organization
 - User must have appropriate permissions (checked via middleware)
 
-#### Internal Endpoints (Port 9091)
+#### Internal Endpoints (Port 9092)
 
 Privileged server-to-server endpoints with JWT authentication, **no permission checks**:
 
@@ -1289,8 +1289,8 @@ Privileged server-to-server endpoints with JWT authentication, **no permission c
 **Server Request Example**:
 
 ```bash
-# Request to internal server (port 9091)
-curl -X GET http://localhost:9091/internal/organizations/123456789 \
+# Request to internal server (port 9092)
+curl -X GET http://localhost:9092/internal/organizations/123456789 \
   -H "Authorization: Bearer eyJhbGc...(server JWT)"
 ```
 
@@ -1303,7 +1303,7 @@ curl -X GET http://localhost:9091/internal/organizations/123456789 \
 
 #### Key Differences
 
-| Aspect             | Public Server (3000)       | Internal Server (9091)        |
+| Aspect             | Public Server (9090)       | Internal Server (9092)        |
 | ------------------ | -------------------------- | ----------------------------- |
 | **Authentication** | Session cookies            | Server JWTs (EdDSA)           |
 | **Authorization**  | Permission checks required | No permission checks          |

docs/deployment.md

@@ -14,8 +14,9 @@ This guide provides instructions for deploying the InferaDB Management API in pr
   - Storage: Minimal (logs only, data in RAM)
 
 - **Network**:
-  - HTTP port (default: 3000) - Management REST API
-  - gRPC port (default: 3001) - Internal gRPC server
+  - Public REST port (default: 9090) - Client-facing REST API
+  - Public gRPC port (default: 9091) - Client-facing gRPC server
+  - Internal REST port (default: 9092) - Server-to-server communication (JWKS, etc.)
   - Outbound access to:
     - InferaDB policy engine (gRPC)
     - SMTP server (for email)
@@ -98,30 +99,32 @@ email:
 export SMTP_PASSWORD="your-password"
 ```
 
-#### Server API Endpoint
+#### Policy Service (InferaDB Server) Endpoint
 
 ```yaml
-server_api:
-  grpc_endpoint: "https://policy-engine.example.com:8080"
+policy_service:
+  service_url: "https://policy-engine.example.com"
+  grpc_port: 8081
+  internal_port: 8082
   tls_enabled: true
 ```
 
-**Action**: Point to your InferaDB policy engine gRPC endpoint. Enable TLS in production.
+**Action**: Point to your InferaDB policy engine. The `service_url` is the base URL, and ports specify gRPC (for policy operations) and internal REST (for webhooks). Enable TLS in production.
 
 ### 3. Environment-Specific Overrides
 
 Use environment variables to override sensitive configuration:
 
 ```bash
-# Key encryption secret
-export KEY_ENCRYPTION_SECRET="your-32-byte-secret"
+# Key encryption secret (use INFERADB_MGMT__ prefix for all config overrides)
+export INFERADB_MGMT__AUTH__KEY_ENCRYPTION_SECRET="your-32-byte-secret"
 
 # SMTP credentials
-export SMTP_USERNAME="smtp-user"
-export SMTP_PASSWORD="smtp-pass"
+export INFERADB_MGMT__EMAIL__SMTP_USERNAME="smtp-user"
+export INFERADB_MGMT__EMAIL__SMTP_PASSWORD="smtp-pass"
 
 # Worker ID (for multi-instance deployments)
-export WORKER_ID="0"
+export INFERADB_MGMT__ID_GENERATION__WORKER_ID="0"
 ```
 
 ## Single-Instance Deployment
@@ -158,7 +161,13 @@ spec:
   ports:
     - name: http
       port: 80
-      targetPort: 3000
+      targetPort: 9090
+    - name: grpc
+      port: 9091
+      targetPort: 9091
+    - name: internal
+      port: 9092
+      targetPort: 9092
   type: LoadBalancer
 
 ---