733 lines
8.4 KiB
Markdown
733 lines
8.4 KiB
Markdown
# BZOD Multi-User Architecture Guide
|
|
|
|
Version: v0.6.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:
|
|
|
|
```text
|
|
users
|
|
sessions
|
|
quotas
|
|
api_tokens
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
* Authentication
|
|
* Session management
|
|
* Password verification
|
|
* User status management
|
|
* Quota tracking
|
|
|
|
---
|
|
|
|
## system.db
|
|
|
|
Global platform database.
|
|
|
|
Contains:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
users/
|
|
└── 15/
|
|
├── content.db
|
|
└── analytics.db
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
### content.db
|
|
|
|
Stores:
|
|
|
|
```text
|
|
urls
|
|
pages
|
|
qr_metadata
|
|
previews
|
|
```
|
|
|
|
### analytics.db
|
|
|
|
Stores:
|
|
|
|
```text
|
|
visits
|
|
aggregates
|
|
referrers
|
|
browsers
|
|
countries
|
|
```
|
|
|
|
---
|
|
|
|
# Directory Structure
|
|
|
|
Example installation:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
/company
|
|
/about
|
|
/docs
|
|
```
|
|
|
|
If User A owns:
|
|
|
|
```text
|
|
/company
|
|
```
|
|
|
|
User B cannot create:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
global_slugs
|
|
```
|
|
|
|
Contains:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
User A
|
|
└── users/2/
|
|
|
|
User B
|
|
└── users/3/
|
|
```
|
|
|
|
User A never accesses:
|
|
|
|
```text
|
|
users/3/content.db
|
|
users/3/analytics.db
|
|
```
|
|
|
|
User B never accesses:
|
|
|
|
```text
|
|
users/2/content.db
|
|
users/2/analytics.db
|
|
```
|
|
|
|
All access is enforced by application logic.
|
|
|
|
---
|
|
|
|
# Authentication Architecture
|
|
|
|
Authentication is centralized.
|
|
|
|
Stored in:
|
|
|
|
```text
|
|
users.db
|
|
```
|
|
|
|
Tables:
|
|
|
|
```text
|
|
users
|
|
sessions
|
|
```
|
|
|
|
All dashboard sessions use:
|
|
|
|
```text
|
|
bzod_session
|
|
```
|
|
|
|
Sessions are validated against:
|
|
|
|
```text
|
|
users.db.sessions
|
|
```
|
|
|
|
---
|
|
|
|
# Session Lifecycle
|
|
|
|
Login:
|
|
|
|
```text
|
|
User Login
|
|
↓
|
|
Create Session
|
|
↓
|
|
Store in users.db
|
|
↓
|
|
Set bzod_session cookie
|
|
```
|
|
|
|
Logout:
|
|
|
|
```text
|
|
Delete session row
|
|
↓
|
|
Expire cookie
|
|
```
|
|
|
|
Disabled users immediately lose access.
|
|
|
|
---
|
|
|
|
# Quota System
|
|
|
|
Every user has quotas.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
quota_reconcile
|
|
```
|
|
|
|
Purpose:
|
|
|
|
* Detect drift
|
|
* Recount resources
|
|
* Repair counters
|
|
|
|
Example:
|
|
|
|
```text
|
|
Stored URLs = 50
|
|
Actual URLs = 47
|
|
```
|
|
|
|
Counter automatically corrected.
|
|
|
|
---
|
|
|
|
# Analytics Isolation
|
|
|
|
Each tenant stores analytics independently.
|
|
|
|
Example:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
/api/qr/{slug}.png
|
|
/api/qr/{slug}.svg
|
|
```
|
|
|
|
Slug ownership is resolved through:
|
|
|
|
```text
|
|
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:
|
|
|
|
```http
|
|
410 Gone
|
|
```
|
|
|
|
For:
|
|
|
|
```text
|
|
/slug
|
|
/p/slug
|
|
/api/qr/slug.png
|
|
/api/qr/slug.svg
|
|
```
|
|
|
|
---
|
|
|
|
# Audit Logging
|
|
|
|
All administrative actions are recorded.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
login
|
|
logout
|
|
user_create
|
|
user_delete
|
|
password_reset
|
|
quota_update
|
|
slug_transfer
|
|
backup_create
|
|
restore_execute
|
|
```
|
|
|
|
Stored in:
|
|
|
|
```text
|
|
system.db
|
|
```
|
|
|
|
---
|
|
|
|
# Backup Architecture
|
|
|
|
Supported levels:
|
|
|
|
## Full Platform Backup
|
|
|
|
Includes:
|
|
|
|
```text
|
|
users.db
|
|
system.db
|
|
all tenant databases
|
|
```
|
|
|
|
---
|
|
|
|
## User Backup
|
|
|
|
Includes:
|
|
|
|
```text
|
|
content.db
|
|
analytics.db
|
|
```
|
|
|
|
For a specific user.
|
|
|
|
---
|
|
|
|
# Disaster Recovery
|
|
|
|
Supported operations:
|
|
|
|
```bash
|
|
bzod backup
|
|
bzod restore
|
|
bzod backup-user
|
|
bzod restore-user
|
|
```
|
|
|
|
Recovery preserves:
|
|
|
|
* URLs
|
|
* Pages
|
|
* Analytics
|
|
* Users
|
|
* Slugs
|
|
* Settings
|
|
|
|
---
|
|
|
|
# Upgrade Path
|
|
|
|
BZOD automatically migrates:
|
|
|
|
```text
|
|
v0.4.x
|
|
```
|
|
|
|
to
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
users.db
|
|
```
|
|
|
|
---
|
|
|
|
## Authorization
|
|
|
|
Role-based.
|
|
|
|
```text
|
|
admin
|
|
standard
|
|
system
|
|
```
|
|
|
|
---
|
|
|
|
## CSRF Protection
|
|
|
|
All forms protected.
|
|
|
|
Invalid tokens:
|
|
|
|
```http
|
|
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:
|
|
|
|
```text
|
|
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.
|