Skip to content

Admin Guide: Persistent Storage Strategy

Overview

For any professional SaaS or ERP system, document persistence is critical for legal compliance and audit trails. This guide outlines the strategy for moving from ephemeral local storage to persistent cloud storage for the MERP25 system.

The Problem: Ephemeral Storage

Currently, the application runs on platforms like Render or Railway which use ephemeral filesystems. * Wipe on Restart: Every time the server restarts or a new version is deployed, the local media/pdfs/ folder is deleted. * Dynamic Recreation: The system is "self-healing" and will recreate the PDF when a user clicks "Print," but it will use the current data in the database. * Audit Gap: If an invoice was edited after it was first printed, the original "snapshot" of the document is lost.

Recommendation: Phase-Based Approach

Phase 1: Growth (Best Choice NOW) - Supabase Storage

Since the project already uses Supabase for the database and authentication, Supabase Storage is the most efficient choice.

  • Pros:
    • No new accounts or billing required.
    • S3-compatible API (allows future migration without code changes).
    • High performance via Cloudflare integration.
    • 1-click setup from the Supabase dashboard.
  • Cons:
    • Slightly less feature-rich lifecycle policies than AWS (e.g., automated deep-freeze).

Phase 2: Mature SaaS Scale - AWS S3

As the user base grows and you move to a more complex infrastructure (AWS ECS/EKS), you should migrate to AWS S3.

  • Pros:
    • Functionally infinite scalability.
    • Advanced lifecycle rules (e.g., move files older than 7 years to glacier storage for cost savings).
    • Industry standard for legal data preservation.
  • Cons:
    • High complexity for IAM permissions and security policies.
    • Egress (bandwidth) costs can be higher without careful CDN tuning.

Comparison Summary

Feature Supabase Storage AWS S3
Complexity Very Low High
Performance High (Global CDN) Elite (with CloudFront)
Scalability High (Multi-TB) Unlimited
Ideal Timing < 10,000 Users > 10,000 Users

Implementation Strategy

To ensure a smooth transition, follow these rules:

  1. Use django-storages: Use the standard Django library for storage abstraction.
  2. S3-Compatible Interface: Even when using Supabase, configure it using the S3-compatible endpoint.
  3. Environment Variables: Manage your storage keys (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, ENDPOINT_URL) in your .env file. This allows you to switch from Supabase to AWS S3 in the future by changing only the credentials, not the code.

Supabase Storage: Manual Setup Guide

To enable persistent storage for your printed documents, follow these steps in the Supabase Dashboard:

  1. Create a Bucket:
    • Go to Storage in the left sidebar.
    • Click New bucket.
    • Name it merp-documents (or your preferred name).
    • Toggle Public bucket to Off for security (we will use authenticated access).
  2. Get S3 Credentials:
    • Go to Settings > Storage.
    • Locate the S3 Connection section.
    • Export the Access Key ID, Secret Access Key, and Region/Endpoint.
  3. Update Configuration:
    • Add these credentials to your .env file on Render/Railway.
    • (Future Step) I will need to install django-storages and update settings.py to use these variables.

Overwrite & Versioning Logic

How it works if you Edit and Reprint:

  1. Current Behavior (Ephemeral):
    • Since the server restarts and clears the disk, every "Reprint" generates a fresh PDF from the latest saved data.
    • This effectively "overwrites" the view the user sees.
  2. Persistent Storage Behavior:
    • If turned on, the system checks if a PDF already exists with the same filename (e.g., INV_SALES_INV-001.pdf).
    • If it exists, Django's default behavior is to serve the original file and avoid overwriting (to preserve the audit trail).
    • To see updates: If you want a reprint to reflect edits, we must either:
      • Option A (Update): Explicitly overwrite the old file (replaces history).
      • Option B (Audit Trail): Save a new version with a timestamp (e.g., INV-001_v2.pdf).

Recommendation for Audit Compliance:

For professional audits, you should never overwrite. - The system should treat the first PDF as the "Legal Record." - If you edit an Invoice, you should technically "Cancel" it and issue a new one, or the system should generate a "Revised" document version.

Conclusion

Start with Supabase Storage to keep your development fast and your billing simple. It provides the legal audit trail you need today while keeping the door open for an AWS migration tomorrow.