pirate-station/.planning/REQUIREMENTS.md

# Requirements: Pirate Station

**Defined:** 2026-02-03
**Core Value:** Users can securely access and manage files on the Pi from anywhere via the web, with the server completely isolated to its designated storage directory.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Authentication

- [ ] **AUTH-01**: User can log in with username and password
- [ ] **AUTH-02**: Passwords stored with secure hashing (bcrypt/argon2)
- [ ] **AUTH-03**: JWT tokens for session management
- [ ] **AUTH-04**: User can log out

### CLI Tool

- [ ] **CLI-01**: Admin can create user account with username/password
- [ ] **CLI-02**: Admin can delete user account
- [ ] **CLI-03**: Admin can change user password
- [ ] **CLI-04**: Admin can list all users

### File Operations

- [ ] **FILE-01**: User can browse folders and see file listing
- [ ] **FILE-02**: User can upload files
- [ ] **FILE-03**: User can download files
- [ ] **FILE-04**: User can delete files and folders
- [ ] **FILE-05**: User can create folders
- [ ] **FILE-06**: User can rename files and folders
- [ ] **FILE-07**: User can move files and folders

### Web UI

- [ ] **UI-01**: Current path displayed (non-clickable)
- [ ] **UI-02**: `..` entry for navigating up one directory
- [ ] **UI-03**: File sizes displayed in listing
- [ ] **UI-04**: Upload progress indicator

### Infrastructure

- [ ] **INFRA-01**: Docker container runs isolated to mounted volume only
- [ ] **INFRA-02**: Single binary Go backend

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### UI Enhancements

- **UI-05**: Drag-and-drop file upload
- **UI-06**: Responsive mobile design
- **UI-07**: Clickable breadcrumb navigation

### Features

- **FEAT-01**: File preview (images, text, video)
- **FEAT-02**: Bulk file selection and operations

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Self-registration | Security — admin creates accounts via CLI only |
| Web admin panel | Simplicity — CLI is sufficient for small user base |
| Per-user private folders | Not needed — trusted group shares one space |
| File preview/streaming | Complexity — just upload, download, manage |
| Tailscale integration | User constraint — using frpc/rathole instead |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| INFRA-01 | Phase 1 | Complete |
| INFRA-02 | Phase 1 | Complete |
| CLI-01 | Phase 2 | Pending |
| CLI-02 | Phase 2 | Pending |
| CLI-03 | Phase 2 | Pending |
| CLI-04 | Phase 2 | Pending |
| AUTH-01 | Phase 3 | Pending |
| AUTH-02 | Phase 3 | Pending |
| AUTH-03 | Phase 3 | Pending |
| AUTH-04 | Phase 3 | Pending |
| FILE-01 | Phase 4 | Pending |
| FILE-02 | Phase 4 | Pending |
| FILE-03 | Phase 4 | Pending |
| FILE-04 | Phase 4 | Pending |
| FILE-05 | Phase 5 | Pending |
| FILE-06 | Phase 5 | Pending |
| FILE-07 | Phase 5 | Pending |
| UI-01 | Phase 6 | Pending |
| UI-02 | Phase 6 | Pending |
| UI-03 | Phase 6 | Pending |
| UI-04 | Phase 6 | Pending |

**Coverage:**
- v1 requirements: 21 total
- Mapped to phases: 21
- Unmapped: 0 ✓

---
*Requirements defined: 2026-02-03*
*Last updated: 2026-02-03 after Phase 1 completion*