🛡️ Enterprise Readiness & Security

This document addresses the security, compliance, and operational concerns of enterprise decision-makers evaluating Alesqui Intelligence for production deployment.

Target Audience: CISOs, Security Architects, Compliance Officers, IT Directors

🎯 Executive Summary

Alesqui Intelligence is designed for self-hosted deployment in security-conscious organizations. Unlike SaaS alternatives:

✅ 100% Data Sovereignty: All data (API specs, conversations, user accounts) stays in YOUR infrastructure.
✅ Zero Training Guarantee: Your data is NEVER used to train AI models.
✅ Audit-Ready: Comprehensive logging with configurable retention (default: 2 years).
✅ Compliance-Friendly: Built to support GDPR & Data Residency requirements via self-hosting.
✅ Role-Based Access Control: Granular permissions with group-based API visibility.

Deployment Model: Self-hosted only. No SaaS option for production workloads ensures complete control over your data.

🔒 Data Privacy & Sovereignty

Your Data Never Leaves Your Infrastructure

When deployed on-premise, Alesqui Intelligence operates entirely within your network boundaries:

Data Type	Storage Location	External Access
API Specifications (Swagger, Postman)	Your MongoDB	❌ Never shared
User Credentials	Your MongoDB (bcrypt-hashed)	❌ Never shared
Conversation History	Your MongoDB	❌ Never shared
Audit Logs	Your MongoDB	❌ Never shared
Application Secrets (JWT signing key)	Your environment variables	❌ Never shared

Zero Training Guarantee

We do not train AI models on your data.

