CDN storage lifecycle: init on startup, route-based sharding, cleanup empty directories

[devin-ai-integration]

Scope

• Move filesystem storage directory creation to startup lifecycle
• Split stored files into per-route subfolders to avoid contention and improve organization
• Delete parent directories if they become empty after file removal

Acceptance criteria

• Storage location is established at service startup, not import-time
• Clear directory structure per cloned route (avatars/, role-icons/, guild-profiles/, ...)
• Deleting a file removes empty parent dirs safely

Code references

• Storage init: https://github.com/erkinalp/anticensor/blob/master/src/cdn/util/Storage.ts#L41
• Folder layout suggestion: https://github.com/erkinalp/anticensor/blob/master/src/cdn/util/FileStorage.ts#L26
• Delete cleanup: https://github.com/erkinalp/anticensor/blob/master/src/cdn/util/FileStorage.ts#L65-L68

[traycerai]

Plan

Observations

The CDN storage system currently initializes filesystem directories at import-time rather than during service startup, lacks systematic route-based directory organization, and doesn't clean up empty parent directories after file deletion. The codebase already has good foundations with route-specific path patterns like avatars/, role-icons/, and guilds/ but needs to be formalized into a proper lifecycle management system.

Approach

I'll refactor the storage initialization to move from import-time to startup lifecycle, implement a systematic route-based directory structure with predefined route types, and enhance the delete operation to safely remove empty parent directories. This approach maintains backward compatibility while improving organization and reducing filesystem clutter.

Reasoning

I explored the CDN module structure and found the current storage implementation in src/cdn/util/Storage.ts where directory creation happens at import-time. I examined the route files to understand current path patterns and identified that FileStorage.delete() lacks parent directory cleanup. I also reviewed the CDN server startup flow to understand where to integrate the new initialization logic.

Proposed File Changes

📄 src/cdn/util/Storage.ts ^(MODIFY) 🔗

References

• 📄 src/cdn/Server.ts ^(MODIFY)

Remove the import-time directory creation logic (lines 34-44) and replace with a deferred initialization approach. Add a new initializeStorage() function that will be called during startup lifecycle. Modify the storage variable to be initialized lazily. Update the storage provider selection logic to prepare the storage instance without immediately creating directories. Add proper error handling for storage initialization failures.

📄 src/cdn/util/FileStorage.ts ^(MODIFY) 🔗

References

• 📄 src/cdn/util/Storage.ts ^(MODIFY)

Add route-based directory structure support by implementing a getRouteBasedPath() function that maps file paths to organized subdirectories. Update the set() method to use route-based paths and ensure proper directory creation. Enhance the delete() method to implement safe parent directory cleanup - after deleting a file, check if parent directories are empty and remove them recursively up to the route base directory. Add a createRouteDirectories() method to pre-create standard route directories during initialization. Remove the TODO comment on line 26 as this will be implemented.

📄 src/cdn/Server.ts ^(MODIFY) 🔗

References

• 📄 src/cdn/util/Storage.ts ^(MODIFY)

Add storage initialization to the start() method after database and config initialization but before route registration. Import the new initializeStorage() function from src/cdn/util/Storage.ts and call it during startup. Add proper error handling and logging for storage initialization. This ensures storage directories are created at service startup rather than import-time, following the lifecycle requirement.

Diagram

sequenceDiagram
    participant Start as start.ts
    participant Server as CDNServer
    participant Storage as Storage.ts
    participant FileStorage as FileStorage.ts
    participant FS as File System

    Start->>Server: new CDNServer()
    Start->>Server: server.start()
    
    Server->>Server: initDatabase()
    Server->>Server: Config.init()
    Server->>Storage: initializeStorage()
    
    Storage->>Storage: Determine storage provider
    Storage->>FileStorage: createRouteDirectories()
    FileStorage->>FS: Create route-based directories
    FS-->>FileStorage: Directories created
    FileStorage-->>Storage: Initialization complete
    Storage-->>Server: Storage ready
    
    Server->>Server: registerRoutes()
    
    Note over Server,FS: Later during file operations...
    
    Server->>FileStorage: delete(path)
    FileStorage->>FS: Remove file
    FileStorage->>FileStorage: Check parent directories
    FileStorage->>FS: Remove empty parent dirs
    FS-->>FileStorage: Cleanup complete

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The CDN storage system currently initializes filesystem directories at import-time rather than during service startup, lacks systematic route-based directory organization, and doesn't clean up empty parent directories after file deletion. The codebase already has good foundations with route-specific path patterns like `avatars/`, `role-icons/`, and `guilds/` but needs to be formalized into a proper lifecycle management system.

