nx9-url-shortener/docs/ARCHITECTURE.md

BZOD Architecture Guide

Version: v0.5.3

---

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

                     ┌─────────────┐
                     │   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:

src/web/

Responsible for:

• HTTP routing
• Dashboard rendering
• Form handling
• Authentication checks
• Redirect handling
• REST API endpoints

Major modules:

admin.rs
api.rs
pages.rs
redirect.rs
qr.rs
system.rs
multi_user.rs
routes.rs

---

Authentication Layer

Location:

src/auth/

Responsible for:

• Password hashing
• Session validation
• Cookie management
• CSRF protection
• Authorization

Modules:

csrf.rs
middleware.rs
password.rs
session.rs

Authentication technologies:

• Argon2id password hashing
• Session cookies
• CSRF tokens
• RBAC checks

---

Database Layer

Location:

src/db/

Responsible for:

• Schema creation
• Migrations
• Database access
• Analytics storage
• User management

Modules:

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:

users
sessions
api_tokens
quotas

Stores:

• User accounts
• Password hashes
• Session records
• API tokens
• Quota information

---

system.db

Purpose:

Global platform metadata.

Contains:

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:

users/
└── <user_id>/
    ├── 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:

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:

system.db -> global_slugs

Purpose:

Prevent collisions across users.

Example:

User A owns:

https://bzo.in/!office

User B cannot create:

https://bzo.in/!office

This guarantees global uniqueness.

---

Request Lifecycle

URL Redirect

Request:

GET /abc123

Flow:

Browser
  ↓
Axum Router
  ↓
global_slugs lookup
  ↓
Locate owner database
  ↓
Resolve URL
  ↓
Record analytics
  ↓
302 Redirect

---

Landing Page

Request:

GET /p/demo

Flow:

Browser
  ↓
Router
  ↓
global_slugs lookup
  ↓
Tenant content.db lookup
  ↓
Render page

---

QR Generation

Request:

GET /api/qr/demo.svg

Flow:

Router
  ↓
global_slugs lookup
  ↓
Generate QR
  ↓
Return SVG

---

Analytics Pipeline

Location:

src/analytics/

Components:

events.rs
queue.rs
worker.rs
aggregate.rs
location.rs

Responsibilities:

• Visit tracking
• QR tracking
• Browser detection
• Referrer parsing
• Aggregation

---

Background Jobs

Location:

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:

src/services/

Purpose:

Business logic abstraction.

Modules:

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:

src/cli/

The CLI and Web UI share the same internal services.

Examples:

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:

users.db
system.db
admin/
users/*

Capabilities:

• Full backups
• Restore operations
• Upgrade migrations
• Disaster recovery validation

---

Testing Architecture

Location:

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

cargo build --release
./bzod serve

Systemd

bzod.service

Docker

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