107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
# Implementation Plan: File Storage Management & UI
|
|
|
|
**Branch**: `014-file-storage-ui` | **Date**: 2026-01-24 | **Spec**: [specs/014-file-storage-ui/spec.md](../014-file-storage-ui/spec.md)
|
|
**Input**: Feature specification from `specs/014-file-storage-ui/spec.md`
|
|
|
|
## Summary
|
|
|
|
This feature implements a managed file storage system for dashboard backups and exported repositories. It introduces a configurable storage root (defaulting to outside the workspace) and a Web UI to list, upload, download, and delete files. The system enforces a structured layout with `backups/` and `repositories/` subdirectories to keep artifacts organized. The UI supports hierarchical folder navigation (e.g., `backups/SS2/DashboardName`), allowing users to browse, download, and manage files within nested directories.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Python 3.9+ (Backend), Node.js 18+ (Frontend)
|
|
**Primary Dependencies**: FastAPI (Backend), SvelteKit (Frontend)
|
|
**Storage**: Local Filesystem (for artifacts), Config (for storage path)
|
|
**Testing**: pytest (Backend), vitest/playwright (Frontend - implied)
|
|
**Target Platform**: Linux server
|
|
**Project Type**: Web application
|
|
**Performance Goals**: File list load < 1s for 100 files, supports 50MB+ uploads
|
|
**Constraints**: Must prevent path traversal, must not pollute git repo
|
|
**Scale/Scope**: ~2-3 backend endpoints, 1-2 frontend pages/components
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- **I. Semantic Protocol Compliance**:
|
|
- **Status**: PASSED
|
|
- **Check**: Will use `[DEF]` anchors and `@RELATION` tags.
|
|
- **Check**: Will follow File Structure Standard.
|
|
|
|
- **II. Causal Validity (Contracts First)**:
|
|
- **Status**: PASSED
|
|
- **Check**: Contracts will be defined in `specs/014-file-storage-ui/contracts/` before implementation.
|
|
|
|
- **III. Immutability of Architecture**:
|
|
- **Status**: PASSED
|
|
- **Check**: No changes to immutable architectural constraints expected.
|
|
|
|
- **IV. Design by Contract (DbC)**:
|
|
- **Status**: PASSED
|
|
- **Check**: Functions will define `@PRE` and `@POST` conditions.
|
|
|
|
- **V. Belief State Logging**:
|
|
- **Status**: PASSED
|
|
- **Check**: Will use standard logging patterns.
|
|
|
|
- **VI. Fractal Complexity Limit**:
|
|
- **Status**: PASSED
|
|
- **Check**: Feature scope is small, unlikely to exceed complexity limits.
|
|
|
|
- **VII. Everything is a Plugin**:
|
|
- **Status**: PASSED
|
|
- **Check**: New functionality will be implemented as a `StoragePlugin` (or similar) inheriting from `PluginBase`.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/014-file-storage-ui/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output
|
|
└── tasks.md # Phase 2 output
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
backend/
|
|
├── src/
|
|
│ ├── api/
|
|
│ │ └── routes/
|
|
│ │ └── storage.py # New route handler
|
|
│ ├── plugins/
|
|
│ │ └── storage.py # New plugin implementation
|
|
│ └── models/
|
|
│ └── storage.py # Pydantic models (StoredFile, StorageConfig)
|
|
└── tests/
|
|
└── test_storage.py # Backend tests
|
|
|
|
frontend/
|
|
├── src/
|
|
│ ├── routes/
|
|
│ │ └── storage/
|
|
│ │ └── +page.svelte # Main storage UI
|
|
│ ├── components/
|
|
│ │ └── storage/
|
|
│ │ ├── FileList.svelte # Component for listing files and folders (explorer view)
|
|
│ │ ├── Breadcrumbs.svelte # Component for navigation
|
|
│ │ └── FileUpload.svelte # Component for uploading
|
|
│ └── services/
|
|
│ └── storageService.js # Frontend API client
|
|
```
|
|
|
|
**Structure Decision**: Standard Web Application structure (Backend + Frontend) with Plugin architecture for the backend logic.
|
|
|
|
## Complexity Tracking
|
|
|
|
> **Fill ONLY if Constitution Check has violations that must be justified**
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| N/A | | |
|