### Approach

I'll refactor the storage initialization to move from import-time to startup lifecycle, implement a systematic route-based directory structure with predefined route types, and enhance the delete operation to safely remove empty parent directories. This approach maintains backward compatibility while improving organization and reducing filesystem clutter.

### Reasoning

I explored the CDN module structure and found the current storage implementation in `src/cdn/util/Storage.ts` where directory creation happens at import-time. I examined the route files to understand current path patterns and identified that FileStorage.delete() lacks parent directory cleanup. I also reviewed the CDN server startup flow to understand where to integrate the new initialization logic.

## Mermaid Diagram

sequenceDiagram
    participant Start as start.ts
    participant Server as CDNServer
    participant Storage as Storage.ts
    participant FileStorage as FileStorage.ts
    participant FS as File System

    Start->>Server: new CDNServer()
    Start->>Server: server.start()
    
    Server->>Server: initDatabase()
    Server->>Server: Config.init()
    Server->>Storage: initializeStorage()
    
    Storage->>Storage: Determine storage provider
    Storage->>FileStorage: createRouteDirectories()
    FileStorage->>FS: Create route-based directories
    FS-->>FileStorage: Directories created
    FileStorage-->>Storage: Initialization complete
    Storage-->>Server: Storage ready
    
    Server->>Server: registerRoutes()
    
    Note over Server,FS: Later during file operations...
    
    Server->>FileStorage: delete(path)
    FileStorage->>FS: Remove file
    FileStorage->>FileStorage: Check parent directories
    FileStorage->>FS: Remove empty parent dirs
    FS-->>FileStorage: Cleanup complete

## Proposed File Changes

### src/cdn/util/Storage.ts(MODIFY)

References: 

- src/cdn/Server.ts(MODIFY)

Remove the import-time directory creation logic (lines 34-44) and replace with a deferred initialization approach. Add a new `initializeStorage()` function that will be called during startup lifecycle. Modify the storage variable to be initialized lazily. Update the storage provider selection logic to prepare the storage instance without immediately creating directories. Add proper error handling for storage initialization failures.

### src/cdn/util/FileStorage.ts(MODIFY)

References: 

- src/cdn/util/Storage.ts(MODIFY)

Add route-based directory structure support by implementing a `getRouteBasedPath()` function that maps file paths to organized subdirectories. Update the `set()` method to use route-based paths and ensure proper directory creation. Enhance the `delete()` method to implement safe parent directory cleanup - after deleting a file, check if parent directories are empty and remove them recursively up to the route base directory. Add a `createRouteDirectories()` method to pre-create standard route directories during initialization. Remove the TODO comment on line 26 as this will be implemented.

### src/cdn/Server.ts(MODIFY)

References: 

- src/cdn/util/Storage.ts(MODIFY)

Add storage initialization to the `start()` method after database and config initialization but before route registration. Import the new `initializeStorage()` function from `src/cdn/util/Storage.ts` and call it during startup. Add proper error handling and logging for storage initialization. This ensures storage directories are created at service startup rather than import-time, following the lifecycle requirement.

---

Developer Humor

🗂️ Why did the CDN files get organized?
Because they were tired of living in a flat world!
Now they have proper routes to their destinations,
And empty folders don't overstay their welcome! 📁✨
Storage lifecycle: from chaos to harmony! 🎵

---

Execution Information

Branch: master
Commit: 0442d70

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.