# BZOD Architecture Guide Version: v0.5.1 --- # Overview BZOD is a self-hosted multi-user URL management platform written in Rust. The platform combines: * URL shortening * Landing pages * QR code generation * Analytics * User management * Moderation * Audit logging * Backup & restore * Disaster recovery into a single deployable binary powered entirely by SQLite. BZOD is designed around operational simplicity, tenant isolation, and long-term maintainability. --- # Architectural Goals The primary design goals are: 1. Self-hosted first 2. SQLite-first architecture 3. Multi-user operation 4. Tenant isolation 5. Simple deployment 6. Minimal dependencies 7. Easy backup and recovery 8. No vendor lock-in --- # High-Level Architecture ```text ┌─────────────┐ │ Browser │ └──────┬──────┘ │ ▼ ┌────────────────────┐ │ Axum Router │ └─────────┬──────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ▼ ▼ ▼ users.db system.db User Databases Users Global Slugs content.db Sessions Audit Events analytics.db Quotas Moderation API Tokens Settings ``` --- # Runtime Components ## Web Layer Location: ```text src/web/ ``` Responsible for: * HTTP routing * Dashboard rendering * Form handling * Authentication checks * Redirect handling * REST API endpoints Major modules: ```text admin.rs api.rs pages.rs redirect.rs qr.rs system.rs multi_user.rs routes.rs ``` --- ## Authentication Layer Location: ```text src/auth/ ``` Responsible for: * Password hashing * Session validation * Cookie management * CSRF protection * Authorization Modules: ```text csrf.rs middleware.rs password.rs session.rs ``` Authentication technologies: * Argon2id password hashing * Session cookies * CSRF tokens * RBAC checks --- ## Database Layer Location: ```text src/db/ ``` Responsible for: * Schema creation * Migrations * Database access * Analytics storage * User management Modules: ```text admin.rs analytics.rs audit_events.rs content.rs migrations.rs sqlite.rs users.rs ``` --- # Database Architecture BZOD uses multiple SQLite databases rather than a single monolithic database. This approach provides: * Better isolation * Easier backup * Simpler disaster recovery * Reduced risk of cross-user data leakage --- ## users.db Purpose: Central identity and account database. Contains: ```text users sessions api_tokens quotas ``` Stores: * User accounts * Password hashes * Session records * API tokens * Quota information --- ## system.db Purpose: Global platform metadata. Contains: ```text global_slugs audit_events moderation_events reserved_slugs settings slug_history ``` Stores: * Global slug ownership * Audit records * Moderation actions * Platform settings * Slug transfers --- ## Tenant Databases Each user receives isolated databases. Directory structure: ```text users/ └── / ├── content.db └── analytics.db ``` --- ### content.db Stores: * URLs * Landing pages * Metadata --- ### analytics.db Stores: * Visits * Referrers * QR scans * Browser information * Analytics aggregates --- # Multi-User Architecture BZOD v0.5.0 introduced complete tenant isolation. Each user owns: ```text content.db analytics.db ``` Users cannot directly access: * Other users' URLs * Other users' landing pages * Other users' analytics The administrator accesses all tenants through controlled administrative interfaces. --- # Global Slug Namespace All public URLs are tracked in: ```text system.db -> global_slugs ``` Purpose: Prevent collisions across users. Example: ```text User A owns: https://bzo.in/!office User B cannot create: https://bzo.in/!office ``` This guarantees global uniqueness. --- # Request Lifecycle ## URL Redirect Request: ```text GET /abc123 ``` Flow: ```text Browser ↓ Axum Router ↓ global_slugs lookup ↓ Locate owner database ↓ Resolve URL ↓ Record analytics ↓ 302 Redirect ``` --- ## Landing Page Request: ```text GET /p/demo ``` Flow: ```text Browser ↓ Router ↓ global_slugs lookup ↓ Tenant content.db lookup ↓ Render page ``` --- ## QR Generation Request: ```text GET /api/qr/demo.svg ``` Flow: ```text Router ↓ global_slugs lookup ↓ Generate QR ↓ Return SVG ``` --- # Analytics Pipeline Location: ```text src/analytics/ ``` Components: ```text events.rs queue.rs worker.rs aggregate.rs location.rs ``` Responsibilities: * Visit tracking * QR tracking * Browser detection * Referrer parsing * Aggregation --- # Background Jobs Location: ```text src/jobs/ ``` Jobs: ## aggregate.rs Analytics aggregation. ## backup.rs Automated backups. ## expiry.rs Expired content cleanup. ## retention.rs Retention policy enforcement. ## healthcheck.rs System health validation. ## quota_reconcile.rs Quota consistency verification. --- # Services Layer Location: ```text src/services/ ``` Purpose: Business logic abstraction. Modules: ```text api_keys.rs audit.rs bulk.rs landing_pages.rs qr.rs shortener.rs ``` This layer separates business rules from HTTP handlers. --- # CLI Architecture Location: ```text src/cli/ ``` The CLI and Web UI share the same internal services. Examples: ```bash bzod create-admin bzod create-user bzod backup bzod restore bzod doctor bzod migrate ``` This avoids duplicate logic between administration methods. --- # Security Model Security mechanisms: ## Authentication * Argon2id password hashes * Session cookies ## Authorization * RBAC * Administrative permission checks ## CSRF Protection * Form tokens * Request validation ## Tenant Isolation * Separate databases * Controlled access paths ## Audit Logging All critical operations are recorded. Examples: * Login attempts * User creation * Password resets * Slug transfers * Moderation actions --- # Backup & Recovery BZOD is designed for SQLite-first recovery. Backup targets: ```text users.db system.db admin/ users/* ``` Capabilities: * Full backups * Restore operations * Upgrade migrations * Disaster recovery validation --- # Testing Architecture Location: ```text tests/ ``` Coverage includes: * Authentication * Authorization * User management * Analytics * Backups * Disaster recovery * Routing * Security * Concurrency * Upgrade validation * Multi-user isolation v0.5.0 includes more than 90 automated tests. --- # Deployment Models Supported deployments: ## Native ```bash cargo build --release ./bzod serve ``` ## Systemd ```text bzod.service ``` ## Docker ```text Dockerfile docker-compose.yml ``` --- # Future Architecture Direction Planned for future releases: * Geo analytics * OpenAPI generation * SSO integration * Multi-organization support * Advanced reporting * Distributed analytics aggregation --- # Summary BZOD v0.5.0 is built around a simple principle: > Keep deployment simple, keep data local, keep users isolated, and keep recovery easy. The platform achieves this through: * Rust * Axum * SQLite * Tenant isolation * Multi-database architecture * Strong automated validation * Operational simplicity