nx9-url-shortener/docs/MULTI_USER.md

BZOD Multi-User Architecture Guide

Version: v0.8.0

---

Introduction

BZOD v0.5.0 introduces a complete multi-user architecture that transforms BZOD from a single-tenant URL shortener into a secure, isolated, self-hosted multi-user platform.

Each user receives logically isolated content and analytics storage while sharing a common authentication, administration, moderation, and routing infrastructure.

This document explains the architecture, database layout, ownership model, security boundaries, quotas, slug management, and administrative workflows.

---

Design Goals

The multi-user architecture was designed around the following principles:

• Strong tenant isolation
• Single binary deployment
• SQLite-only operation
• Minimal operational complexity
• No external services required
• Global slug namespace
• Centralized administration
• Disaster recovery support
• Simple backup and restore workflows

---

User Types

BZOD supports the following account types.

Administrator

Administrators can:

• Access the administrative dashboard
• Create users
• Delete users
• Reset passwords
• Manage quotas
• Transfer ownership
• Moderate content
• Manage backups
• Access health dashboards
• Access audit logs

Administrators cannot bypass database isolation.

---

Standard User

Standard users can:

• Create short URLs
• Create landing pages
• View analytics
• Generate QR codes
• Manage API tokens
• Update passwords

Standard users cannot:

• Access other user content
• Access administrative functions
• Access system settings

---

System Accounts

System accounts are reserved for internal operations.

They cannot authenticate into the dashboard.

---

Database Architecture

BZOD uses multiple SQLite databases.

users.db

Central identity store.

Contains:

users
sessions
quotas
api_tokens

Responsibilities:

• Authentication
• Session management
• Password verification
• User status management
• Quota tracking

---

system.db

Global platform database.

Contains:

global_slugs
slug_history
moderation_events
audit_events
settings
reserved_slugs

Responsibilities:

• Slug ownership
• Moderation
• Audit logging
• Global settings
• System metadata

---

Tenant Databases

Every tenant owns independent databases.

Example:

users/
└── 15/
    ├── content.db
    └── analytics.db

Responsibilities:

content.db

Stores:

urls
pages
qr_metadata
previews

analytics.db

Stores:

visits
aggregates
referrers
browsers
countries

---

Directory Structure

Example installation:

data/
├── users.db
├── system.db
│
├── admin/
│   ├── content.db
│   └── analytics.db
│
└── users/
    ├── 2/
    │   ├── content.db
    │   └── analytics.db
    │
    ├── 3/
    │   ├── content.db
    │   └── analytics.db
    │
    └── 4/
        ├── content.db
        └── analytics.db

---

Global Slug Namespace

BZOD uses a platform-wide namespace.

A slug can only exist once.

Examples:

/company
/about
/docs

If User A owns:

/company

User B cannot create:

/company

The operation is rejected.

---

Slug Registration Flow

When a URL or page is created:

1. Validate quota.
2. Validate slug.
3. Register slug in system.db.
4. Create record in tenant content.db.
5. Increment quota counters.
6. Write audit log.

If any step fails:

• Changes are rolled back.
• Partial records are removed.

---

Global Slug Table

Conceptually:

global_slugs

Contains:

slug
owner_user_id
target_type
target_id
status
created_at

Example:

slug	owner	type
docs	3	page
api	8	page
home	2	url

---

Slug Ownership Transfer

Administrators may transfer ownership.

Process:

1. Validate destination quotas.
2. Copy content.
3. Move ownership.
4. Update global slug registry.
5. Record history.
6. Write audit event.

Analytics remain preserved.

URLs remain functional.

---

Tenant Isolation

Each user owns independent databases.

Example:

User A
└── users/2/

User B
└── users/3/

User A never accesses:

users/3/content.db
users/3/analytics.db

User B never accesses:

users/2/content.db
users/2/analytics.db

All access is enforced by application logic.

---

Authentication Architecture

Authentication is centralized.

Stored in:

users.db

Tables:

users
sessions

All dashboard sessions use:

bzod_session

Sessions are validated against:

users.db.sessions

---

Session Lifecycle

Login:

User Login
    ↓
Create Session
    ↓
Store in users.db
    ↓
Set bzod_session cookie

Logout:

Delete session row
    ↓
Expire cookie

Disabled users immediately lose access.

---

Quota System

Every user has quotas.

Examples:

max_urls
max_pages
max_storage_mb
max_api_tokens

Current utilization is tracked separately.

Administrators may:

• Increase limits
• Reduce limits
• Trigger reconciliation

---

Quota Reconciliation

Background job:

quota_reconcile

Purpose:

• Detect drift
• Recount resources
• Repair counters

Example:

Stored URLs = 50
Actual URLs = 47

Counter automatically corrected.

---

Analytics Isolation

Each tenant stores analytics independently.

Example:

users/10/analytics.db

Contains only User 10 traffic.

Administrators can:

• View aggregated analytics
• Access user analytics

Users cannot view analytics from other tenants.

---

QR Code System

QR codes are generated dynamically.

Endpoints:

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

Slug ownership is resolved through:

system.db.global_slugs

No content database scan is required.

---

Moderation Architecture

Administrators can:

• Flag content
• Disable content
• Delete content
• Transfer ownership

Disabled content returns:

410 Gone

For:

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

---

Audit Logging

All administrative actions are recorded.

Examples:

login
logout
user_create
user_delete
password_reset
quota_update
slug_transfer
backup_create
restore_execute

Stored in:

system.db

---

Backup Architecture

Supported levels:

Full Platform Backup

Includes:

users.db
system.db
all tenant databases

---

User Backup

Includes:

content.db
analytics.db

For a specific user.

---

Disaster Recovery

Supported operations:

bzod backup
bzod restore
bzod backup-user
bzod restore-user

Recovery preserves:

• URLs
• Pages
• Analytics
• Users
• Slugs
• Settings

---

Upgrade Path

BZOD automatically migrates:

v0.4.x

to

v0.5.x

Migration process:

1. Create users.db.
2. Create system.db.
3. Create admin tenant.
4. Migrate content.
5. Migrate analytics.
6. Populate global_slugs.
7. Create legacy_admin.
8. Validate integrity.

No manual database migration is normally required.

---

Security Model

Security boundaries:

Authentication

Centralized.

users.db

---

Authorization

Role-based.

admin
standard
system

---

CSRF Protection

All forms protected.

Invalid tokens:

403 Forbidden

---

Session Security

• Secure session IDs
• Session invalidation
• Expiration support
• Replay protection

---

Tenant Isolation

Per-user databases.

No shared content tables.

---

Operational Recommendations

Recommended deployment:

Nginx
    ↓
BZOD
    ↓
SQLite WAL

Enable:

• HTTPS
• Daily backups
• Log rotation
• Health monitoring

---

Limitations

Current v0.5.0 limitations:

• SQLite backend only
• Single server deployment
• No clustering
• No federation
• No organization account hierarchy

These may be addressed in future releases.

---

Future Expansion

Potential v0.6.x features:

• Organization accounts
• Service accounts
• SSO integration
• Multi-node replication
• Advanced analytics dashboards
• Scheduled tasks UI

---

Summary

BZOD v0.5.0 provides:

• Centralized authentication
• Multi-user isolation
• Global slug namespace
• Per-user analytics
• Administrative moderation
• Quotas
• Audit logging
• Backup & disaster recovery
• Single-binary deployment

while remaining lightweight, SQLite-native, and operationally simple.

---

End of Document.