✅ API specifications are processed in-memory and stored in your MongoDB only.
✅ User queries are sent to OpenAI API but not used for OpenAI model training (per OpenAI's enterprise API policy).
✅ No telemetry or analytics data is sent to Alesqui servers.
✅ No "phone home" functionality.

External Dependencies

The only external service called from the backend:

OpenAI API (api.openai.com) - For natural language processing
- Required for AI functionality.
- Uses a single system-wide API key (configured via environment variables), ensuring individual user keys are not required.
- Subject to OpenAI's data processing terms.
- Alternative: Azure OpenAI Service (can be deployed in your Azure region for enhanced isolation).
SMTP Server (REQUIRED) - For sending emails (account activation, password reset)
- REQUIRED for user account activation and password resets
- Configurable to use your own mail server
- Can be internal to your network (e.g., Exchange, Gmail workspace)
- Supported providers: Gmail, SendGrid, Mailgun, Amazon SES

Data Residency

All data is stored in your MongoDB instance:

Deploy MongoDB in your preferred geographic region.
Full compliance with data residency requirements (GDPR, CCPA, etc.).
No cross-border data transfers (except OpenAI API calls, if using OpenAI US endpoints).

🛡️ Authentication & Security

Authentication Mechanism

Alesqui Intelligence uses JWT (JSON Web Tokens) for secure, stateless authentication:

✅ Tokens signed with a configurable secret key (JWT_SECRET).
✅ Configurable expiration to control session duration.
✅ Refresh Token support, allowing sessions to remain active securely.
✅ HMAC-SHA256 signing algorithm (Industry Standard).

Deployment Configuration (Environment Variables):

The operations team must configure the following variables in the .env file:

# JWT Secret Key (Base64-encoded, minimum 256 bits / 32 bytes)
# Generate with: openssl rand -base64 32
JWT_SECRET=your-base64-encoded-secret-key-here

# Access token expiration in milliseconds
# Recommended: 900000 (15 minutes)
JWT_EXPIRATION=900000

# Refresh token expiration in milliseconds
# Recommended: 604800000 (7 days)
JWT_REFRESH_EXPIRATION=604800000

Password Security

✅ Robust Encryption: Hashing via BCrypt algorithm (default strength with automatic salting).
✅ Password Policy: Minimum 8 characters, must contain uppercase, lowercase, number, and special character.
✅ Secure Storage: Passwords are never stored in plaintext.
✅ Secure Recovery: Reset via secure, random, single-use tokens (expire in 1 hour).

Account Activation & Onboarding

To guarantee identity, new accounts require email verification:

Admin creates the user.
System generates a cryptographically secure activation token.
Email is sent with the activation link.
Link expires after 48 hours for security.
User clicks the link, sets their password, and the account becomes active.

Security Features:

✅ Activation links are single-use.
✅ Email verification prevents unauthorized account creation or bots.
✅ Tokens are cryptographically secure (32 bytes → 64 hex characters).

Role-Based Access Control (RBAC)

The system has three built-in roles to manage permissions:

Role	Capabilities	API Visibility	API Modification
SUPERADMIN	Full system access, user management, bypasses group restrictions	All APIs	All APIs
IT	API configuration, API-group assignment, diagnostics	APIs in assigned groups	APIs in assigned groups
BUSINESS	Read-only access, chat with APIs	APIs in assigned groups	❌ Cannot modify anything

Assignment Rules:

Roles are assigned by a Superadmin.
The system prevents deleting the last Superadmin user to avoid lockouts.

Group-Based API Visibility

APIs can be restricted to specific departments or groups for granular control:

✅ Public APIs: Visible to all authenticated users (no groups linked).
✅ Private APIs: Only visible to users belonging to the linked groups.
✅ SUPERADMIN: Sees everything, regardless of groups.

Example Scenario:

Group: "Finance"    → Users: [alice@company.com (IT)]
Group: "HR"         → Users: [charlie@company.com (BUSINESS)]
API: "Payroll API"  → Linked to "Finance" group
API: "Calendar API" → Public (Not linked)

alice@company.com (IT Role in Finance):
  ✅ Sees and edits "Payroll API"
  ✅ Sees "Calendar API"
  ❌ Does NOT see HR group APIs

charlie@company.com (BUSINESS Role in HR):
  ✅ Sees HR group APIs
  ✅ Sees "Calendar API"
  ❌ Cannot edit anything (Role restriction)
  ❌ Does NOT see "Payroll API"

🔐 Encryption

Data in Transit

✅ HTTPS/TLS: Application-level encryption not enforced by backend (requires reverse proxy: nginx, Apache, Traefik, cloud load balancer).
✅ Backend-to-MongoDB: Supports TLS connections (configure via mongodb+srv:// URI or connection options).
✅ Backend-to-OpenAI: HTTPS enforced by OpenAI API.
✅ Backend-to-SMTP: STARTTLS encryption enforced for email transmission.
✅ Frontend-to-Backend: HTTPS enforced via reverse proxy (same as above).

Recommendation: Use Let's Encrypt for free automated SSL certificates or your organization's internal CA for the reverse proxy.

Data at Rest

✅ MongoDB Encryption at Rest: Supported (enable in MongoDB server configuration, not application-level).
✅ Secrets in Environment Variables: Not stored in database or code.
✅ Password Hashing: BCrypt (one-way hashing with default strength, irreversible).

Secrets & Configuration Management

Critical secrets and security configurations are loaded from environment variables (.env file → application.properties):

Category	Environment Variable	Purpose
Security (JWT)	`JWT_SECRET`	Sign/verify authentication tokens (Min 256 bits)
Security (JWT)	`JWT_EXPIRATION`	Access token validity duration (ms)
Security (JWT)	`JWT_REFRESH_EXPIRATION`	Refresh token validity duration (ms)
Security (CORS)	`FRONTEND_URL`	Allowed origin for Cross-Origin Resource Sharing
External API	`OPENAI_API_KEY`	Authenticate with OpenAI API
Database	`MONGODB_URI`	Full connection string (e.g., `mongodb://...`)
Database	`MONGODB_USER` / `MONGODB_PASSWORD`	Database authentication credentials
Email (SMTP)	`SMTP_HOST` / `SMTP_PORT`	Email server connection details
Email (SMTP)	`SMTP_USER` / `SMTP_PASSWORD`	Email server authentication credentials
Email (Info)	`MAIL_FROM_EMAIL`	Sender email address (e.g., `noreply@mycompany.com`)
Email (Info)	`MAIL_FROM_NAME`	Display name for outgoing emails
Audit Logging	`AUDIT_RETENTION_DAYS`	Days to retain audit logs before auto-deletion (default: 730)
Network	`PROXY_HOST` / `PROXY_PORT`	(Optional) Corporate proxy configuration

Best Practices:

✅ JWT Rotation: Keep JWT_EXPIRATION short (e.g., 15 mins) and use JWT_REFRESH_EXPIRATION for longer sessions.

✅ Randomness: Ensure JWT_SECRET is generated using a cryptographically secure random number generator:

# Generate 256-bit (32-byte) secret
openssl rand -base64 32

# Or for 512-bit (64-byte) secret (more secure)
openssl rand -base64 64

📊 Compliance & Auditing

Audit Logging

All user and system actions are logged to MongoDB in the audit_logs collection:

Logged Events:

✅ User logins, token refreshes, and authentication failures.
✅ User CRUD operations (create, update, delete, activate, password changes, role changes).
✅ Group CRUD operations and membership changes.
✅ API CRUD operations and group assignments.
✅ All administrative actions with IP address and user agent tracking.

Audit Log Retention:

Default: 730 days (2 years).
Configurable: Set AUDIT_RETENTION_DAYS environment variable.
Automatic Cleanup: MongoDB TTL background task deletes expired logs every 60 seconds.
Minimum Recommended: 90 days for compliance purposes.

Audit Log Structure:

{
  "_id": "507f1f77bcf86cd799439011",
  "timestamp": "2026-01-22T14:30:00Z",
  "actorUsername": "admin@example.com",
  "actorUserId": "user123",
  "action": "USER_CREATED",
  "entityType": "USER",
  "entityId": "696ce3767302dd415583cff1",
  "entityName": "newuser@example.com",
  "details": "User created with roles: Business, Active: false",
  "ipAddress": "192.168.1.100",
  "userAgent": "Mozilla/5.0...",
  "result": "SUCCESS"
}

User Activity Tracking

Conversation history provides full traceability for chat interactions:

✅ Who: User ID and email (username).
✅ What: User query and AI response.
✅ When: Timestamp (ISO-8601 UTC format, e.g., 2026-01-22T14:30:00Z).
✅ Which API: API name and endpoint called (stored in step-by-step reasoning).
✅ Step-by-step reasoning: AI decision process (thoughts, actions, observations).
✅ Status tracking: SUCCESS, ERROR_PROCESSING, REPORTED_BY_USER, UNDER_REVIEW, RESOLVED.

Retention: Conversation history is retained indefinitely (manual deletion required).

User Permissions

Users: Can only view and delete their own conversation history.
IT Users: Can view conversations with issues (status: REPORTED_BY_USER, ERROR_PROCESSING, UNDER_REVIEW, RESOLVED) from users in their shared groups via the Diagnostics panel.
SUPERADMIN: Can view all conversations with issues across all users via the Diagnostics panel.

Note: IT users and SUPERADMIN access conversations exclusively through the Diagnostics panel, not through regular conversation history endpoints.

Diagnostics & Issue Reporting

Built-in feedback loop for quality assurance and API troubleshooting:

✅ Issue Reporting: Users can report issues when AI responses are incorrect (adds optional comment).
✅ Status Updates: Reports automatically change conversation status to REPORTED_BY_USER.
✅ IT Access: IT teams access reports via Diagnostics tab.
✅ Ticket Filtering:
- By status: REPORTED_BY_USER, ERROR_PROCESSING, UNDER_REVIEW, RESOLVED
- By username search (partial match)
- Group-based access control: IT users (non-SUPERADMIN) only see tickets from users in their shared groups.
✅ Ticket Management:
- Update status (e.g., mark as UNDER_REVIEW or RESOLVED)
- Add internal notes for team collaboration
- View full conversation history for context
✅ Navigation: Pagination and sorting for efficient navigation.

Use Cases:

Detect APIs with incomplete or incorrect OpenAPI/Postman documentation.
Identify authentication/authorization failures.
Monitor AI accuracy over time.
Track recurring user issues.

🚨 Security Features

Read-Only Mode

Restrict AI agent to GET requests only to prevent accidental data modifications:

✅ Configurable per API (readOnly boolean field in API configuration).
✅ AI Awareness: When enabled, the system filters the API definition provided to the LLM. The AI is not aware that modification endpoints (POST, PUT, DELETE) exist, preventing hallucinations or attempted unauthorized actions.
✅ Recommended for production environments during initial rollout.
✅ Prevents accidental data mutations by business users.

Behavior:

When readOnly = true: Only GET endpoints visible to AI agent.
When readOnly = false or not set: All endpoints available.

Input Validation

All user inputs are validated using industry-standard validation rules:

Email Validation:

Must be a valid email format.
Required field (cannot be blank).

Password Validation:

Minimum 8 characters.
At least one uppercase letter (A-Z).
At least one lowercase letter (a-z).
At least one number (0-9).
At least one special character (@$!%*?&#^()_+=-[]{}; :'",.<>/\|~ `).

File Upload Validation:

Maximum file size: 10 MB for Postman/Swagger collection files.
Supported formats: .json, .yaml, .yml.
Content size validation to prevent memory overflow.

Field Requirements:

All required fields validated as non-blank/non-null.
Size constraints enforced (e.g., roles must contain at least 1 value).

API Timeout & Retry Configuration

Prevent runaway API calls and improve resilience:

✅ Timeout: Configurable per API (default: 30 seconds).
✅ Max Retries: Configurable per API (default: 3 attempts).
✅ Exponential Backoff: Automatic retry with 500ms base delay.
✅ Smart Retry Logic: Only retries on transient failures.

Retry Conditions:

Retryable Errors:
- HTTP 5xx (server errors)
- HTTP 408 (Request Timeout)
- HTTP 429 (Too Many Requests)
- Network I/O errors (connection failures, timeouts)
Non-Retryable Errors:
- HTTP 4xx client errors (except 408 and 429)
- Invalid request format
- Authentication failures

Backoff Strategy:

Retry.backoff(maxRetries, Duration.ofMillis(500))

Base delay: 500 milliseconds.
Exponential increase on subsequent retries.
Example: 500ms → 1000ms → 2000ms.

🏗️ Architecture & Infrastructure

Deployment Model

Alesqui Intelligence consists of three components:

Backend: Spring Boot (Java 21) application
- REST API for all operations.
- Reactive programming with WebFlux (non-blocking I/O).
- Stateless (can run multiple instances behind load balancer).
Frontend: React + TypeScript (Vite)
- Single-page application (SPA).
- Served via static hosting or Node.js server.
Database: MongoDB
- NoSQL document store.
- Supports replica sets for high availability.

Stateless Backend

The backend is fully stateless, enabling horizontal scaling:

✅ No server-side sessions (JWT-based authentication).
✅ All state stored in MongoDB or client-side (JWT).
✅ Can run multiple backend instances behind load balancer.
✅ Supports rolling updates without downtime.

Database Isolation

MongoDB runs in your private network:

✅ No external database connections.
✅ Can be firewalled to accept connections only from backend.
✅ Supports MongoDB Atlas (managed) or self-hosted.

High Availability

Backend:

Deploy multiple instances behind load balancer.
Use health check endpoint: /actuator/health.
Automatic failover (stateless design).

MongoDB:

Configure MongoDB Replica Set (3+ nodes).
Automatic failover to secondary nodes.
Read preference: primaryPreferred or secondaryPreferred.

Replica Set Connection Example:

# In .env file, configure MongoDB URI with replica set
MONGODB_URI=mongodb://mongo1:27017,mongo2:27017,mongo3:27017/alesqui?replicaSet=rs0

🔄 Backup & Disaster Recovery

What to Backup

Critical components requiring backup:

✅ MongoDB database (Contains all API specifications, users, groups, and chat history).
✅ Environment variables (.env file with credentials and configuration).

Optional:

Reverse proxy configuration (nginx/Apache configs if customized).

Database Backup Strategy

Choose the backup method that fits your MongoDB deployment:

Option 1: MongoDB Atlas (If using managed MongoDB)

Automated continuous backups included.
Point-in-time recovery available.
Configure retention policies in Atlas console.
No manual intervention required.
Recommended for production environments.

Option 2: mongodump (If using self-hosted MongoDB)

# Create backup
mongodump --uri="${MONGODB_URI}" --out=/backups/$(date +%Y%m%d)

# Restore from backup
mongorestore --uri="${MONGODB_URI}" /backups/20260125

Option 3: Docker Volume Backup (If MongoDB runs in Docker with volumes)

# Backup MongoDB data volume
docker run --rm -v mongodb_data:/data -v /backups:/backup \
  alpine tar -czf /backup/mongodb_$(date +%Y%m%d).tar.gz /data

# Restore MongoDB data volume
docker run --rm -v mongodb_data:/data -v /backups:/backup \
  alpine tar -xzf /backup/mongodb_20260125.tar.gz -C /

Recommended Backup Frequency

Component	Minimum Frequency	Retention
MongoDB Database	Daily	30 days
`.env` file	After each change	Indefinite (encrypted)

Recovery Procedures

Scenario 1: Database Corruption or Data Loss

Stop the backend container
```
docker compose stop backend
```
Restore MongoDB database
Restart containers
```
docker compose start
```

Verify application health

curl https://your-backend-url/actuator/health
# Should return: {"status":"UP"}

Scenario 2: Lost Environment Variables

Restore .env file from your secure backup location.
If backup not available, reconfigure all required variables (see Configuration section for complete list).

Restart containers with new configuration:

docker compose down
docker compose up -d

⚠️ Important: If JWT_SECRET is regenerated, all users must log in again.

Scenario 3: Complete System Failure

Provision new infrastructure (VM, cloud instance, etc.).
Install Docker and Docker Compose.
Copy Docker Compose configuration and .env file to new server.
Restore MongoDB database (using one of the methods above).
Start containers:
```
docker compose up -d
```

Verify health endpoint:

curl https://your-backend-url/actuator/health

Recovery Time Estimates

RTO (Recovery Time Objective): ~15-30 minutes
- Database restore: 5-15 minutes (varies with database size).
- Container restart: 1-2 minutes.
- Health verification: 1-2 minutes.
RPO (Recovery Point Objective): Depends on your backup frequency
- Daily backups: Up to 24 hours of potential data loss.
- Hourly backups: Up to 1 hour of potential data loss.
- Continuous (Atlas): Near-zero data loss.

Testing Your Backups

⚠️ Critical: Untested backups are unreliable.

Recommended: Test backup restoration quarterly.

Test Procedure:

Set up isolated test environment (separate Docker network or server).
Restore backup to test environment.
Start containers: docker compose up -d.
Verify health check: curl http://test-server:8080/actuator/health.
Verify data integrity:
- Can you log in with a test user?
- Are API specifications visible?
- Is chat history intact?
Document any issues for improvement.

Security Best Practices

✅ Encrypt backups at rest (especially .env files containing secrets).
✅ Store backups off-server (separate storage, cloud bucket, or backup server).
✅ Restrict backup access to authorized personnel only.
✅ Secure backup scripts with appropriate permissions.
⚠️ Never commit .env files to version control.
⚠️ Test backup encryption and secure key storage.

Backup Storage Recommendations

Minimum (Local backups):

/backups/alesqui/
├── mongodb_20260125/
├── mongodb_20260124/
├── config_20260125.tar.gz
└── config_20260124.tar.gz

Recommended (Off-site backups):

Cloud storage.
Remote backup server.
Encrypted before transfer.

🌐 Network Security

Private Network Deployment

Alesqui Intelligence is designed to operate entirely within your secure network perimeter, supporting strict isolation policies:

✅ Zero Inbound Access: No public internet access required for the application components.
✅ Internal Communication: Backend, Frontend, and MongoDB communicate exclusively within your private subnet.
✅ VPN/Intranet Only: Application access can be restricted to your corporate VPN or internal network.

Connectivity Options

Choose the deployment model that fits your security posture:

Option A: Standard Isolation (OpenAI API)

Inbound: Strictly private (VPN/Intranet).
Outbound: Requires HTTPS (443) egress to api.openai.com.
Control: Can be routed through your corporate HTTP Proxy for audit and filtering.

Option B: High Security / No Internet Egress (Azure OpenAI)

Inbound: Strictly private.
Outbound: No public internet access required.
Architecture: Connects to Azure OpenAI Service within your Azure VNET.
Security: Data remains within your private network boundaries (using Azure Private Link), ensuring full compliance for highly regulated environments (Banking, Healthcare, Government).

Firewall Configuration

Recommended Firewall Rules:

Source	Destination	Port	Protocol	Purpose
Internet	Reverse Proxy	80, 443	TCP	Public HTTPS access
Reverse Proxy	Frontend (static files)	80, 443	TCP	Frontend application (production)
Reverse Proxy	Frontend (Vite dev server)	3000	TCP	Frontend application (development only)
Reverse Proxy	Backend	8080	TCP	Internal API calls
Backend	MongoDB	27017	TCP	Database access
Backend	OpenAI API	443	TCP	AI processing
Backend	SMTP Server	(configurable)	TCP	Email sending

Deny All Else: Block all other inbound/outbound traffic by default.

Note on Frontend Deployment:

Production: The frontend is built as static files (HTML, CSS, JS) and served directly by the reverse proxy (nginx/Apache). No Node.js server or port 3000 is needed.

Development: Vite runs a development server on port 3000. This should NOT be exposed in production.

Proxy Support

Backend supports HTTP proxy for outbound OpenAI API calls.

Configuration (in .env file):

# HTTP Proxy configuration (optional)
PROXY_HOST=proxy.company.com
PROXY_PORT=8080

Use Case: Organizations that route all internet traffic through a corporate proxy server.

Limitations:

Only supports HTTP proxies (no SOCKS).
No authentication support (username/password not supported).
Applies only to OpenAI API calls.
Localhost and 127.0.0.1 are automatically excluded from proxy.

⚠️ Enterprise Proxy Requirements: Many corporate environments require authenticated proxies. If your proxy requires authentication (username/password), consider these workarounds:

Use a local proxy (e.g., squid) that handles authentication and forwards to your corporate proxy.

Configure network rules to allow direct HTTPS egress to api.openai.com for the backend server.

Contact support@alesqui.com for a custom build with proxy authentication support.

SMTP Configuration

Email notifications require SMTP server access.

Configuration (in .env file):

# SMTP Configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-username
SMTP_PASSWORD=your-smtp-password

Common SMTP Ports:

587: STARTTLS (recommended).
465: SSL/TLS.
25: Unencrypted (not recommended).

Firewall Requirements:

Allow outbound TCP connection from backend to SMTP server on configured port.

CORS Configuration

Configure allowed origins for frontend access.

Configuration (in .env file):

# Primary frontend URL (required)
FRONTEND_URL=https://your-frontend-domain.com

# Additional origins (optional - for multiple frontends)
CORS_ADDITIONAL_ORIGINS=https://staging.example.com,https://dev.example.com

Default Allowed:

Value of FRONTEND_URL.
Values in CORS_ADDITIONAL_ORIGINS (if set).

Security Notes:

Credentials (cookies, auth headers) are allowed by default.
Preflight requests cached for 1 hour.
Wildcard (*) origins are not supported when credentials are enabled for security reasons (prevents CSRF attacks and credential leaking).

🔍 Monitoring & Observability

Health Check Endpoints

Spring Boot Actuator exposes monitoring endpoints:

Endpoint	Purpose	Access	Example Response
`/actuator/health`	Application and MongoDB health	Public	`{"status":"UP"}`
`/actuator/info`	Build version info	Public	`{"app":"alesquiintelligence"}`
`/actuator/metrics`	Performance metrics	Requires JWT auth	List of available metrics

Access:

/actuator/health and /actuator/info are publicly accessible (no authentication required).
/actuator/metrics requires JWT authentication.

MongoDB Health Check:

The MongoDB connection status is included in the health endpoint:

# Basic health (public - no auth required)
curl https://your-backend-url/actuator/health
# Response: {"status":"UP"}

# Detailed health (requires JWT authentication)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-backend-url/actuator/health
# Response: {"status":"UP","components":{"mongo":{"status":"UP"},...}}

Usage Examples:

# Check build info
curl https://your-backend-url/actuator/info

# List available metrics (requires JWT auth)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-backend-url/actuator/metrics

# Get specific metric (requires JWT auth)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-backend-url/actuator/metrics/jvm.memory.used

Logging

Application logs are written to console (stdout) and file (logs/alesquiintelligence.log).

Default Log Levels:

Application logs: ERROR level (production-ready).
Spring Framework: ERROR level.
MongoDB driver: ERROR level.

Log Rotation (automatic):

Maximum file size: 10 MB per log file.
Retention: 30 days of history.
Total size cap: 1 GB maximum.
Cleanup: Automatic deletion of old logs.

Log Location:

/opt/alesqui/logs/alesquiintelligence.log
/opt/alesqui/logs/alesquiintelligence-2026-01-25.log (archived)
/opt/alesqui/logs/alesquiintelligence-2026-01-24.log (archived)

Accessing Logs:

For Docker deployments:

# View real-time logs
docker compose logs -f backend

# View last 100 lines
docker compose logs --tail=100 backend

# Access log files directly
docker exec -it alesqui-backend cat /app/logs/alesquiintelligence.log

Integration with Monitoring Tools

Grafana:

The /actuator/metrics endpoint can be used as a data source in Grafana with the appropriate plugin:

Install JSON API plugin in Grafana.
Configure data source pointing to /actuator/metrics.
Use authentication with valid JWT token.
Import Spring Boot metrics dashboards.

ELK Stack (Elasticsearch, Logstash, Kibana):

Configure Filebeat to ship logs:

# filebeat.yml
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /opt/alesqui/logs/*.log
    fields:
      app: alesqui-intelligence
      
output.logstash:
  hosts: ["logstash:5044"]

Logstash parses and indexes in Elasticsearch.
Visualize in Kibana with custom dashboards.

Application Performance Monitoring (APM):

For Datadog, New Relic, Elastic APM, etc., add Java agent to Docker container:

# In your docker-compose.yml
services:
  backend:
    environment:
      JAVA_OPTS: >-
        -javaagent:/path/to/agent.jar
        -Ddd.service.name=alesqui-intelligence
        -Ddd.env=production

Available Metrics

Access metrics via /actuator/metrics (requires JWT authentication):

Common Metrics:

jvm.memory.used - JVM memory usage.
jvm.memory.max - Maximum JVM memory.
system.cpu.usage - CPU usage percentage.
http.server.requests - HTTP request statistics.
mongodb.driver.pool.size - MongoDB connection pool size.

Usage Example:

# List all available metrics
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-backend/actuator/metrics

# Get specific metric
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-backend/actuator/metrics/jvm.memory.used

Troubleshooting

Check application health:

curl https://your-backend/actuator/health

Check detailed health (with JWT auth):

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" https://your-backend/actuator/health

Common issues:

Status	Component	Cause	Solution
DOWN	mongo	MongoDB unreachable	Check `MONGODB_URI` in `.env`
DOWN	overall	Application error	Check logs: `docker compose logs backend`

Monitoring Best Practices

Set up alerts on health check endpoint failures.
Monitor disk space - Logs can grow quickly.
Configure log aggregation - Don't rely only on local files.
Regular health checks - Automated monitoring every 30-60 seconds.
Audit log reviews - Periodic security audits via administration interface.
Backup monitoring data - Especially audit logs for compliance.

🔧 Operational Control

User Management

The application uses a role-based access control system with three roles:

SUPERADMIN Powers:

✅ Full administrative control:
- Create, update, delete users.
- Assign roles (SUPERADMIN, IT, BUSINESS).
- Create and manage groups.
- Assign users to groups.
- Assign APIs to groups.
- View all APIs (including orphan APIs).
- View audit logs.
✅ API Management:
- Upload and configure APIs (Swagger/Postman).
- Set API authentication.
- View API-group associations.
- View diagnostics.
✅ Chat: Access all APIs.

IT User Powers:

✅ API Management (Full control):
- Upload Swagger/Postman collections (/api/swagger/**, /api/postman/**).
- Configure APIs (authentication, timeout, retries).
- View API-group associations (/api/admin/apis/*/groups).
- View diagnostics and issue reports (/api/diagnostics/**).
✅ Chat: Access APIs in assigned groups.
❌ Cannot manage users or create groups.

BUSINESS User Powers:

✅ Chat only: Interact with APIs in assigned groups.
✅ View conversation history.
✅ Report issues to IT.
❌ Cannot configure APIs or manage users.

Group-Based Access Control

Access to APIs is controlled through groups:

SUPERADMIN creates groups (e.g., "Finance Team", "Sales Team").
SUPERADMIN assigns users to groups.
SUPERADMIN OR IT assigns APIs to groups (/api/admin/apis/{apiId}/groups).
Users can only chat with APIs assigned to their groups.

Important:

IT users can see which groups have access to specific APIs.
IT users can assign groups to APIs (if they have proper permissions).
IT users CANNOT create/delete groups or manage users.

Example Structure:

Group: "Finance Team"
├── Users: john@company.com (BUSINESS), jane@company.com (IT)
└── APIs: PaymentAPI, InvoiceAPI, BillingAPI

Group: "Sales Team"  
├── Users: bob@company.com (BUSINESS), alice@company.com (IT)
└── APIs: CRMAPI, LeadsAPI

API Configuration Control

Per-API settings managed by IT/SUPERADMIN users through the application interface:

Configuration Options:

✅ Base URL: Environment-specific URL (e.g., https://api.company.com).
✅ Authentication:
- None
- API Key (header or query parameter)
- Bearer Token
- Basic Authentication (username/password)
- OAuth2 Client Credentials
✅ Read-Only Mode: Restrict AI agent to GET requests only.
✅ Timeout: Maximum wait time for API response (default: 30 seconds).
✅ Max Retries: Number of retry attempts on failure (default: 3).
✅ Logging: Enable/disable request/response logging.
✅ Group Assignment: Which groups can access this API.

Configuration via Web Interface:

All API configuration is done through the web application interface. IT and SUPERADMIN users can:

Upload Swagger/Postman collections.
Configure authentication credentials.
Set timeout and retry policies.
Enable read-only mode for safety.
Assign APIs to groups.

Password Management

Password Requirements:

Minimum 8 characters.
At least one uppercase letter.
At least one lowercase letter.
At least one number.
At least one special character.

Password Reset Flow (Self-Service):

Users can reset their own password if they forget it:

User clicks "Forgot password" on login page.
Enters their email address.
System sends password reset email (if account exists).
User receives email with reset link.
User clicks link and sets new password.
Reset link expires after 1 hour.
User can log in with new password.

Note: For security, the system always returns success even if the email doesn't exist, preventing email enumeration attacks.

User Activation

When SUPERADMIN creates a new user:

Admin creates user without password.
User receives activation email.
User clicks activation link.
User sets initial password.
Account becomes active.
User can log in.

Activation Link:

Valid for 48 hours.
Single-use only.
Expires after password is set.

Audit Trail

All administrative actions are automatically logged:

Logged Actions:

User creation, update, deletion.
Password changes and resets.
Role assignments.
Group membership changes.
API creation, update, deletion.
Group-API assignments.
Login attempts.
Authentication token refresh.

Audit Log Access:

Available to SUPERADMIN via Administration interface.
Filterable by user, action type, date range.
Includes IP address and timestamp.
Retention: Configurable (default 2 years).

Session Management

JWT Token Configuration (in .env file):

# JWT Secret: Use a strong, random string (minimum 256 bits)
# Generate with: openssl rand -base64 32
JWT_SECRET=your-very-secure-jwt-secret-change-in-production

# Access token expiration in milliseconds
# Default: 900000 (15 minutes)
# Recommended for production: 900000 - 1800000 (15-30 minutes)
JWT_EXPIRATION=900000

# Refresh token expiration in milliseconds
# Default: 604800000 (7 days)
# Recommended for production: 604800000 - 2592000000 (7-30 days)
JWT_REFRESH_EXPIRATION=604800000

Session Behavior:

Access tokens expire after 15 minutes (configurable).
Refresh tokens valid for 7 days (configurable).
Automatic token refresh on activity.
Users logged out on token expiration.
All sessions invalidated if JWT_SECRET changes.

✅ Security Checklist

Before deploying to production, verify these essential security settings:

Required Configuration (.env file)

JWT_SECRET - Generate a strong secret (minimum 256 bits).

# Generate 256-bit (32-byte) JWT secret
openssl rand -base64 32

# Or generate 512-bit (64-byte) secret for enhanced security
openssl rand -base64 64

Set in .env:

JWT_SECRET=your-generated-base64-secret-here

⚠️ Never use the default value in production

MongoDB Connection - Secure connection string.
```
# In .env file
MONGODB_URI=mongodb://username:password@your-mongodb-host:27017/your-database
```
- Use strong MongoDB username/password.
- If using MongoDB Atlas, connection string includes authentication.
CORS Origins - Restrict to your production domain(s).
```
# In .env file
FRONTEND_URL=https://your-production-domain.com
CORS_ADDITIONAL_ORIGINS=https://additional-domain.com
```
- ⚠️ Remove localhost addresses before production.
- Only include domains you control.

Email Configuration - SMTP credentials for notifications.

# In .env file
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USER=your-email@domain.com
SMTP_PASSWORD=your-smtp-password
MAIL_FROM_EMAIL=noreply@your-domain.com
MAIL_FROM_NAME=Your Company Name

OpenAI API Key - Your OpenAI account key.
```
OPENAI_API_KEY=sk-...
```

Application Security

Default admin password changed.
- Change the first SUPERADMIN password immediately after deployment.
- Use a strong, unique password (8+ chars, uppercase, lowercase, number, special char).
User roles assigned correctly.
- SUPERADMIN: Only system administrators.
- IT: Technical users who manage APIs.
- BUSINESS: End users (chat only).
Read-Only mode enabled for sensitive APIs (optional).
- Configure in admin interface per API.
- Restricts AI to GET requests only.
- Recommended during initial rollout.

Network & Access

HTTPS enabled (reverse proxy required).
MongoDB port not exposed to internet.
- Default port 27017 should NOT be accessible externally.
- If self-hosting MongoDB: configure firewall rules.
- If using MongoDB Atlas: already secured by default.
Application accessible only through reverse proxy.
- Backend port 8080 should NOT be directly exposed to internet.
- Only reverse proxy (nginx/etc.) should access port 8080.

File Security

.env file permissions.
- Only owner can read/write.
.env file backed up securely.
- Store encrypted copy in secure location.
- Document secret rotation procedure.

Monitoring

Health check endpoint monitored.
```
# Check application health
curl https://your-backend-domain/actuator/health
```
- Should return: {"status":"UP"}.
- Set up automated monitoring (optional: Prometheus, Datadog, etc.).
Audit logs retention configured.
```
# In .env file (default: 730 days)
AUDIT_RETENTION_DAYS=365
```
- Adjust based on your compliance requirements.

Backup

MongoDB backup configured.
- If using MongoDB Atlas: automated backups included.
- If self-hosting: configure daily backups.
- Test restore procedure at least once.
.env file backed up.
- Store securely (encrypted).
- Document where backups are stored.

🚀 Next Steps

For deployment guidance, see:

Download & Installation - Installation options and quick start.
Configuration Guide - Environment variables and secrets.
Architecture Overview - System design and components.
Distribution Repository - Docker deployment guides and examples.

📧 Enterprise Support

If you have any questions, don't hesitate to reach out.

Email: support@alesqui.com

Documentation

🛡️ Enterprise Readiness & Security

🎯 Executive Summary

🔒 Data Privacy & Sovereignty

Your Data Never Leaves Your Infrastructure

Zero Training Guarantee

External Dependencies

Data Residency

🛡️ Authentication & Security

Authentication Mechanism

Password Security

Account Activation & Onboarding

Role-Based Access Control (RBAC)

Group-Based API Visibility

🔐 Encryption

Data in Transit

Data at Rest

Secrets & Configuration Management

Best Practices:

📊 Compliance & Auditing

Audit Logging

User Activity Tracking

User Permissions

Diagnostics & Issue Reporting

🚨 Security Features

Read-Only Mode

Input Validation

API Timeout & Retry Configuration

🏗️ Architecture & Infrastructure

Deployment Model

Stateless Backend

Database Isolation

High Availability

🔄 Backup & Disaster Recovery

What to Backup

Database Backup Strategy

Recommended Backup Frequency

Recovery Procedures

Recovery Time Estimates

Testing Your Backups

Security Best Practices

Backup Storage Recommendations

🌐 Network Security

Private Network Deployment

Connectivity Options

Firewall Configuration

Proxy Support

SMTP Configuration

CORS Configuration

🔍 Monitoring & Observability

Health Check Endpoints

Logging

Integration with Monitoring Tools

Available Metrics

Troubleshooting

Monitoring Best Practices

🔧 Operational Control

User Management

Group-Based Access Control

API Configuration Control

Password Management

User Activation

Audit Trail

Session Management

✅ Security Checklist

Required Configuration (.env file)

Application Security

Network & Access

File Security

Monitoring

Backup

🚀 Next Steps

📧 Enterprise Support