Focus Hub 🎯

A modern, AI-powered task and knowledge management application built with React and TypeScript. Focus Hub helps you organize your work items, projects, and ideas with universal AI assistant integration supporting ChatGPT, Google Gemini, Claude, and more.

✨ Features

🤖 Universal AI Integration (New!)

Multi-Platform Support: Works with ChatGPT, Google Gemini, Claude, and any REST API
Natural Language Interface: Query and manage tasks using conversational AI
Intelligent Processing: AI Gateway understands context and intent
Real-time Sync: Automatic synchronization between AI and app
Offline Support: Queue operations when offline, sync when reconnected

📊 Dual View Modes

Grouped View: Hierarchical organization by categories and subcategories
Table View: Flat list with sortable columns and quick overview

🎨 Modern UI/UX

Clean, minimalist design inspired by Excalidraw
Dark mode support with automatic system detection
Smooth animations and transitions
Responsive layout for all screen sizes
API sync status indicator

📂 Organization System

Categories: Top-level organization (Personal, Work, Project, etc.)
Subcategories: Second-level grouping within categories
Items: Individual tasks or knowledge items
Tags: Cross-cutting labels for flexible organization

🔄 Drag & Drop

Reorder items within categories
Move items between categories and subcategories
Visual feedback during dragging
Different behavior for Grouped vs Table view

💾 Data Management

Local browser storage using IndexedDB (Dexie)
Import/Export functionality with compression
Automatic saving
No server required - fully client-side

📝 Rich Item Features

Progress tracking (0-100%)
External links
Notes and descriptions
Comments system
Tags with autocomplete
Real-time search

🎯 Additional Features

Notes view for free-form documentation
Category management (add, rename, recolor)
Subcategory creation
Context menus for quick actions
Keyboard shortcuts (ESC to close modals)

🚀 Getting Started

Prerequisites

Node.js 18+ (for native fetch support)
npm or yarn

Installation

Clone the repository:

git clone https://github.com/yourusername/focus-hub.git
cd focus-hub

Install dependencies:

# Main app
npm install

# API server dependencies
cd server
npm install

# MCP server dependencies (for Claude)
cd ../mcp-server
npm install

Start the services:

Terminal 1 - React App:

npm start
# Runs on http://localhost:3000

Terminal 2 - API Server (optional, for AI features):

cd server
node index.js
# Runs on http://localhost:3001

Terminal 3 - AI Gateway (optional, for AI features):

cd server
node ai-gateway.js
# Runs on http://localhost:3002

Open http://localhost:3000 in your browser

Production Build

npm run build

This creates an optimized production build in the build/ folder.

🏗️ Architecture

Tech Stack

Frontend

React 18 - UI framework
TypeScript - Type safety
Tailwind CSS - Styling (custom theme system)
Dexie.js - IndexedDB wrapper
@dnd-kit - Drag and drop
@tanstack/react-table - Table management
Lucide React - Icons
LZ-String - Data compression

Backend (AI Integration)

Express.js - REST API server
SQLite3 - Database for API server
MCP SDK - Claude Desktop integration
OpenAPI 3.0 - API specification
Natural Language Processing - Custom query parser

Project Structure

focus-hub/
├── src/
│   ├── components/
│   │   ├── WorkTable/       # Main table component
│   │   ├── Modals/          # All modal dialogs
│   │   ├── Notes/           # Notes view
│   │   ├── ApiSync/         # API synchronization UI
│   │   └── SettingsMenu/    # Settings dropdown
│   ├── hooks/               # Custom React hooks
│   ├── services/
│   │   ├── database.ts      # IndexedDB operations
│   │   └── apiClient.ts     # API client with offline support
│   ├── contexts/            # React contexts (Theme)
│   ├── theme/
│   │   └── styles.ts        # Centralized styling system
│   ├── types/               # TypeScript definitions
│   └── utils/               # Helper functions
├── server/
│   ├── index.js             # REST API server
│   ├── ai-gateway.js        # Universal AI gateway
│   ├── openapi.yaml         # OpenAPI specification
│   └── focushub.db          # SQLite database
├── mcp-server/
│   └── index.js             # Claude MCP server
├── integrations/
│   ├── chatgpt-action.json # ChatGPT configuration
│   └── gemini-extension.json # Gemini configuration
└── docs/
    ├── USER_GUIDE.md        # Comprehensive user guide
    ├── AI_AGENT_SETUP.md    # AI setup instructions
    └── UNIVERSAL_AI_INTEGRATION.md # Universal AI guide

📱 Usage Guide

Adding Items

Click "Add Item" button or use category menu
Fill in item details (name, category, tags, etc.)
Items added from a category auto-select that category

Managing Categories

Click settings menu → "Manage Categories"
Add, rename, or change category colors
Categories persist across sessions

Drag & Drop

Grouped View: Drag items between categories/subcategories
Table View: Reorder items in the list
Drag handle appears on hover

Search & Filter

