fabdash/README.md

# FabDash

**Fabrication Dashboard** — A sleek, modern project management & scheduling application.

![Version](https://img.shields.io/badge/version-1.0.0-gold)
![Stack](https://img.shields.io/badge/stack-React%20%2B%20Flask%20%2B%20SQLite-informational)
![Theme](https://img.shields.io/badge/theme-Dark%20%2F%20Gold-yellow)
![Docker](https://img.shields.io/badge/deployment-Single%20Docker%20Container-blue)

---

## Table of Contents

- [Overview](#overview)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Features](#features)
- [API Reference](#api-reference)
- [Unraid Installation](#unraid-installation)
- [Updating FabDash on Unraid](#updating-fabdash-on-unraid)
- [Local Development](#local-development)
- [Environment Variables](#environment-variables)
- [Database Schema](#database-schema)
- [Roadmap](#roadmap)

---

## Overview

FabDash is a self-hosted project management dashboard built for fabrication teams. It features a large interactive calendar, multi-deliverable project tracking, drag-and-drop scheduling, and a per-project timeline Focus View — all wrapped in a dark/gold UI and deployed as a single Docker container.

---

## Tech Stack

| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS |
| Calendar | FullCalendar v6 (daygrid, timegrid, interaction) |
| Focus View | Custom horizontal timeline (react-chrono) |
| State | Zustand |
| HTTP | Axios |
| Backend | Flask 3, Flask-SQLAlchemy, Flask-Migrate, Flask-CORS |
| Database | SQLite (persisted via Docker volume) |
| Server | Gunicorn (production) |

---

## Project Structure

```
fabdash/
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
├── README.md
│
├── backend/
│   ├── run.py
│   ├── config.py
│   ├── requirements.txt
│   └── app/
│       ├── __init__.py
│       ├── extensions.py
│       ├── models.py
│       └── routes/
│           ├── __init__.py
│           ├── projects.py
│           └── deliverables.py
│
└── frontend/
    ├── package.json
    ├── vite.config.js
    ├── tailwind.config.js
    ├── postcss.config.js
    ├── index.html
    └── src/
        ├── main.jsx
        ├── App.jsx
        ├── api/
        │   ├── projects.js
        │   └── deliverables.js
        ├── components/
        │   ├── Calendar/
        │   │   └── MainCalendar.jsx
        │   ├── Projects/
        │   │   ├── ProjectList.jsx
        │   │   ├── ProjectCard.jsx
        │   │   └── ProjectModal.jsx
        │   ├── Deliverables/
        │   │   └── DeliverableModal.jsx
        │   ├── FocusView/
        │   │   ├── FocusDrawer.jsx
        │   │   ├── FocusTimeline.jsx
        │   │   └── DeliverableCard.jsx
        │   └── UI/
        │       ├── Button.jsx
        │       ├── Badge.jsx
        │       ├── Modal.jsx
        │       └── Drawer.jsx
        ├── store/
        │   ├── useProjectStore.js
        │   └── useFocusStore.js
        ├── utils/
        │   ├── dateHelpers.js
        │   └── statusHelpers.js
        └── styles/
            └── globals.css
```

---

## Features

- **Large calendar view** — Month, Week, and Day modes via FullCalendar
- **Drag-and-drop** — Move deliverables to new dates; backend updates instantly
- **Multi-deliverable projects** — Unlimited deliverables per project, each with its own due date and status
- **Color-coded projects** — 12-swatch palette + custom hex input
- **Deliverable Focus View** — Click any calendar event to open a slide-up drawer with the full project timeline; clicked deliverable highlighted in gold
- **Status tracking** — Upcoming / In Progress / Completed / Overdue badges
- **Dark/gold theme** — Dark surfaces throughout with gold as the primary accent
- **Full persistence** — SQLite via Flask-SQLAlchemy, mounted as a Docker volume

---

## API Reference

### Projects

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/projects` | List all projects with nested deliverables |
| `POST` | `/api/projects` | Create project (with optional inline deliverables) |
| `GET` | `/api/projects/:id` | Get single project |
| `PATCH` | `/api/projects/:id` | Update name, color, or description |
| `DELETE` | `/api/projects/:id` | Delete project + cascade deliverables |

### Deliverables

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/deliverables?project_id=:id` | List deliverables for a project |
| `POST` | `/api/deliverables` | Create deliverable |
| `PATCH` | `/api/deliverables/:id` | Update title, due_date, or status |
| `DELETE` | `/api/deliverables/:id` | Delete deliverable |

---

## Unraid Installation

FabDash is installed by cloning the repo and building the Docker image locally on your Unraid server via SSH, then registering and managing the container through the Unraid Docker GUI. This gives you full GUI control (start, stop, logs, edit) while keeping the image local.

---

### Step 1 — Enable SSH on Unraid

Go to **Settings → Management Access** and confirm SSH is enabled. Note your Unraid server's local IP address (visible on the Unraid dashboard header).

---

### Step 2 — SSH into Unraid and Clone the Repo

Open a terminal on your local machine and connect:

```bash
ssh root@YOUR_UNRAID_IP
```

Clone FabDash into your appdata share:

```bash
cd /mnt/user/appdata
git clone https://github.com/yourname/fabdash.git
cd fabdash
```

---

### Step 3 — Build the Docker Image Locally

This command builds the image on your Unraid server and tags it as `fabdash:latest`.
The first build takes 3–5 minutes (downloads Node + Python layers, compiles React).

```bash
docker build -t fabdash:latest .
```

When complete, verify the image exists:

```bash
docker images | grep fabdash
# fabdash   latest   abc123def456   1 minute ago   ...
```

---

### Step 4 — Create the Data Directory

Create the persistent directory where SQLite will store your database:

```bash
mkdir -p /mnt/user/appdata/fabdash/data
```

---

### Step 5 — Add the Container via Unraid Docker GUI

1. In the Unraid web UI, go to the **Docker** tab
2. At the bottom, click **Add Container**
3. In the top-right of the form, toggle to **Advanced View**

Fill in the fields exactly as follows:

#### Basic Settings

| Field | Value |
|---|---|
| **Name** | `fabdash` |
| **Repository** | `fabdash:latest` |
| **Docker Hub URL** | *(leave blank — local image)* |
| **Network Type** | `Bridge` |
| **Console shell command** | `bash` |
| **Privileged** | `Off` |

#### Port Mapping

Click **Add another Path, Port, Variable, Label or Device** → select **Port**:

| Field | Value |
|---|---|
| **Name** | `Web UI` |
| **Container Port** | `8080` |
| **Host Port** | `8080` |
| **Connection Type** | `TCP` |

> Access FabDash at `http://YOUR_UNRAID_IP:8080` after starting the container.
> Change Host Port if `8080` is already in use on your server.

#### Volume / Path Mapping

Click **Add another Path, Port, Variable, Label or Device** → select **Path**:

| Field | Value |
|---|---|
| **Name** | `AppData` |
| **Container Path** | `/app/data` |
| **Host Path** | `/mnt/user/appdata/fabdash/data` |
| **Access Mode** | `Read/Write` |

> This is where `fabdash.db` will live. Data persists across all container restarts and rebuilds.

#### Environment Variables

Click **Add another Path, Port, Variable, Label or Device** → select **Variable** for each:

| Name | Key | Value |
|---|---|---|
| Secret Key | `SECRET_KEY` | `your-strong-random-secret-key-here` |
| Flask Environment | `FLASK_ENV` | `production` |
| Database URL | `DATABASE_URL` | `sqlite:////app/data/fabdash.db` |

> **SECRET_KEY** — Use a long random string. Generate one with:
> ```bash
> cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 48 | head -n 1
> ```

#### Extra Parameters (optional)

| Field | Value |
|---|---|
| **Extra Parameters** | `--restart unless-stopped` |

---

### Step 6 — Apply and Start

Click **Apply** at the bottom of the form. Unraid will register and start the container using your locally built image.

Navigate to the **Docker** tab — you should see `fabdash` running with a green indicator.

Open your browser:

```
http://YOUR_UNRAID_IP:8080
```

---

### Step 7 — Verify (Optional)

Check container logs from the Unraid Docker tab by clicking the `fabdash` container icon → **Logs**, or via SSH:

```bash
docker logs fabdash --tail 50
```

A healthy startup looks like:

```
[INFO] Starting gunicorn 23.0.0
[INFO] Listening at: http://0.0.0.0:8080
[INFO] Worker booting (pid: ...)
```

---

## Updating FabDash on Unraid

When a new version is pushed to GitHub, update FabDash in three steps:

### Step 1 — Pull the latest code and rebuild

SSH into Unraid:

```bash
ssh root@YOUR_UNRAID_IP
cd /mnt/user/appdata/fabdash
git pull
docker build -t fabdash:latest .
```

### Step 2 — Restart the container via Unraid GUI

1. Go to the **Docker** tab in Unraid
2. Click the `fabdash` container icon
3. Select **Restart**

The container will stop, reload with the newly built image, and come back up. Your database is untouched.

### Step 3 — Verify

```bash
docker logs fabdash --tail 20
```

---

## Data Backup

Your database lives at:

```
/mnt/user/appdata/fabdash/data/fabdash.db
```

**Manual backup:**

```bash
cp /mnt/user/appdata/fabdash/data/fabdash.db \
   /mnt/user/backups/fabdash-$(date +%Y%m%d-%H%M).db
```

**Automated backup** — Use the **Appdata Backup/Restore** plugin from Unraid Community Applications to schedule regular backups of `/mnt/user/appdata/fabdash/`.

---

## Local Development

Run backend and frontend separately for Vite hot-module reloading:

**Terminal 1 — Flask:**

```bash
cd backend
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install -r requirements.txt
export FLASK_ENV=development
flask run --port 5000
```

**Terminal 2 — React:**

```bash
cd frontend
npm install
npm run dev                   # http://localhost:5173
```

Vite proxies all `/api/*` calls to Flask on port 5000 automatically via `vite.config.js`. No CORS issues in dev.

---

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `SECRET_KEY` | Yes | — | Flask session secret. Use a long random string |
| `FLASK_ENV` | No | `production` | Set to `development` for debug mode |
| `DATABASE_URL` | No | `sqlite:////app/data/fabdash.db` | SQLite path (4 slashes = absolute path) |

---

## Database Schema

```sql
CREATE TABLE projects (
  id          INTEGER  PRIMARY KEY AUTOINCREMENT,
  name        TEXT     NOT NULL,
  color       TEXT     NOT NULL DEFAULT '#C9A84C',
  description TEXT,
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE deliverables (
  id          INTEGER  PRIMARY KEY AUTOINCREMENT,
  project_id  INTEGER  NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  title       TEXT     NOT NULL,
  due_date    DATE     NOT NULL,
  status      TEXT     NOT NULL DEFAULT 'upcoming'
                       CHECK(status IN ('upcoming','in_progress','completed','overdue')),
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_deliverables_project  ON deliverables(project_id);
CREATE INDEX idx_deliverables_due_date ON deliverables(due_date);
```

---

## Roadmap

### v1.0 — Core Release *(current)*

- [x] Dark/gold Tailwind design system
- [x] FullCalendar with Month / Week / Day views
- [x] Drag-and-drop deliverable rescheduling
- [x] Multi-deliverable project creation with inline rows
- [x] Add / Edit / Delete for projects and deliverables
- [x] Deliverable Focus View — slide-up drawer with horizontal timeline
- [x] Active deliverable gold highlight in Focus View
- [x] Status badges (Upcoming / In Progress / Completed / Overdue)
- [x] Flask REST API + SQLite persistence
- [x] Cascade delete (project → deliverables)
- [x] Single Docker container deployment
- [x] Unraid installation — local build + Docker GUI management

### v1.1 — Polish & UX

- [ ] Keyboard shortcuts (`N` = new project, `Esc` = close, arrow keys = calendar nav)
- [ ] 30-second undo toast for drag-and-drop moves
- [ ] Animated modal/drawer transitions
- [ ] Hover tooltip on calendar events (preview without opening Focus View)
- [ ] Responsive layout with collapsible sidebar
- [ ] Empty state illustrations

### v1.2 — Calendar Enhancements

- [ ] Agenda sidebar showing all upcoming deliverables across projects
- [ ] Date range selection for bulk deliverable creation
- [ ] "Today" jump button
- [ ] Week numbers in calendar header

### v2.0 — Auth & Multi-user

- [ ] User login (Flask-Login + JWT)
- [ ] Multi-user support with project ownership
- [ ] Role-based access per project (Owner / Editor / Viewer)
- [ ] Activity log and comment threads per deliverable

### v2.1 — Notifications & Integrations

- [ ] In-app notification center for approaching due dates
- [ ] Email reminders at configurable intervals (Flask-Mail)
- [ ] iCal / Google Calendar export
- [ ] Slack webhook for deliverable status changes
- [ ] CSV import/export

### v2.2 — Advanced Views

- [ ] Gantt view alternate layout
- [ ] Kanban board (columns by status)
- [ ] Cross-project timeline view
- [ ] Workload heatmap

### v3.0 — Intelligence Layer

- [ ] AI scheduling suggestions
- [ ] Conflict detection for overloaded days
- [ ] Natural language deliverable input

---

*Built with intention. No subscriptions. No bloat. Just your fabrication workflow.*