# FabDash
### Fabrication Dashboard — A Sleek, Modern Project Management & Scheduling Application

![Version](https://img.shields.io/badge/version-1.0.0--alpha-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)
![License](https://img.shields.io/badge/license-MIT-green)

---

## 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.*