Global search across all item fields
Filters work in both view modes
Real-time results as you type

Import/Export

Export: Settings → Export Data
Import: Settings → Import Data
Data is compressed for smaller file sizes

🤖 AI Integration

Quick Setup for AI Assistants

ChatGPT:

Start servers: node server/index.js and node server/ai-gateway.js
Use ngrok: ngrok http 3002
Import OpenAPI spec in ChatGPT Actions
Query: "Show me all tasks in Work category"

Google Gemini:

Upload integrations/gemini-extension.json to AI Studio
Point to http://localhost:3002/api/ai/gemini
Use natural language to manage tasks

Claude Desktop:

Add MCP server to claude_desktop_config.json
Restart Claude Desktop
Use Focus Hub tools directly in Claude

Example AI Queries:

"Create a new project for mobile app"
"Show me all urgent tasks"
"Mark task ABC as completed"
"Give me analytics about my work items"

See UNIVERSAL_AI_INTEGRATION.md for detailed setup.

🚢 Deployment

Vercel (Recommended)

Push code to GitHub
Import repository in Vercel
Deploy with default settings

Manual Deployment

Build the project: npm run build
Deploy the build/ folder to any static hosting service
No server configuration needed

🔧 Configuration

Environment Variables

React App (.env)

REACT_APP_API_URL=http://localhost:3001/api  # Optional, for API sync

API Server (server/.env)

PORT=3001                    # API server port
AI_GATEWAY_PORT=3002         # AI gateway port
DB_PATH=./focushub.db        # Database file location

API Endpoints

Endpoint	Method	Description
`/api/health`	GET	Health check
`/api/items`	GET	Get all items (with filters)
`/api/items`	POST	Create new item
`/api/items/:id`	GET	Get specific item
`/api/items/:id`	PUT	Update item
`/api/items/:id`	DELETE	Delete item
`/api/categories`	GET	List all categories
`/api/tags`	GET	List all unique tags
`/api/analytics`	GET	Get analytics data
`/api/sync`	POST	Bulk sync items
`/api/ai/query`	POST	Natural language query
`/api/ai/health`	GET	AI gateway health check

Customization

Categories: Stored in localStorage and synced to API
Theme: Auto-detects system preference
Data: Stored in browser's IndexedDB with API backup
AI Responses: Customizable per platform in gateway server

📊 Performance

Initial Load: ~140KB gzipped
Build Size: 2.2MB uncompressed
Dependencies: Optimized for production
Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Design inspired by Excalidraw
Icons from Lucide
Built with Create React App
AI Integration powered by:

🛠️ What's New in v2.0.0

Major Features

🤖 Universal AI Integration: Support for ChatGPT, Gemini, Claude, and REST APIs
🔄 API Server: Complete REST API with SQLite backend
🧠 Natural Language Processing: AI Gateway for intelligent query parsing
📡 Real-time Sync: Automatic synchronization with offline support
🎨 Improved UI: Consistent styling system and better tag management

Technical Improvements

Centralized theme system with consistent naming
API client with queue management
OpenAPI 3.0 specification
MCP server for Claude Desktop
Comprehensive test suites

📞 Support

For issues, questions, or suggestions:

📋 Open an issue on GitHub
📖 Check the User Guide for detailed instructions
🤖 Read the AI Integration Guide for AI setup

Made with ❤️ by VZ | v2.0.0 | October 2025

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
integrations		integrations
mcp-server		mcp-server
public		public
scripts		scripts
server		server
src		src
.gitignore		.gitignore
AI_AGENT_SETUP.md		AI_AGENT_SETUP.md
COMPLETE_DEPLOYMENT_GUIDE.md		COMPLETE_DEPLOYMENT_GUIDE.md
CUSTOM_DOMAIN_SETUP.md		CUSTOM_DOMAIN_SETUP.md
Claude.md		Claude.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
GITHUB_DEPLOYMENT.md		GITHUB_DEPLOYMENT.md
GITHUB_PUSH_GUIDE.md		GITHUB_PUSH_GUIDE.md
INSTALL_HOMEBREW.md		INSTALL_HOMEBREW.md
README.md		README.md
STYLES_AUDIT_REPORT.md		STYLES_AUDIT_REPORT.md
STYLES_IMPROVEMENT_REPORT.md		STYLES_IMPROVEMENT_REPORT.md
UNIVERSAL_AI_INTEGRATION.md		UNIVERSAL_AI_INTEGRATION.md
USER_GUIDE.md		USER_GUIDE.md
claude_desktop_config.json		claude_desktop_config.json
error-handling-test-report.json		error-handling-test-report.json
gh_2.40.1_macOS_amd64.tar.gz		gh_2.40.1_macOS_amd64.tar.gz
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
push-to-github.sh		push-to-github.sh
tailwind.config.js		tailwind.config.js
test-ai-gateway.js		test-ai-gateway.js
test-api.js		test-api.js
test-error-handling.js		test-error-handling.js
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation