WorkHub — Open-Source Project Management for Freelancers

The all-in-one project management, time tracking, invoicing, marketing, and ops platform built for freelancers, agencies, and small teams.

Stop juggling Trello, Toggl, Buffer, and a pile of spreadsheets. WorkHub combines Kanban boards, time tracking, financial management, calendar scheduling, media library, AI-powered assistance, a Content Studio (AI image generation + social publishing to Facebook/Instagram/LinkedIn), a server monitoring dashboard, team & audit tooling, and an MCP server for AI agents — all in a single self-hosted app.

Live Demo • Getting Started • Features • Screenshots • Docs • Contributing • Changelog

---

Why WorkHub?

Problem	WorkHub Solution
Kanban boards that lag on 100+ tasks	Optimistic UI with instant drag-and-drop — no spinners
Time tracking is a separate app	Built-in live timer with per-task, per-subtask granularity
No idea what clients owe you	Per-project finances — milestone, monthly, and fixed-price tracking
Scattered files across Google Drive & Dropbox	Integrated media library with drag-and-drop upload and image compression
AI tools that don't know your project	Context-aware AI assistant that understands your tasks, deadlines, and workload
SaaS tools that own your data	Self-hosted on Firebase — your data stays on your infrastructure

---

Screenshots

All screenshots show the built-in dark mode. Light mode is fully supported.

Dashboard — Your command center

Active projects, pending tasks, time tracked today/this week, and financial overview — all at a glance.

Projects — Rich project cards with progress tracking

Manage all projects with rich cards showing progress bars, payment models, deadlines, sub-projects, and client info.

Kanban Board — Drag-and-drop task management

Color-coded priorities, task types, time estimates, feature grouping, and confetti celebrations when tasks hit Done.

Financial Management — Know what you're owed

Track payments, milestones, and monthly earnings with interactive charts and per-project financial breakdowns.

Time Tracking — Analyze your work hours

Daily breakdowns, project distribution, and detailed time entry logs with manual entry support.

Media Library — Organize project files

Upload, organize, and link files to projects. Grid/list views, filters, and automatic image optimization.

AI Assistant — Your intelligent project companion

Chat-based AI powered by Google Gemini for task breakdowns, time estimates, and productivity insights.

---

Features

Project Management

• Multi-tier hierarchy: Organizations → Systems → Projects → Features → Tasks → Subtasks
• Kanban board with drag-and-drop reordering across columns (To Do, In Progress, Review, Done)
• Sub-projects with shared or independent finances
• Task types: Task, Bug, Feature, Improvement, Documentation, Research — each color-coded
• Priority levels: Low, Medium, High, Critical — with visual border indicators
• Task states: Archive to declutter, or mark as "Waiting" for blocked tasks
• Comments on tasks and subtasks with threaded discussions

Time Tracking

• Live timer widget — start, pause, resume, stop from anywhere in the app
• Manual time entry for retroactive logging
• Per-subtask tracking linked to projects and tasks
• Daily/weekly summaries on the dashboard
• Persistent timer across page navigation (Zustand + localStorage)

Calendar & Scheduling

• Full calendar view — month, week, day, and list views
• Drag-and-drop events with resize support
• Category-based color coding — Work, Meeting, Deadline, Personal, Reminder
• Status tracking — To Do, In Progress, Review, Done, Cancelled
• Mini calendar sidebar with quick date navigation and filters

Financial Management

• Payment models: Milestone-based, Monthly, Fixed-price, and Internal
• Milestone tracking with pending/completed/paid statuses
• Monthly payment management with payment history
• Income visualization with interactive ApexCharts
• Dashboard stats: Total owed, total received, next payment deadline

Media Library

• Folder hierarchy with breadcrumb navigation
• Drag-and-drop upload with progress tracking
• Automatic image compression via Canvas API (configurable quality/dimensions)
• File categories: Images, Videos, Audio, Documents, Archives
• Link files to projects and tasks
• 50MB max file size via Firebase Storage

Project Vault

• Encrypted-like storage for project-specific sensitive data
• Entry types: Text notes, Passwords, and Files
• Passkey protection with auto-unlock on correct entry
• Per-project isolation accessible from the project detail view

AI Assistant

