487 lines
14 KiB
Markdown
487 lines
14 KiB
Markdown
# FabDash
|
||
|
||
**Fabrication Dashboard** — A sleek, modern project management & scheduling application.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 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.*
|