ai-agents-workspace-starter: Skill for Claude Code

Skill: Storage Patterns

File management and storage patterns. Read when working with uploads, file generation, documents.

---

Architecture

Storage is a bind mount from host to container:

• Host: ${STORAGE_PATH:-./storage}/ (from .env)
• Container: /app/storage/

Directory Hierarchy

storage/
  {tenant_id}/                  # per-tenant/user isolation
    uploads/                    # files uploaded by user
      {YYYY-MM}/                # date-based partitioning
        {uuid}.{ext}            # unique name (never the original!)
    generated/                  # system-generated files
      reports/
        {uuid}.pdf
      exports/
        {uuid}.json
    temp/                       # temporary files (cleaned by cron/task)
      {uuid}.{ext}

Rules

1. Never use the original filename as the disk name -> UUID + extension
2. Original name stored in database (column original_filename)
3. Date partitioning (YYYY-MM/) prevents millions of files in a single directory
4. Isolation per tenant/user -> {tenant_id}/ at the top level
5. Temp cleaned automatically after 24h (Huey periodic task)
6. STORAGE_PATH configurable via .env -> easy migration to S3/GCS in the future

Database Model (StoredFile)

• Table: stored_files
• Columns: id (PK), uuid (unique, indexed), tenant_id (FK to users, indexed), original_filename (500), storage_path (1000, relative to STORAGE_PATH), mime_type (255), size_bytes (BigInteger), category (50: uploads/generated/temp), created_at

Port (interface)

• ABC class FileStorage with async methods:
  • save(tenant_id, category, filename, content) -> str (returns UUID)
  • get_path(tenant_id, uuid) -> Path | None
  • delete(tenant_id, uuid) -> bool

Adapter (local implementation)

• Class LocalFileStorage(FileStorage) with base_path: str = "/app/storage"
• save(): generates UUID, extracts extension from original filename, creates date-partitioned path {tenant_id}/{category}/{YYYY-MM}/{uuid}.{ext}, writes bytes
• Parent dirs created with mkdir(parents=True, exist_ok=True)