• Powered by Google Gemini (4 model options: Gemini 3 Pro/Flash, Gemini 2.5 Pro/Flash)
• Task breakdown: Generate subtask suggestions from feature descriptions
• Time estimation: AI-powered effort estimates
• Productivity insights: Project health and work pattern analysis
• Web search: Integrated DuckDuckGo search and URL content fetching
• Optional — gracefully disabled without API key

Content Studio — Marketing & Social

• AI image generation — create on-brand graphics and images from text prompts (multiple quality tiers), saved straight to the media library
• Social post composer — draft posts pairing generated or uploaded media with copy
• Multi-network publishing — publish and schedule to Facebook, Instagram, and LinkedIn
• Campaign planning — plan and lay out multi-post campaigns
• Automatic scheduler — cron-driven auto-publishing at the times you set
• Engagement insights — pull post insights back from connected accounts

Server Monitoring — Ops Dashboard

• Live server stats — CPU, memory, disk, load average, and uptime for the host(s) WorkHub runs on
• Multi-server — one card per server; click through to a full per-server dashboard
• Docker insight — running containers, images, and storage breakdown
• TLS certificate tracking — expiry monitoring for your domains
• Systems & Apps inventory — auto-discovered from Docker, with per-app CPU/memory history charts
• Security posture — automated checks (SSH hardening, firewall, brute-force protection, auto-updates) scored on a card
• Remote agent — a lightweight push agent reports stats from additional servers
• Owner-only — the whole dashboard is gated to the workspace owner

Team & Governance

• Team management — invite members, assign tasks, and manage access
• Audit logs — a chronological, filterable record of changes across the workspace

Integrations & Automation

• MCP server — drive WorkHub time tracking from AI agents (Claude and others) over the Model Context Protocol (list_projects, start_timer, log_time, create_task, and more)
• Email notifications — transactional deadline and payment emails via your mail provider
• Git integration (optional) — browse connected repositories and their READMEs from inside WorkHub
• AI session processing — background AI runs that summarize and organize project work

Notifications

• Deadline alerts — configurable days-before warning
• Payment reminders for pending invoices
• Timer reminders for long-running sessions
• Break reminders and idle detection
• Dismissable — click "Got it" and it won't appear again

Additional

• Dark mode with full theme support
• Responsive design for desktop and tablet
• URL-based tab navigation — deep link to any project tab
• Confetti celebration when tasks are completed
• Optimistic UI — instant feedback on all operations

---

Tech Stack

Category	Technology
Framework	Next.js 16 (App Router, Turbopack)
Language	TypeScript 5.7 (strict mode)
UI	React 19 + Radix UI + shadcn/ui
Styling	Tailwind CSS 3.4
Icons	Lucide React + Remix Icons
Charts	ApexCharts + Recharts
Calendar	FullCalendar 6
Rich Text	TipTap
Database	Firebase Firestore
Auth	Firebase Authentication
Storage	Firebase Storage
State	Zustand 5
AI	Google Generative AI (Gemini)
Dates	date-fns 4
Slider	keen-slider
Automation	Model Context Protocol server (AI-agent time tracking)
Social	Meta Graph API (Facebook / Instagram) + LinkedIn API
Ops	Docker Engine API via a read-only socket proxy (server monitoring)

---

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• A Firebase project with Firestore, Authentication, and Storage enabled
• A Google AI Studio API key (optional — for AI features)

Installation

git clone https://github.com/AhmedSayedSk/workhub.git
cd workhub
npm install

Environment Variables

cp .env.local.example .env.local

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# Gemini AI (optional)
GEMINI_API_KEY=your_gemini_api_key

Where to get these:

• Firebase: Firebase Console → Project Settings → General → Your Apps
• Gemini: Google AI Studio

Firebase Setup

1. Create a Firebase project at console.firebase.google.com
2. Enable Firestore Database (production mode)
3. Enable Authentication → Email/Password
4. Enable Storage
5. Copy .firebaserc.example to .firebaserc and update with your project ID
6. Deploy rules:

npm run firebase:deploy:rules
npm run firebase:deploy:indexes

Run

npm run dev          # Development → http://localhost:3090
npm run build        # Production build
npm start            # Start production server

---

Available Scripts

Command	Description
npm run dev	Development server (port 3090)
npm run build	Production build
npm start	Production server
npm run lint	ESLint checks
npm run migrate	Run Firestore migrations
npm run firebase:deploy	Deploy all Firebase configs
npm run firebase:deploy:rules	Deploy Firestore rules
npm run firebase:deploy:indexes	Deploy Firestore indexes

