pirate-station/.planning/ROADMAP.md

# Roadmap: Pirate Station

**Created:** 2026-02-03
**Depth:** Standard (5-8 phases)

## Overview

| Phase | Name | Goal | Requirements |
|-------|------|------|--------------|
| 1 | Foundation | Go backend running in Docker with isolated storage | INFRA-01, INFRA-02 |
| 2 | CLI Tool | Admin can manage user accounts via CLI | CLI-01, CLI-02, CLI-03, CLI-04 |
| 3 | Authentication | Users can securely log in and out via web | AUTH-01, AUTH-02, AUTH-03, AUTH-04 |
| 4 | Core File Operations | Users can browse, upload, download, and delete files | FILE-01, FILE-02, FILE-03, FILE-04 |
| 5 | Advanced File Operations | Users can create folders, rename, and move items | FILE-05, FILE-06, FILE-07 |
| 6 | UI Polish | Web interface has polished navigation and feedback | UI-01, UI-02, UI-03, UI-04 |

## Phases

### Phase 1: Foundation

**Goal:** Go backend running in Docker with isolated storage

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

**Plans:** 2 plans

Plans:
- [x] 01-01-PLAN.md — Go project structure and multi-stage Dockerfile
- [ ] 01-02-PLAN.md — Docker Compose dev environment and verification

**Success Criteria:**
1. Docker container starts with volume mount and runs Go binary
2. Container cannot access files outside mounted volume
3. Go backend serves HTTP endpoint on specified port
4. Container can be built on x86 and deployed to ARM64 (Pi)

**Depends on:** None

---

### Phase 2: CLI Tool

**Goal:** Admin can manage user accounts via CLI

**Requirements:**
- **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

**Success Criteria:**
1. Admin can create new user with `./cli-tool create <username>`
2. Admin can delete existing user with `./cli-tool delete <username>`
3. Admin can change password with `./cli-tool passwd <username>`
4. Admin can list all users with `./cli-tool list`
5. User database persists in mounted volume (survives container restart)

**Depends on:** Phase 1

---

### Phase 3: Authentication

**Goal:** Users can securely log in and out via web

**Requirements:**
- **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

**Success Criteria:**
1. User can access login page at web root
2. User can log in with valid credentials created via CLI
3. Invalid credentials show error without revealing which part failed
4. User stays logged in across browser sessions (JWT in cookie)
5. User can log out and must log in again to access content

**Depends on:** Phase 2

---

### Phase 4: Core File Operations

**Goal:** Users can browse, upload, download, and delete files

**Requirements:**
- **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

**Success Criteria:**
1. Logged-in user sees file listing of mounted volume root
2. User can click folder to navigate into it
3. User can upload file via button and see it appear in listing
4. User can click file to download it
5. User can delete file or empty folder and see it removed from listing

**Depends on:** Phase 3

---

### Phase 5: Advanced File Operations

**Goal:** Users can create folders, rename, and move items

**Requirements:**
- **FILE-05**: User can create folders
- **FILE-06**: User can rename files and folders
- **FILE-07**: User can move files and folders

**Success Criteria:**
1. User can create new folder and see it in listing
2. User can rename file or folder without changing location
3. User can move file or folder to different directory
4. Move operation preserves file content and permissions

**Depends on:** Phase 4

---

### Phase 6: UI Polish

**Goal:** Web interface has polished navigation and feedback

**Requirements:**
- **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

**Success Criteria:**
1. Current path displays at top of file listing (e.g., `/folder/subfolder`)
2. `..` entry appears at top of listing when not at root, clicking navigates up
3. File sizes show next to each file in human-readable format (KB, MB, GB)
4. Upload shows progress bar or percentage while uploading
5. UI is responsive and usable on mobile browsers

**Depends on:** Phase 4 (Core file ops must work before polishing UI)

---

## Progress

| Phase | Status | Requirements Covered |
|-------|--------|---------------------|
| 1 - Foundation | Planned | 2/21 (10%) |
| 2 - CLI Tool | Pending | 4/21 (19%) |
| 3 - Authentication | Pending | 4/21 (19%) |
| 4 - Core File Operations | Pending | 4/21 (19%) |
| 5 - Advanced File Operations | Pending | 3/21 (14%) |
| 6 - UI Polish | Pending | 4/21 (19%) |

## Coverage

- **Total v1 requirements:** 21
- **Mapped:** 21
- **Unmapped:** 0

### Coverage Map

| Requirement | Phase | Description |
|-------------|-------|-------------|
| INFRA-01 | 1 | Docker isolation to mounted volume |
| INFRA-02 | 1 | Single binary Go backend |
| CLI-01 | 2 | Create user account |
| CLI-02 | 2 | Delete user account |
| CLI-03 | 2 | Change user password |
| CLI-04 | 2 | List all users |
| AUTH-01 | 3 | User login |
| AUTH-02 | 3 | Password hashing |
| AUTH-03 | 3 | JWT session management |
| AUTH-04 | 3 | User logout |
| FILE-01 | 4 | Browse folders |
| FILE-02 | 4 | Upload files |
| FILE-03 | 4 | Download files |
| FILE-04 | 4 | Delete files/folders |
| FILE-05 | 5 | Create folders |
| FILE-06 | 5 | Rename files/folders |
| FILE-07 | 5 | Move files/folders |
| UI-01 | 6 | Display current path |
| UI-02 | 6 | Navigate up with `..` |
| UI-03 | 6 | Display file sizes |
| UI-04 | 6 | Upload progress indicator |

---
*Last updated: 2026-02-03*