498 lines
18 KiB
Markdown
498 lines
18 KiB
Markdown
# FabDash
|
||
### Fabrication Dashboard — A Sleek, Modern Project Management & Scheduling Application
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
- [Overview](#overview)
|
||
- [Core Philosophy](#core-philosophy)
|
||
- [Tech Stack](#tech-stack)
|
||
- [Project Structure](#project-structure)
|
||
- [Data Architecture](#data-architecture)
|
||
- [Features](#features)
|
||
- [Main Calendar View](#main-calendar-view)
|
||
- [Project & Deliverable Management](#project--deliverable-management)
|
||
- [Deliverable Focus View](#deliverable-focus-view)
|
||
- [Color Coding System](#color-coding-system)
|
||
- [Theme & Design System](#theme--design-system)
|
||
- [API Reference](#api-reference)
|
||
- [Component Architecture](#component-architecture)
|
||
- [Getting Started](#getting-started)
|
||
- [Prerequisites](#prerequisites)
|
||
- [Backend Setup](#backend-setup)
|
||
- [Frontend Setup](#frontend-setup)
|
||
- [Running the App](#running-the-app)
|
||
- [Environment Variables](#environment-variables)
|
||
- [Database Schema](#database-schema)
|
||
- [Roadmap](#roadmap)
|
||
---
|
||
|
||
## Overview
|
||
|
||
**FabDash** is a self-hosted, full-stack project management and scheduling application built for professionals who need a clean, fast, and visually intuitive way to manage multi-deliverable projects across time. It combines a large, interactive calendar view with a powerful per-project timeline focus system — all wrapped in a dark, modern UI with gold accents.
|
||
|
||
Unlike bloated SaaS tools, FABDASH runs locally with zero subscription fees, full data ownership, and a UI designed with intention — not feature creep.
|
||
|
||
---
|
||
|
||
## Core Philosophy
|
||
|
||
| Principle | Implementation |
|
||
|---|---|
|
||
| **Clarity over clutter** | One focused view at a time — calendar or timeline, never both fighting for space |
|
||
| **Speed of interaction** | Drag, click, and edit without leaving context |
|
||
| **Data ownership** | Local SQLite persistence, no cloud dependency |
|
||
| **Visual hierarchy** | Gold accents guide the eye to what matters most |
|
||
|
||
---
|
||
|
||
## Tech Stack
|
||
|
||
### Frontend
|
||
| Package | Version | Purpose |
|
||
|---|---|---|
|
||
| React | ^18.x | UI component framework |
|
||
| Vite | ^5.x | Build tool & dev server |
|
||
| Tailwind CSS | ^3.x | Utility-first styling with custom tokens |
|
||
| @fullcalendar/react | ^6.x | Main calendar view |
|
||
| @fullcalendar/daygrid | ^6.x | Month/week/day grid views |
|
||
| @fullcalendar/interaction | ^6.x | Drag-and-drop + click events |
|
||
| @fullcalendar/timegrid | ^6.x | Time-slot grid view |
|
||
| react-chrono | ^2.x | Deliverable Focus View timeline |
|
||
| Zustand | ^4.x | Global state management |
|
||
| Axios | ^1.x | HTTP client for Flask API |
|
||
| React Router | ^6.x | Client-side routing |
|
||
| date-fns | ^3.x | Date formatting and manipulation |
|
||
|
||
### Backend
|
||
| Package | Version | Purpose |
|
||
|---|---|---|
|
||
| Flask | ^3.x | REST API server |
|
||
| Flask-SQLAlchemy | ^3.x | ORM for SQLite |
|
||
| Flask-CORS | ^4.x | Cross-origin support for React dev server |
|
||
| Flask-Migrate | ^4.x | Database migrations |
|
||
|
||
### Database
|
||
- **SQLite** — Zero-config, file-based persistence. Located at `/backend/fabdash.db`
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
\`\`\`
|
||
fabdash/
|
||
│
|
||
├── backend/ # Flask REST API
|
||
│ ├── app/
|
||
│ │ ├── __init__.py # App factory
|
||
│ │ ├── models.py # SQLAlchemy models
|
||
│ │ ├── routes/
|
||
│ │ │ ├── projects.py # Project CRUD endpoints
|
||
│ │ │ └── deliverables.py # Deliverable CRUD endpoints
|
||
│ │ └── extensions.py # db, cors, migrate instances
|
||
│ ├── migrations/ # Flask-Migrate migration files
|
||
│ ├── fabdash.db # SQLite database (auto-generated)
|
||
│ ├── config.py # Environment config
|
||
│ └── run.py # App entry point
|
||
│
|
||
├── frontend/ # React + Vite application
|
||
│ ├── public/
|
||
│ ├── src/
|
||
│ │ ├── api/
|
||
│ │ │ ├── projects.js # Axios calls for projects
|
||
│ │ │ └── deliverables.js # Axios calls for deliverables
|
||
│ │ ├── components/
|
||
│ │ │ ├── Calendar/
|
||
│ │ │ │ ├── MainCalendar.jsx # FullCalendar wrapper
|
||
│ │ │ │ ├── EventChip.jsx # Color-coded event pill
|
||
│ │ │ │ └── CalendarToolbar.jsx # Custom nav toolbar
|
||
│ │ │ ├── Projects/
|
||
│ │ │ │ ├── ProjectList.jsx # Sidebar project list
|
||
│ │ │ │ ├── ProjectCard.jsx # Individual project entry
|
||
│ │ │ │ └── ProjectModal.jsx # Add/edit project modal
|
||
│ │ │ ├── Deliverables/
|
||
│ │ │ │ ├── DeliverableModal.jsx # Add/edit deliverable modal
|
||
│ │ │ │ └── DeliverableChip.jsx # Badge inside ProjectCard
|
||
│ │ │ ├── FocusView/
|
||
│ │ │ │ ├── FocusDrawer.jsx # Slide-up drawer container
|
||
│ │ │ │ ├── FocusTimeline.jsx # react-chrono wrapper
|
||
│ │ │ │ └── DeliverableCard.jsx # Individual timeline card
|
||
│ │ │ └── UI/
|
||
│ │ │ ├── Button.jsx
|
||
│ │ │ ├── Badge.jsx # Status badge (Upcoming/Overdue)
|
||
│ │ │ ├── Modal.jsx # Base modal wrapper
|
||
│ │ │ └── Drawer.jsx # Base slide-up drawer
|
||
│ │ ├── store/
|
||
│ │ │ ├── useProjectStore.js # Zustand: project state
|
||
│ │ │ └── useFocusStore.js # Zustand: focus view state
|
||
│ │ ├── hooks/
|
||
│ │ │ ├── useProjects.js # Data fetching hook
|
||
│ │ │ └── useDeliverables.js # Data fetching hook
|
||
│ │ ├── utils/
|
||
│ │ │ ├── dateHelpers.js # date-fns wrappers
|
||
│ │ │ └── statusHelpers.js # Overdue/Upcoming logic
|
||
│ │ ├── styles/
|
||
│ │ │ └── globals.css # Tailwind base + custom vars
|
||
│ │ ├── App.jsx
|
||
│ │ └── main.jsx
|
||
│ ├── tailwind.config.js
|
||
│ ├── vite.config.js
|
||
│ └── package.json
|
||
│
|
||
├── .env.example
|
||
├── .gitignore
|
||
└── README.md
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## Data Architecture
|
||
|
||
### Relationships
|
||
|
||
\`\`\`
|
||
Project (1) ──────────── (many) Deliverable
|
||
│ │
|
||
├── id (PK) ├── id (PK)
|
||
├── name ├── project_id (FK)
|
||
├── color (hex) ├── title
|
||
├── description ├── due_date
|
||
└── created_at ├── status (enum)
|
||
└── created_at
|
||
\`\`\`
|
||
|
||
Each **Project** owns one or more **Deliverables**. Every deliverable inherits the parent project's color when rendered on the calendar. Deleting a project cascades to remove all its deliverables.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
### Main Calendar View
|
||
|
||
The primary interface is a large, full-width **FullCalendar** grid. It supports three view modes switchable from the toolbar:
|
||
|
||
- **Month View** — Full month overview, all deliverables visible as colored event chips
|
||
- **Week View** — Focused 7-day view with time slots
|
||
- **Day View** — Single-day granularity for heavy scheduling days
|
||
|
||
**Interaction behaviors:**
|
||
- **Drag-and-drop** any deliverable event to a new date — the backend is updated immediately via `PATCH /deliverables/:id`
|
||
- **Click** any event to open the **Deliverable Focus View** for that project
|
||
- **Right-click** (context menu) on an event to access quick actions: Edit, Delete, Open Project
|
||
- **Click empty date cell** to open the Add Deliverable modal pre-filled with that date
|
||
|
||
---
|
||
|
||
### Project & Deliverable Management
|
||
|
||
**Adding a Project:**
|
||
1. Click the **"+ New Project"** button in the sidebar
|
||
2. Enter project name, optional description, and select a color swatch
|
||
3. Immediately add one or more deliverables inline before saving
|
||
4. Submit — project and all deliverables are persisted in a single transaction
|
||
|
||
**Adding a Deliverable to an Existing Project:**
|
||
- Open a project via the sidebar and click **"+ Add Deliverable"**
|
||
- Or click an empty calendar cell and select an existing project from the dropdown
|
||
|
||
**Editing:**
|
||
- Click any deliverable chip in the sidebar or calendar event to open its edit modal
|
||
- All fields (title, date, status) are editable inline
|
||
|
||
**Deleting:**
|
||
- Projects can be deleted from the sidebar (with a confirmation dialog warning of cascade delete)
|
||
- Individual deliverables can be deleted from their edit modal or via calendar right-click context menu
|
||
|
||
---
|
||
|
||
### Deliverable Focus View
|
||
|
||
Clicking any deliverable on the calendar opens a **slide-up drawer** from the bottom of the screen containing the full project timeline for that deliverable's parent project.
|
||
|
||
**Behavior:**
|
||
- All deliverables for the project are rendered as a **horizontal timeline** using `react-chrono` in `HORIZONTAL_ALL` mode
|
||
- The **clicked deliverable is highlighted** with a gold glowing border (`ring-2 ring-gold`) and elevated scale
|
||
- All other deliverables appear as dimmed context nodes
|
||
- Each card displays: deliverable title, due date, and status badge
|
||
- The drawer can be dismissed by clicking outside it, pressing `Escape`, or clicking the close button
|
||
- An **"Edit Deliverable"** and **"Edit Project"** button are available within the drawer without navigating away
|
||
|
||
**Active Node Visual Treatment:**
|
||
\`\`\`
|
||
[ Deliverable 1 ]──────[ Deliverable 2 ]──────[ ★ Deliverable 3 ★ ]
|
||
Jan 15, 2026 Feb 28, 2026 Mar 28, 2026
|
||
Completed In Progress ← ACTIVE / FOCUSED
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
### Color Coding System
|
||
|
||
Each project is assigned a hex color at creation. This color is used:
|
||
- As the **background of event chips** on the FullCalendar grid
|
||
- As the **left border accent** on sidebar project cards
|
||
- As the **timeline node color** in the Focus View for non-active deliverables
|
||
|
||
Colors are fully user-selectable from a curated palette of 12 swatches (chosen to remain readable against the dark background) plus a custom hex input.
|
||
|
||
---
|
||
|
||
### Theme & Design System
|
||
|
||
The entire application uses a **dark, modern aesthetic** with gold as the primary accent color.
|
||
|
||
**Tailwind Custom Tokens:**
|
||
\`\`\`js
|
||
// tailwind.config.js
|
||
theme: {
|
||
extend: {
|
||
colors: {
|
||
gold: '#C9A84C',
|
||
'gold-light': '#E8C96A',
|
||
'gold-muted': '#8A6E2F',
|
||
surface: '#111111',
|
||
'surface-raised': '#1A1A1A',
|
||
'surface-elevated':'#242424',
|
||
'surface-border': '#2E2E2E',
|
||
'text-primary': '#F5F5F5',
|
||
'text-muted': '#888888',
|
||
},
|
||
boxShadow: {
|
||
gold: '0 0 12px rgba(201, 168, 76, 0.4)',
|
||
},
|
||
fontFamily: {
|
||
sans: ['Inter', 'sans-serif'],
|
||
mono: ['JetBrains Mono', 'monospace'],
|
||
}
|
||
}
|
||
}
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## API Reference
|
||
|
||
### Projects
|
||
|
||
| Method | Endpoint | Description |
|
||
|---|---|---|
|
||
| `GET` | `/api/projects` | Fetch all projects with nested deliverables |
|
||
| `POST` | `/api/projects` | Create a new project |
|
||
| `GET` | `/api/projects/:id` | Fetch a single project |
|
||
| `PATCH` | `/api/projects/:id` | Update project name, color, or description |
|
||
| `DELETE` | `/api/projects/:id` | Delete project and cascade deliverables |
|
||
|
||
### Deliverables
|
||
|
||
| Method | Endpoint | Description |
|
||
|---|---|---|
|
||
| `GET` | `/api/deliverables?project_id=:id` | Fetch deliverables for a project |
|
||
| `POST` | `/api/deliverables` | Create a new deliverable |
|
||
| `PATCH` | `/api/deliverables/:id` | Update title, date, or status |
|
||
| `DELETE` | `/api/deliverables/:id` | Delete a single deliverable |
|
||
|
||
**Example Payload — Create Project with Deliverables:**
|
||
\`\`\`json
|
||
POST /api/projects
|
||
{
|
||
"name": "CODA",
|
||
"color": "#4A90D9",
|
||
"description": "Example fabrication project",
|
||
"deliverables": [
|
||
{ "title": "Deliverable 1 – Concept Brief", "due_date": "2026-01-15" },
|
||
{ "title": "Deliverable 2 – Draft Review", "due_date": "2026-02-28" },
|
||
{ "title": "Deliverable 3 – Final Submission", "due_date": "2026-03-28" }
|
||
]
|
||
}
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## Component Architecture
|
||
|
||
\`\`\`
|
||
App
|
||
├── Sidebar
|
||
│ ├── ProjectList
|
||
│ │ └── ProjectCard (× N)
|
||
│ │ └── DeliverableChip (× N)
|
||
│ └── Button ["+ New Project"]
|
||
│
|
||
├── MainCalendar
|
||
│ ├── CalendarToolbar (Month / Week / Day + nav arrows)
|
||
│ └── FullCalendar
|
||
│ └── EventChip (rendered per deliverable)
|
||
│
|
||
├── ProjectModal (Add / Edit project)
|
||
├── DeliverableModal (Add / Edit deliverable)
|
||
│
|
||
└── FocusDrawer (slide-up, conditionally rendered)
|
||
└── FocusTimeline
|
||
└── DeliverableCard (× N, one highlighted)
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
### Prerequisites
|
||
- Node.js >= 18.x
|
||
- Python >= 3.11
|
||
- pip
|
||
- Git
|
||
|
||
---
|
||
|
||
### Backend Setup
|
||
|
||
\`\`\`bash
|
||
cd backend
|
||
python -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
flask db init
|
||
flask db migrate -m "Initial schema"
|
||
flask db upgrade
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
### Frontend Setup
|
||
|
||
\`\`\`bash
|
||
cd frontend
|
||
npm install
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
### Running the App
|
||
|
||
**Terminal 1 — Flask backend:**
|
||
\`\`\`bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
flask run --port 5000
|
||
\`\`\`
|
||
|
||
**Terminal 2 — React frontend:**
|
||
\`\`\`bash
|
||
cd frontend
|
||
npm run dev
|
||
\`\`\`
|
||
|
||
App will be available at: **http://localhost:5173**
|
||
|
||
---
|
||
|
||
## Environment Variables
|
||
|
||
\`\`\`env
|
||
# backend/.env
|
||
FLASK_APP=run.py
|
||
FLASK_ENV=development
|
||
DATABASE_URL=sqlite:///fabdash.db
|
||
SECRET_KEY=your-secret-key-here
|
||
|
||
# frontend/.env
|
||
VITE_API_BASE_URL=http://localhost:5000/api
|
||
\`\`\`
|
||
|
||
---
|
||
|
||
## 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 scope)*
|
||
- [x] Dark/gold design system with Tailwind custom tokens
|
||
- [x] FullCalendar main view with Month / Week / Day modes
|
||
- [x] Drag-and-drop deliverable rescheduling
|
||
- [x] Project creation with multiple deliverables and color selection
|
||
- [x] Add / Edit / Delete for both projects and deliverables
|
||
- [x] Deliverable Focus View (slide-up drawer with react-chrono horizontal timeline)
|
||
- [x] Active deliverable highlighting in Focus View
|
||
- [x] Status badges (Upcoming / In Progress / Completed / Overdue)
|
||
- [x] Flask REST API with SQLite persistence
|
||
- [x] Cascade delete (project → deliverables)
|
||
- [x] Right-click context menu on calendar events
|
||
|
||
---
|
||
|
||
### v1.1 — Polish & UX
|
||
- [ ] Keyboard shortcuts (N = new project, Esc = close modal/drawer, ←→ = calendar navigation)
|
||
- [ ] Undo/redo for drag-and-drop moves (30-second undo toast)
|
||
- [ ] Animated transitions on drawer open/close and modal enter/exit
|
||
- [ ] Deliverable sorting within Focus View (by date, by status)
|
||
- [ ] Empty state illustrations for no projects / no deliverables
|
||
- [ ] Responsive layout for smaller screens (collapsible sidebar)
|
||
|
||
### v1.2 — Enhanced Calendar
|
||
- [ ] Mini-map / agenda sidebar showing upcoming deliverables across all projects
|
||
- [ ] Week numbers in calendar header
|
||
- [ ] "Today" jump button with smooth scroll animation
|
||
- [ ] Hoverable event tooltip previewing deliverable details without opening Focus View
|
||
- [ ] Date range selection to bulk-create deliverables
|
||
|
||
### v2.0 — Collaboration & Auth
|
||
- [ ] User authentication (Flask-Login + JWT)
|
||
- [ ] Multi-user support with project ownership and sharing
|
||
- [ ] Role-based access (Owner / Editor / Viewer per project)
|
||
- [ ] Activity log per project (who changed what, when)
|
||
- [ ] Comment threads on individual deliverables
|
||
|
||
### v2.1 — Notifications & Integrations
|
||
- [ ] In-app notification center for approaching due dates
|
||
- [ ] Email reminders (Flask-Mail) at configurable intervals before due date
|
||
- [ ] iCal / Google Calendar export per project
|
||
- [ ] Slack webhook integration for deliverable status changes
|
||
- [ ] CSV import/export for bulk project setup
|
||
|
||
### v2.2 — Advanced Views
|
||
- [ ] Gantt view (using dhtmlx-gantt or Bryntum) as an alternate layout
|
||
- [ ] Kanban board view (columns by status: Upcoming / In Progress / Completed)
|
||
- [ ] Cross-project timeline view showing all projects on one horizontal axis
|
||
- [ ] Workload heatmap showing deliverable density per day across all projects
|
||
- [ ] Archived projects with searchable history
|
||
|
||
### v3.0 — Intelligence Layer
|
||
- [ ] AI-assisted scheduling: suggest optimal due dates based on project cadence
|
||
- [ ] Auto-detect overdue deliverables and surface them on dashboard load
|
||
- [ ] Smart conflict detection: flag days with too many concurrent deliverables
|
||
- [ ] Natural language input for creating deliverables ("Add final draft due next Friday to CODA")
|
||
|
||
---
|
||
|
||
*Built with intention. No subscriptions. No bloat. Just your fabrication workflow.*
|