nx9-url-shortener/docs/ADMIN_GUIDE.md

BZOD Administrator Guide

Version: v0.5.3

---

Introduction

This guide is intended for BZOD administrators responsible for operating, maintaining, and managing a BZOD instance.

It covers:

• Administrator authentication
• User management
• Quotas
• Sessions
• Moderation
• Slug ownership
• Analytics
• Audit logs
• Backup and recovery
• Health monitoring
• Operational best practices

---

Administrator Role

Administrators have full platform control.

Administrative capabilities include:

• Create users
• Modify users
• Disable users
• Delete users
• Reset passwords
• Manage quotas
• Review analytics
• Moderate content
• Transfer slug ownership
• Manage backups
• Review audit logs
• Monitor system health

Administrators cannot bypass audit logging.

All administrative actions are recorded.

---

Login

Administrative login is available at:

/login

Successful login redirects to:

/admin

Authentication uses:

users.db

Sessions are stored in:

users.db.sessions

Cookie name:

bzod_session

---

Administrative Dashboard

Route:

/admin

The dashboard provides a high-level overview of platform activity.

Metrics include:

• Total Users
• Active Users
• Total URLs
• Total Landing Pages
• Active Sessions
• API Tokens
• Storage Usage
• Moderation Events
• Recent Audit Events

Quick actions include:

• Create User
• View Sessions
• View Audit Logs
• Create Backup
• Review Health Status

---

User Management

Users List

Route:

/admin/users

Displays:

• User ID
• Username
• Status
• Account Type
• Creation Date

Available actions:

• View
• Edit
• Disable
• Enable
• Reset Password
• Delete

---

Create User

Route:

/admin/users/new

Fields:

• Username
• Password
• Account Type
• Quota Limits

Supported account types:

admin
standard

Reserved usernames cannot be used.

Examples:

admin
legacy_admin
system
root
administrator

---

User Detail Page

Route:

/admin/users/{id}

Displays:

Profile

• User ID
• Username
• Status
• Account Type
• Created Date

Usage Statistics

• URL Count
• Landing Page Count
• Visit Count
• Storage Usage
• API Token Count
• Active Sessions

Quotas

• Maximum URLs
• Maximum Pages
• Maximum Storage
• Maximum Tokens

Sessions

List of active sessions.

API Tokens

List of active tokens.

---

Edit User

Route:

/admin/users/{id}/edit

Administrators may:

• Change status
• Change account type
• Modify quotas

---

Reset Password

Route:

/admin/users/{id}/password

Creates a new password hash and invalidates existing sessions.

Audit event generated:

password_reset

---

Disable User

Route:

/admin/users/{id}/disable

Effects:

• User login disabled
• Existing sessions revoked
• API access denied

Audit event generated:

user_disabled

---

Enable User

Route:

/admin/users/{id}/enable

Restores account access.

Audit event generated:

user_enabled

---

Delete User

Route:

/admin/users/{id}/delete

Deletion performs:

1. Session revocation
2. API token removal
3. Content removal
4. Analytics removal
5. Slug release
6. User database deletion

Audit event generated:

user_deleted

---

Session Management

Route:

/admin/sessions

Displays all active platform sessions.

Information displayed:

• User ID
• Username
• Session Identifier
• Created Time
• Expiry Time
• IP Address
• User Agent

---

Revoke Session

Individual sessions can be revoked.

Effects:

• Session removed immediately
• User forced to reauthenticate

---

Revoke All Sessions

Administrators may invalidate all active sessions.

Useful after:

• Password compromise
• Security incidents
• Large configuration changes

---

Quota Management

Route:

/admin/quotas

Quotas limit user resource consumption.

Available limits:

max_urls
max_pages
max_storage_mb
max_api_tokens

---

Quota Reconciliation

Administrators can execute:

quota_reconcile

Purpose:

• Detect counter drift
• Recount resources
• Repair quota usage

Common causes:

• Manual database modifications
• Failed migrations
• Interrupted operations

---

Moderation

Route:

/admin/moderation

Moderation allows administrators to manage abuse and policy violations.

---

Flag Content

Marks content for review.

Audit event:

content_flagged

---

Disable Content

Disabled content returns:

410 Gone

Affected endpoints:

