@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/docs/file-management/FILE_UPLOAD_FLOW.md

@@ -0,0 +1,300 @@
+# File Upload Flow Diagram
+
+## Current Implementation (Enhanced)
+
+```mermaid
+graph TB
+    subgraph Plugin
+        A[forloopFileUpload<br/>Tool] --> B[API Client<br/>createPresignedUpload]
+        B --> C[Server /files/presign]
+        C --> D[Generate Upload URL<br/>with folder path]
+        D --> E[S3 Presigned URL]
+        E --> F[Upload to S3]
+        F --> G[API Client<br/>completeUpload]
+        G --> H[Server /files/complete]
+        H --> I[Create File Record<br/>with folder & storyId]
+        I --> J[(Database<br/>canvasFile)]
+    end
+    
+    subgraph Parameters
+        A1[filePath] --> A
+        A2[sprintId] --> A
+        A3[description?] --> A
+        A4[folder?] --> A
+        A5[storyId?] --> A
+    end
+    
+    subgraph S3 Structure
+        S1[sprint/14/] --> S1A[myfile.md]
+        S1 --> S1B[project/]
+        S1B --> S1B1[plans/myfile.md]
+        S1B --> S1B2[knowledge/myfile.md]
+        S1B --> S1B3[tasks/myfile.md]
+    end
+
+    style A4 fill:#90EE90
+    style A5 fill:#90EE90
+    style S1B fill:#FFE4B5
+```
+
+---
+
+## Before Enhancement (Original Flow)
+
+```mermaid
+graph TB
+    subgraph Old Flow
+        A[Upload File] --> B[Server creates key:<br/>sprint/{id}/{file}]
+        B --> C[All files in root]
+        C --> D[(S3:<br/>sprint/14/file1.md<br/>sprint/14/file2.md<br/>sprint/14/file3.md)]
+    end
+
+    style D fill:#FFB6C1
+```
+
+---
+
+## After Enhancement (With Folder Support)
+
+```mermaid
+graph TB
+    subgraph New Flow
+        A[Upload with folder param] --> B{folder provided?}
+        B -->|Yes| C[Server creates key:<br/>sprint/{id}/folder/{file}]
+        B -->|No| D[Server creates key:<br/>sprint/{id}/{file}]
+        C --> E[Files organized in folders]
+        D --> E
+        E --> F[(S3:<br/>sprint/14/file1.md<br/>sprint/14/project/plans/file2.md<br/>sprint/14/project/knowledge/file3.md)]
+    end
+
+    style C fill:#90EE90
+    style E fill:#90EE90
+    style F fill:#90EE90
+```
+
+---
+
+## doc_folder Linking vs S3 Folder Organization
+
+```mermaid
+graph LR
+    subgraph S3_Physical["Physical S3 Structure"]
+        A[sprint/14/]
+        A --> B[project/]
+        B --> B1[plans/file.md]
+        B --> B2[knowledge/file.md]
+    end
+    
+    subgraph Database["Database Linking"]
+        C[canvasFile table]
+        C --> D[storyId: 101]
+        D --> E[Story #101<br/>doc_folder:<br/>'Project Artifacts']
+    end
+    
+    subgraph UI["ForLoop UI Display"]
+        F[📁 Project Artifacts]
+        F --> G[📄 file.md]
+    end
+    
+    S3_Physical -.->|folder param| Database
+    Database -.->|storyId param| UI
+
+    style S3_Physical fill:#E0F7FA
+    style Database fill:#FFF9C4
+    style UI fill:#F3E5F5
+```
+
+---
+
+## Complete Workflow: .forloop/ Sync
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant Plugin as ForLoop Plugin
+    participant S3 as AWS S3
+    participant DB as Database
+    participant UI as ForLoop UI
+    
+    Note over User,UI: Step 1: Create Plan Document
+    User->>Plugin: Create sprint plan
+    Plugin->>Plugin: Generate .forloop/plan/plan-14-*.md
+    User->>Plugin: forloopFileUpload<br/>--folder project/plans
+    Plugin->>S3: Upload to sprint/14/project/plans/
+    S3-->>Plugin: Upload Success
+    Plugin-->>User: ✅ Plan uploaded to folder
+    
+    Note over User,UI: Step 2: Create Knowledge File
+    User->>Plugin: Capture domain knowledge
+    Plugin->>Plugin: Generate .forloop/knowledge/knowledge-*.md
+    User->>Plugin: forloopFileUpload<br/>--folder project/knowledge
+    Plugin->>S3: Upload to sprint/14/project/knowledge/
+    S3-->>Plugin: Upload Success
+    Plugin-->>User: ✅ Knowledge uploaded to folder
+    
+    Note over User,UI: Step 3: Create Task File
+    User->>Plugin: Break plan into tasks
+    Plugin->>Plugin: Generate .forloop/task/task-14-*.md
+    Plugin->>DB: Create stories in ForLoop
+    User->>Plugin: forloopFileUpload<br/>--folder project/tasks
+    Plugin->>S3: Upload to sprint/14/project/tasks/
+    S3-->>Plugin: Upload Success
+    Plugin-->>User: ✅ Tasks uploaded to folder
+    
+    Note over User,UI: Step 4: Create doc_folder (Optional)
+    User->>Plugin: forloopDocFolder<br/>--title 'Project Artifacts'
+    Plugin->>DB: Create Story #101<br/>(type: doc_folder)
+    DB-->>Plugin: Story #101 Created
+    Plugin-->>User: ✅ Doc folder created
+    
+    Note over User,UI: Step 5: Link Files to doc_folder (Optional)
+    User->>Plugin: forloopFileUpload<br/>--folder project/plans<br/>--storyId 101
+    Plugin->>S3: Upload to sprint/14/project/plans/
+    Plugin->>DB: Set storyId: 101
+    DB-->>Plugin: File record created
+    Plugin-->>User: ✅ File linked to folder
+    
+    Note over User,UI: Result
+    rect rgb(200, 250, 200)
+        Note right of UI: S3 Structure:<br/>sprint/14/<br/>├── project/<br/>│   ├── plans/<br/>│   ├── knowledge/<br/>│   └── tasks/<br/><br/>UI Grouping:<br/>📁 Project Artifacts (Story #101)<br/>└── Linked files
+    end
+```
+
+---
+
+## Parameter Decision Tree
+
+```mermaid
+graph TD
+    A[Upload File] --> B{Need S3<br/>folder structure?}
+    B -->|No| C{Need UI grouping<br/>in app?}
+    B -->|Yes| D[Use: --folder project/plans]
+    C -->|No| E[Result: sprint/14/file.md]
+    C -->|Yes| F{Have doc_folder<br/>story?}
+    D --> G{Also need UI grouping?}
+    G -->|No| H[Result: sprint/14/project/plans/file.md]
+    G -->|Yes| I[Also use: --storyId 101]
+    F -->|No| J[Create doc_folder first]
+    F -->|Yes| K[Use: --storyId 101]
+    J --> K
+    K --> L[Result: sprint/14/file.md<br/>Linked to Story #101]
+    I --> M[Result: sprint/14/project/plans/file.md<br/>Linked to Story #101]
+    
+    style D fill:#FFE4B5
+    style H fill:#90EE90
+    style L fill:#90EE90
+    style M fill:#90EE90
+    style E fill:#FFB6C1
+```
+
+---
+
+## Recommended Usage Patterns
+
+### Pattern 1: .forloop/ Artifacts (Primary Use Case)
+
+```
+Use folder organization ONLY:
+✅ forloopFileUpload --filePath .forloop/plan/plan.md --folder project/plans
+✅ forloopFileUpload --filePath .forloop/knowledge/auth.md --folder project/knowledge
+✅ forloopFileUpload --filePath .forloop/task/task.md --folder project/tasks
+
+Result: Clean S3 structure, visible in AWS console
+```
+
+### Pattern 2: User-Visible Folders
+
+```
+Use doc_folder linking ONLY:
+✅ forloopDocFolder --title 'Specs'
+✅ forloopFileUpload --filePath api-spec.md --storyId 101
+
+Result: Organized in ForLoop UI, S3 remains flat
+```
+
+### Pattern 3: Combined (Advanced)
+
+```
+Use both for complete organization:
+✅ forloopFileUpload --folder project/plans --storyId 101
+
+Result: S3 folders + UI grouping
+```
+
+### Pattern 4: Simple Files (Default)
+
+```
+Use no parameters (backward compatible):
+✅ forloopFileUpload --filePath quick-note.md
+
+Result: sprint/14/quick-note.md (root level)
+```
+
+---
+
+## TypeScript Type Safety
+
+### Plugin Type Definitions
+
+```typescript
+// file-tools.ts
+args: {
+  filePath: string;        // Required
+  sprintId: number;        // Required
+  description?: string;    // Optional
+  folder?: string;         // Optional - S3 folder path
+  storyId?: number;        // Optional - Link to story
+}
+```
+
+### Server Request Body
+
+```typescript
+// uploadController.ts
+interface PresignRequest {
+  sprintId: number;
+  contentType: string;
+  originalName: string;
+  folder?: string;         // Optional
+}
+
+interface CompleteRequest {
+  sprintId: number;
+  fileName: string;
+  originalName: string;
+  fileType: string;
+  size: number;
+  folder?: string;         // Optional
+  storyId?: number;        // Optional
+  x?: number;
+  y?: number;
+}
+```
+
+### Frontend Compatibility
+
+```typescript
+// Frontend calls remain unchanged
+// No breaking changes
+await api.post('/files/presign', {
+  sprintId,
+  contentType: file.type,
+  originalName: file.name,
+  // folder: undefined (uses default)
+});
+```
+
+---
+
+## Key Benefits
+
+1. **Organized S3 Structure** - Files grouped in logical folders
+2. **Backward Compatible** - Existing code works without changes
+3. **Flexible** - Use folders, doc_folders, or both
+4. **Type Safe** - Full TypeScript support
+5. **Future Ready** - Can add more organization features
+
+---
+
+**Created:** 2026-04-12  
+**Version:** 1.0.0