HISTORICAL ANALYSIS

Timeline Snapshots & Replay

VIRCON's timeline system captures point-in-time snapshots of complete server state, enabling historical analysis, policy impact measurement, and rollback verification. Snapshots can be replayed to visualize past server conditions or compared to identify changes over time.

Timeline Commands

Commands for creating snapshots, replaying historical states, and comparing time periods.

,snapshot create <label> - Create timestamped server state snapshot
,snapshot list [days] - View all available snapshots
,snapshot view <snapshot_id> - Display snapshot contents
,snapshot compare <id1> <id2> - Diff two snapshots to see changes
,snapshot replay <snapshot_id> - Simulate server state at snapshot time
,snapshot export <snapshot_id> - Export snapshot as JSON for analysis

What's Captured in a Snapshot

Comprehensive server state data stored in each timeline snapshot.

Server Configuration

Feature locks, automation settings, thresholds, channel mappings

User State

Trust scores, warnings, bans, active appeals, training progress

Staff Assignments

Roles, permissions, shift schedules, availability status

Moderation Metrics

Action counts (bans/warns/kicks), average response time, case resolution rate

Incidents

Open incidents, resolution status, assigned staff, linked evidence

Snapshot Creation Workflow

Automated process for capturing and compressing complete server state.

1. Admin triggers snapshot manually with ,snapshot create or via automation.
2. System captures complete database state across all relevant tables.
3. Snapshot labeled with timestamp, creator, and optional description.
4. Data serialized to JSON and stored with compression (50-70% size reduction).
5. Snapshot indexed for quick comparison and replay operations.
6. Regular auto-snapshots created daily at 00:00 UTC (configurable interval).
7. Snapshots retained for 180 days, then archived to cold storage.

Replay Workflow

Step-by-step process for viewing historical server state in read-only mode.

1. Admin specifies snapshot ID to replay.
2. System loads snapshot data into read-only simulation environment.
3. Dashboard displays server state as it was at snapshot time.
4. User trust scores, bans, warnings visible at historical point.
5. Staff assignments and availability shown as of snapshot timestamp.
6. "Current vs Snapshot" comparison view highlights what changed since then.
7. Replay mode clearly labeled to prevent confusion with live data.
8. Exit replay to return to current live state.

Snapshot Database Schema

Database structure for storing compressed snapshots with metadata and archival info.

Field	Description
snapshot_id	Unique snapshot identifier.
snapshot_timestamp	Exact UTC time snapshot was captured.
created_by	Discord ID of admin who created snapshot.
snapshot_label	Human-readable label (e.g., 'Pre-Policy-Change').
snapshot_type	manual, auto_daily, pre_rollback, pre_migration.
data_blob	Compressed JSON of complete server state.
data_size_bytes	Size of snapshot data (for storage tracking).
compression_ratio	Compression efficiency (e.g., 0.65 = 65% of original).
archived_at	Timestamp when moved to cold storage (NULL if active).

Real-World Use Cases

Practical examples of timeline snapshots enabling historical analysis and impact measurement.

Pre-deployment safety net

Workflow: Admin creates snapshot before bot update deployment

Benefit: Can replay snapshot to verify nothing broke, or rollback if issues appear

Investigate trust score changes

Workflow: User questions why trust dropped from 80 to 45

Benefit: Replay snapshot from 30 days ago, compare to today, identify exact actions that lowered score

Policy change impact analysis

Workflow: Admin creates snapshot before/after stricter ban threshold

Benefit: Compare snapshots to quantify how many more users were banned under new policy

Historical audit for appeals

Workflow: User appeals ban claiming they were falsely flagged

Benefit: Replay snapshot to exact time of ban, verify moderation context and evidence validity

Automation Features

Scheduled snapshots, automatic compression, and intelligent pruning policies.

Auto-snapshots: daily at 00:00 UTC, weekly on Sundays, monthly on 1st of month.
Pre-deployment snapshots: automatically created before bot restarts/migrations.
Pre-rollback snapshots: created automatically before config rollback operations.
Snapshot pruning: auto-delete snapshots >180 days (except manually labeled ones).
Compression: automatic GZIP compression on snapshot creation (50-70% size reduction).

Snapshot Comparison Analysis

Capabilities for comparing two snapshots to identify changes over time.

Diff view: side-by-side comparison showing added, removed, and modified entries.
User delta: identify which users gained/lost trust, received new warnings, etc.
Config changes: highlight all configuration modifications between snapshots.
Staff turnover: see which staff joined, left, or changed roles.
Moderation trends: compare action counts (bans/warns) to identify escalation/de-escalation.

Best Practices

Guidelines for effective snapshot management and historical analysis workflows.

Create manual snapshots before major policy changes or bot updates.
Label snapshots descriptively ("Pre-Ban-Threshold-Change" not "test1").
Review auto-snapshot schedule to ensure critical periods are covered.
Use snapshot comparison to validate rollback success after config changes.
Export snapshots for external analysis if investigating complex patterns.
Don't confuse replay mode with live data - always check UI for replay indicator.

Limitations & Caveats

Important constraints and scope limitations of snapshot functionality.

Snapshots capture database state, NOT message history or Discord audit logs.
Large snapshots (>100MB) take longer to compress and replay.
Replay mode is read-only - cannot take actions from historical view.
Snapshots do NOT include VRChat API data (only VRChat IDs synced to Discord).
Comparison analysis limited to 2 snapshots at a time (no 3-way merge view).