---

Architecture

Data Model

Organization
  └── System (color-coded project groups)
        └── Project (client, payment model, finances)
              ├── Feature (high-level work items)
              │     └── Task (kanban items with status, type, priority)
              │           ├── Subtask (granular work units)
              │           ├── TaskComment (discussion threads)
              │           └── TimeEntry (tracked work sessions)
              ├── CalendarEvent (scheduled events)
              ├── Milestone (payment milestones)
              ├── MonthlyPayment (recurring payments)
              └── VaultEntry (sensitive project data)

MediaFolder / MediaFile  (global media library, linkable to projects/tasks)
Member                   (team members, roles, task assignments)
SocialPost / Campaign    (Content Studio posts, schedules, campaigns)
AuditLog                 (workspace-wide change history)
VpsMetrics / VpsSnapshots (server-monitoring time-series + latest per-server snapshot)
AppSettings              (singleton for AI model + integration configuration)

API Routes

Endpoint	Method	Description
/api/ai	POST / GET	AI: task breakdown, time estimates, insights, Q&A / fetch AI settings
/api/ai/image	POST	AI image generation for the Content Studio
/api/web/search	POST	DuckDuckGo web search
/api/web/fetch	POST	Extract content from URLs
/api/social/publish	POST	Publish a post to a connected network
/api/social/schedule	POST	Schedule a post for later
/api/social/unpublish	POST	Remove a published post
/api/social/insights	GET	Engagement insights for connected accounts
/api/social/linkedin/oauth/*	GET	LinkedIn OAuth connect flow
/api/social/cron/run	POST	Scheduler tick — auto-publishes due posts (secret-gated)
/api/campaigns/plan	POST	Plan a multi-post campaign
/api/vps/servers	GET	Multi-server summary for the ops dashboard (owner-only)
/api/vps/stats	GET	Full live/snapshot stats for one server (owner-only)
/api/vps/report	POST	Remote-agent snapshot ingest (secret-gated)
/api/vps/history, /api/vps/system-history	GET	Time-series metric history (owner-only)
/api/vps/sample, /api/vps/rollup	POST	Metric sampler + hourly rollup crons (secret-gated)
/api/email/notify	POST	Send a transactional notification email
/api/create-user, /api/reset-password	POST	Team member provisioning and password reset

Key Design Decisions

• Optimistic updates on all CRUD — instant UI with automatic rollback on error
• Optional flags (archived, waiting) are orthogonal to task status
• Firestore Timestamps everywhere for consistency
• Background sync for calendar events — dialog closes immediately
• URL-based tab state for deep linking and refresh persistence

---

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a PR.

We follow the Contributor Covenant Code of Conduct. By participating, you agree to uphold it.

# Fork, then:
git clone https://github.com/YOUR_USERNAME/workhub.git
cd workhub
npm install
cp .env.local.example .env.local
cp .firebaserc.example .firebaserc  # Add your Firebase project ID
npm run dev

Areas Where Help is Needed

• Testing — Unit and integration tests
• Accessibility — Keyboard navigation, screen reader support, ARIA labels
• Internationalization — Multi-language support
• Mobile — Responsive improvements for phones
• Performance — Firestore query optimization, bundle size reduction

Security

Found a vulnerability? Please see our Security Policy for responsible disclosure guidelines.

---

License

This project is licensed under the Sikasio Source Available License.

Free for personal use. Commercial use requires a license from Sikasio. See LICENSE for full terms.

---

FAQ

Is WorkHub free?

Yes — free for personal use, learning, and non-commercial projects. Commercial use requires a license from Sikasio.

Can I self-host WorkHub?

Absolutely. WorkHub is designed to be self-hosted on your own Firebase project. Your data stays yours.

Do I need the AI features?

No. AI features are optional and gracefully disabled without a Gemini API key. Everything else works perfectly without it.

What's the difference between WorkHub and Jira/Asana/Monday?

WorkHub is built for small teams and freelancers, not enterprises. It combines project management, time tracking, finances, and AI in one place — no per-seat pricing, no feature-gating, no vendor lock-in.

---

Built by Sikasio — From Chaos to Clarity

Report Bug • Request Feature • Star on GitHub