/{slug}
/p/{slug}
/api/qr/{slug}.png
/api/qr/{slug}.svg

Audit event:

content_disabled

---

Enable Content

Restores functionality.

Audit event:

content_enabled

---

Delete Content

Permanently removes content.

Audit event:

content_deleted

---

Slug Management

Route:

/admin/slugs

Displays platform-wide slug ownership.

Information includes:

• Slug
• Owner
• Type
• Status
• Creation Date

---

Slug Types

Supported types:

url
page

---

Transfer Ownership

Administrators may transfer ownership.

Workflow:

1. Validate recipient quota.
2. Copy content.
3. Update ownership.
4. Update global slug registry.
5. Write audit record.

Audit event:

slug_transfer

Analytics are preserved.

---

Analytics

Administrators can access analytics for any managed resource.

---

URL Analytics

Route:

/admin/analytics/url/{id}

Displays:

• Total Visits
• Unique Visitors
• Referrers
• Browsers
• Countries
• Visit Timeline

---

Page Analytics

Route:

/admin/analytics/page/{id}

Displays identical metrics for landing pages.

---

User Analytics

Administrators can review user-level analytics.

Route:

/analytics

Includes:

• Top Links
• Top Pages
• Referrers
• Browsers
• Countries
• Recent Visits

---

Audit Logs

Route:

/admin/audit

All administrative actions are recorded.

Searchable event types include:

login
logout
failed_login
user_created
user_deleted
user_disabled
user_enabled
password_reset
quota_updated
slug_transfer
content_flagged
content_disabled
backup_created
restore_executed

Audit logs should be reviewed regularly.

---

Backup Management

Route:

/admin/backups

Provides web-based backup operations.

---

Create Backup

Creates a platform snapshot.

Includes:

users.db
system.db
tenant databases

Audit event:

backup_created

---

Download Backup

Allows local storage of backup archives.

Recommended frequency:

Daily

---

Restore Backup

Restores a selected backup archive.

Audit event:

restore_executed

Always test restores before production use.

---

Delete Backup

Removes backup archives from storage.

---

Health Dashboard

Route:

/admin/health

Provides operational diagnostics.

Displays:

• Database Status
• WAL Status
• Storage Utilization
• Backup Status
• Health Check Results
• Quota Reconciliation Results

---

Database Health

Checks:

users.db
system.db
content.db
analytics.db

Reports:

healthy
warning
error

---

Storage Monitoring

Shows:

• Total Storage
• Free Storage
• Database Sizes
• Backup Sizes

---

Security Administration

Password Policies

Recommendations:

• Minimum 12 characters
• Unique passwords
• Password manager usage

---

Session Management

Recommended actions:

• Revoke old sessions
• Review active sessions
• Remove inactive users

---

CSRF Protection

All administrative forms require valid CSRF tokens.

Invalid requests return:

403 Forbidden

---

Audit Reviews

Recommended review schedule:

Event Type	Frequency
Failed Logins	Daily
User Creation	Weekly
Slug Transfers	Weekly
Backup Events	Daily
Moderation Events	Weekly

---

Disaster Recovery

Recommended workflow:

1. Stop BZOD.
2. Create backup copy.
3. Restore archive.
4. Verify databases.
5. Run integrity checks.
6. Restart service.

---

Operational Best Practices

Recommended:

• Enable HTTPS
• Run daily backups
• Monitor disk usage
• Review audit logs
• Keep binaries updated
• Test restore procedures regularly

Avoid:

• Manual database modifications
• Direct deletion of tenant databases
• Disabling audit logging

---

Troubleshooting

User Cannot Login

Check:

• User status
• Session validity
• Password reset history

---

Slug Already Exists

Check:

/admin/slugs

for ownership conflicts.

---

Analytics Missing

Verify:

• Analytics worker running
• Analytics database present
• Event queue processing

---

Backup Failure

Check:

• Free disk space
• File permissions
• Backup destination path

---

Summary

The BZOD administration system provides:

• Centralized user management
• Quotas and session controls
• Moderation and slug ownership management
• Analytics visibility
• Audit logging
• Backup and restore capabilities
• Health monitoring

while maintaining strong tenant isolation and a SQLite-native operational model.

---

End of Document.