diff --git a/README.md b/README.md index 8b61e33..73f8de6 100644 --- a/README.md +++ b/README.md @@ -1 +1,497 @@ -# fabdash \ No newline at end of file +# 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, CODA 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.*