🛰️ Pocket NAS

A futuristic, minimal NAS dashboard for managing files on a tablet-based FTP server.

Built with React, TypeScript, and Express — deployed on Vercel (frontend) and Railway (backend).

---

✨ Features

• 📁 Browse files — Navigate directories with animated breadcrumbs
• ⬆️ Upload files — Drag-and-drop with multi-file queue
• ⬇️ Download files — One-click downloads
• 🗑️ Delete files — Confirmation modal with safety checks
• 📂 Create folders — Organize your NAS storage
• 🔄 Real-time refresh — Instant directory updates
• 🎨 Futuristic UI — Glassmorphism, neon accents, smooth animations

---

🏗️ Architecture

┌─────────────────┐     HTTPS      ┌─────────────────┐      FTP       ┌─────────────────┐
│                 │  ◄──────────►  │                 │  ◄──────────►  │                 │
│   Frontend      │                │   Backend       │                │   Tablet NAS    │
│   (Vercel)      │                │   (Railway)     │                │   (FTP Server)  │
│                 │                │                 │                │                 │
│   React + Vite  │                │   Express +     │                │   Android/iOS   │
│   TailwindCSS   │                │   basic-ftp     │                │   FTP App       │
│   Framer Motion │                │                 │                │                 │
└─────────────────┘                └─────────────────┘                └─────────────────┘

---

📂 Project Structure

pocket-nas/
├── frontend/                # React + TypeScript UI
│   ├── src/
│   │   ├── api/             # API client (axios)
│   │   ├── components/      # React components
│   │   │   ├── Header.tsx
│   │   │   ├── Breadcrumbs.tsx
│   │   │   ├── Toolbar.tsx
│   │   │   ├── UploadZone.tsx
│   │   │   ├── FileGrid.tsx
│   │   │   ├── FileCard.tsx
│   │   │   ├── CreateFolderModal.tsx
│   │   │   └── DeleteConfirmModal.tsx
│   │   ├── utils/           # Helper functions
│   │   ├── App.tsx          # Main application
│   │   └── index.css        # Design system
│   ├── vercel.json          # Vercel deployment config
│   └── vite.config.ts       # Vite + Tailwind config
│
├── backend/                 # Node.js API server
│   ├── src/
│   │   ├── routes/          # Express route handlers
│   │   │   ├── files.ts     # File operations
│   │   │   └── folders.ts   # Folder operations
│   │   ├── services/        # Business logic
│   │   │   └── ftp.service.ts  # FTP client wrapper
│   │   └── index.ts         # Server entry point
│   ├── Dockerfile           # Docker deployment
│   └── .env.example         # Environment template
│
├── shared/                  # Shared TypeScript types
│   └── types.ts
│
├── docs/                    # Documentation
│   ├── ARCHITECTURE.md
│   └── DEPLOYMENT.md
│
├── scripts/                 # Dev utilities
│   ├── setup.sh
│   └── dev.sh
│
└── .github/workflows/       # CI pipeline
    └── ci.yml

---

🚀 Quick Start

Prerequisites

• Node.js 20+
• npm 10+
• An FTP server running on your tablet (e.g., Solid Explorer, FTP Server app)

1. Clone & Setup

git clone https://github.com/Bhargi777/pocket-nas.git
cd pocket-nas
chmod +x scripts/setup.sh
./scripts/setup.sh

2. Configure Environment

Edit backend/.env with your FTP server details:

FTP_HOST=192.168.1.100    # Your tablet's IP address
FTP_USER=admin             # FTP username
FTP_PASSWORD=password      # FTP password
FTP_PORT=21                # FTP port (usually 21)
PORT=4000                  # Backend server port
FRONTEND_URL=http://localhost:5173

3. Start Development

# Option A: Both servers at once
./scripts/dev.sh

# Option B: Start separately
cd backend && npm run dev    # Terminal 1
cd frontend && npm run dev   # Terminal 2

4. Open Dashboard

Visit http://localhost:5173

---

🔌 API Reference

Method	Endpoint	Description
GET	/health	Server health check
GET	/api/files?path=/	List files in directory
POST	/api/upload	Upload file (multipart form)
GET	/api/download/:name?path=/	Download a file
DELETE	/api/files/:name?path=/	Delete a file
POST	/api/folder	Create a new folder
DELETE	/api/folder/:name?path=/	Delete a folder

---

🌐 Deployment

Frontend → Vercel

1. Import this repo on vercel.com
2. Set root directory to frontend
3. Add env variable: VITE_API_URL = your backend URL
4. Deploy

Backend → Railway

1. Import this repo on railway.app
2. Set root directory to backend
3. Add env variables: FTP_HOST, FTP_USER, FTP_PASSWORD, FRONTEND_URL
4. Deploy

See docs/DEPLOYMENT.md for detailed instructions.

---

🔒 Security Notes

• Never commit .env files — they contain FTP credentials
• CORS is configured to allow only the specified frontend origin
• File size limit is set to 500 MB per upload
• FTP connections are created per-request and closed immediately after
• Use FTPS (FTP over TLS) in production when possible

---

🛠 Tech Stack

Layer	Technology	Purpose
Frontend	React 18	UI framework
Frontend	TypeScript 5	Type safety
Frontend	Vite 7	Build tool
Frontend	Tailwind CSS v4	Styling
Frontend	Framer Motion	Animations
Frontend	Axios	HTTP client
Backend	Node.js	Runtime
Backend	Express	HTTP server
Backend	basic-ftp	FTP client
Backend	Multer	File uploads
Infra	Vercel	Frontend hosting
Infra	Railway	Backend hosting
Infra	Docker	Containerization
CI/CD	GitHub Actions	Automated builds

---

📄 License

MIT License — see LICENSE for details.

---

Built with ☕ by Bhargi777