Database Schemas & Cron Jobs

Relevant source files

The following files were used as context for generating this wiki page:

• supabase/create_structure_hashes_table.sql
• supabase/log_counts_cron.sql
• supabase/record_structure_usage.sql
• TERMS_OF_USE.md
• src/index.js
• src/HoloPrint.js

HoloPrint utilizes a Supabase backend to maintain anonymous usage statistics and track the number of resource packs generated. This system is designed with a focus on privacy, ensuring that no personally identifiable information (PII) is stored while providing the development team with essential data on project growth and unique file usage.

The database infrastructure consists of tables for storing file identifiers, functions for recording usage, and scheduled cron jobs that aggregate data for public statistics.

Sources: TERMS_OF_USE.md:12-16, src/HoloPrint.js:235-236

Database Architecture

The data flow begins at the client-side application when a user generates a resource pack. The application generates a hash of the uploaded structure files and transmits this to the Supabase instance.

This diagram illustrates the lifecycle of a structure file identifier from local generation to remote database storage and eventual statistical aggregation.

Data Privacy & Hashing

To protect user privacy, HoloPrint does not record the full structure file or its complete hash. Instead, it only records the first 4 bytes of the SHA-256 hash. This truncated hash acts as a unique identifier for the file without allowing the original content to be reconstructed.

Sources: TERMS_OF_USE.md:12-16, src/index.js:587-593

Schema Definitions

The primary storage mechanism is the structure_hashes table, which tracks unique file identifiers and their occurrence frequency.

Table: structure_hashes

Field	Type	Description
hash	text	The first 4 bytes of the file's SHA-256 hash. Primary Key.
usage_count	bigint	Total number of times this specific file has been used.
last_used	timestamp	The timestamp of the most recent pack generation for this file.

Sources: supabase/create_structure_hashes_table.sql

Server-Side Logic & Automation

Record Structure Usage Function

The record_structure_usage SQL function handles the logic for upserting data into the database. When a hash is received, the function checks if it exists:

1. If the hash exists, it increments the usage_count and updates last_used.
2. If the hash is new, it creates a new entry with a count of 1.

Sources: supabase/record_structure_usage.sql

Cron Jobs

A scheduled cron job, log_counts_cron, is used to aggregate data periodically. This job typically:

• Calculates the total number of entries in structure_hashes (representing unique structure files).
• Sums the usage_count column (representing total packs created).
• Exports or prepares these counts for the external statistics repository.

Sources: supabase/log_counts_cron.sql, README.md:58-62

Client Implementation

The interaction with the database is managed by the SupabaseLogger class within the application. The application initializes the Supabase client using a project URL and a public anonymous API key.

// src/index.js:15-16
const supabaseProjectUrl = "https://gnzyfffwvulwxbczqpgl.supabase.co";
const supabaseApiKey = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

Logging Workflow

When the "Generate Pack" process completes successfully, the application triggers the logging mechanism:

1. It gathers all structureFiles used in the pack.
2. It generates the truncated hashes.
3. It calls supabaseLogger.recordPackCreation(structureFiles).

Sources: src/index.js:582-595, src/HoloPrint.js:964-972

Summary

The HoloPrint database system provides a robust, privacy-first method for tracking project usage. By leveraging Supabase's PostgreSQL environment and cron capabilities, the project maintains transparent statistics on total packs generated and unique structures processed, while strictly adhering to the "no cookies, no PII" policy defined in the terms of use.