TaskTitan

TaskTitan is a comprehensive productivity and task management iOS application with AI-powered coaching features.

🎯 Overview

TaskTitan combines modern task management with personalized AI coaching to help users overcome procrastination and achieve their goals through a supportive, gamified experience.

Key Features

• Task Management: Create, track, and manage tasks with AI-powered breakdown
• 5 Unique AI Coaches: Personalized coaching with distinct personalities (Natalie, Leeko, Buto, Sutton, Molten)
• Photo Gallery: Capture completed tasks with device camera or photo library
• Progress Analytics: Visual performance metrics and insights
• Smart Notifications: AI-generated reminders with coach personalities
• Multi-language Support: Full English and Chinese localization
• Theme System: Dark/light mode with elegant orange accent
• Subscription Tiers: Basic and Pro feature sets
• Local-First Architecture: All data stored on device, works offline

🏗️ Project Structure

TaskTitan/
├── frontend/                 # React/TypeScript/Capacitor iOS app
│   ├── src/
│   │   ├── components/      # React components (tracker, coach, statistics, etc.)
│   │   ├── services/        # Notification services
│   │   ├── utils/           # API service, storage, analytics
│   │   ├── assets/          # Images and static files
│   │   └── styles/          # Global CSS and theme
│   ├── ios/                 # iOS Capacitor native project
│   ├── build/               # Production build output
│   └── package.json         # Frontend dependencies
├── backend/                  # Node.js/Express backend (optional)
│   ├── src/
│   │   ├── routes/          # API routes (ai-coach, notifications, purchase)
│   │   ├── services/        # GLM-4 AI and notification services
│   │   └── database/        # PostgreSQL schema (future)
│   └── package.json         # Backend dependencies
└── README.md                # This file

🚀 Getting Started

Frontend Setup (Required)

The TaskTitan frontend is a local-first iOS application that stores all data on the device. It can run independently without the backend.

1. Navigate to frontend directory:

cd frontend

2. Install dependencies (includes camera & IAP plugins):

npm install

3. Development server (web preview):

npm run dev
# Open http://localhost:5173

4. Build for iOS:

npm run ios:build

5. Open in Xcode:

npm run cap:open ios

Quick Setup Script

Run the automated camera setup script:

./install-camera.sh

Backend Setup (Optional)

The backend provides AI coaching via Zhipu GLM-4 API and push notifications via Tencent TPNS.

1. Navigate to backend:

cd backend

2. Install dependencies:

npm install

3. Configure environment (.env file):

# Create .env file in backend directory with:
PORT=3001
GLM_API_KEY=your_glm_api_key_here
APPLE_SHARED_SECRET=your_apple_shared_secret_here

# Optional - Tencent Push Notifications
TPNS_ACCESS_ID=your_tpns_access_id
TPNS_SECRET_KEY=your_tpns_secret_key

4. Start server:

npm run dev
# Backend runs on http://localhost:3001

🤖 AI Coaches

The app features 5 unique AI coaching personalities powered by GLM-4-flash:

Coach	Personality	Icon	Description
Natalie	Empathetic & Supportive	💖	Gentle encouragement and emotional support
Leeko	Young & Energetic	⚡	Playful motivation with a rebellious edge
Buto	Direct & No-Nonsense	🛡️	Tough love and accountability
Sutton	Cool & Trendy	⭐	Hip, modern coaching style
Molten	Wise & Reflective	🏠	Thoughtful, philosophical guidance

Each coach has unique response styles and adapts to English or Chinese automatically.

📸 Gallery Feature

Celebrate completed tasks with photos:

• Take Picture: Use device camera to capture completion moments
• From Gallery: Select photos from your photo library
• Photo Cards: Beautiful card-based gallery with task details
• Timing Metrics: Track if you finished early or late
• Local Storage: Photos stored as Base64, works offline

iOS Permissions Required:

• Camera access
• Photo library read access
• Photo library write access

🔔 Notification System

Dual notification architecture:

1. Local Notifications: Immediate, offline browser notifications
2. Push Notifications: Server-side via TPNS with AI-generated messages

Notification Types:

• 24 hours before goal deadline
• 12 hours before goal deadline
• 1 hour before goal deadline
• Goal deadline overdue
• Final deadline warning

🛠️ Tech Stack

Frontend

• React 18 - UI framework
• TypeScript - Type safety
• Vite - Build tool & dev server
• Capacitor 7 - Native iOS bridge
• Tailwind CSS - Utility-first styling
• Radix UI - Accessible component primitives
• Framer Motion - Smooth animations
• Lucide React - Icon library
• Sonner - Toast notifications

Backend

• Node.js - Runtime
• Express - Web framework
• TypeScript - Type safety
• Axios - HTTP client
• PostgreSQL - Database (schema ready)
• Zhipu GLM-4 - AI coaching API
• Tencent TPNS - Push notifications

Native Features

• @capacitor/camera - Camera & photo library access
• @capacitor/local-notifications - Local notifications
• @capacitor/push-notifications - Push notifications

📦 Available Scripts

Frontend

npm run dev              # Start dev server (web preview)
npm run build            # Build for production
npm run preview          # Preview production build
npm run lint             # Run ESLint
npm run type-check       # TypeScript type checking
npm run ios:build        # Build and sync to iOS
npm run ios:dev          # Build and open Xcode
npm run cap:sync         # Sync native plugins
npm run cap:open ios     # Open iOS project in Xcode

Backend

npm run dev              # Start with hot reload
npm run build            # Build TypeScript
npm run start            # Run production build
npm run lint             # Run ESLint

� Subscription & In-App Purchases

Subscription Tiers

Basic (Free):

• 10 tasks per month
• 10 notifications per month
• Access to 1 coach (Natalie)

Pro (¥4.90/month):

• Unlimited tasks
• Unlimited notifications
• Access to all 5 coaches

Apple IAP Setup

1. App Store Connect:

   • Create subscription group: "Pro Subscriptions"
   • Product ID: com.quesx.tasktitan.pro
   • Duration: 1 Month
   • Price: ¥4.90 (China)

2. Get Shared Secret:

   • App Store Connect → Your App → General → App Information
   • Generate App-Specific Shared Secret
   • Add to backend .env as APPLE_SHARED_SECRET

3. Create Sandbox Tester:

   • App Store Connect → Users and Access → Sandbox Testers
   • Add tester account for testing purchases

4. Backend Verification:

   • Backend automatically verifies receipts with Apple
   • Endpoint: /api/purchase/verify

�📱 iOS Deployment

Requirements

• macOS with Xcode 14+
• Apple Developer Account ($99/year)
• iOS device or simulator

Deployment Steps

1. Build the app:

cd frontend
npm run ios:build

2. Configure in Xcode:

   • Set Bundle Identifier: com.quesx.tasktitan
   • Team: Select your Apple Developer account
   • Signing: Enable "Automatically manage signing"
   • Capabilities:
     • ✓ Push Notifications
     • ✓ Background Modes (Remote notifications)
     • ✓ In-App Purchase

3. Info.plist Permissions:

   • Camera: "We need access to capture photos of completed tasks"
   • Photo Library: "We need access to select photos for your task gallery"
   • Notifications: "We send reminders for your tasks and deadlines"

4. TestFlight Distribution:

   • Archive: Product → Archive (in Xcode)
   • Distribute: Select archive → Distribute App
   • Upload to App Store Connect
   • Add testers (internal: up to 100, external: up to 10,000)
   • Wait for processing (~5-10 minutes)

5. App Store Submission:

   • Complete app metadata in App Store Connect
   • Add screenshots (required: 6.5" & 5.5" displays)
   • Write description and keywords
   • Set age rating
   • Submit for review

🌍 Internationalization

Full bilingual support with automatic language detection:

English:

• Primary language
• Full UI translations
• Coach personalities in English

中文 (Chinese):

• Complete Chinese translations
• Localized date/time formatting
• Chinese coach responses

Language switching in Settings → Language

🎨 Theme System

Light Theme:

• Clean white background
• Orange primary accent (#FF6B35)
• High contrast for readability

Dark Theme:

• Pure black background (#0A0A0A)
• Same orange accent for consistency
• OLED-friendly

Toggle in Settings → Theme

💾 Data Storage

Local-First Architecture:

• All data stored in browser LocalStorage
• No cloud dependency
• Works completely offline
• Export/import functionality
• Privacy-focused

Stored Data:

• Tasks and progress
• Chat conversations
• Gallery photos (Base64)
• User preferences
• Analytics data

🔐 Privacy & Security

• No user accounts - Device-based identification
• Local storage - All data stays on device
• Optional backend - Only for AI features
• No data collection - Privacy-first design
• Device fingerprinting - For future cloud sync (optional)

🧪 Testing

Run Tests

Currently no test files. Future: Jest + React Testing Library

Manual Testing Checklist

• Task creation with AI breakdown
• Task completion flow
• Coach chat interactions
• Camera photo capture
• Photo library selection
• Notification scheduling
• Language switching
• Theme switching
• Statistics display
• Gallery card creation

🐛 Troubleshooting

Camera Not Working

• Check iOS Settings → TaskTitan → Enable Camera/Photos access
• Re-sync Capacitor: npm run cap:sync (in frontend directory)
• Rebuild: npm run ios:build

Backend Connection Issues

# Check backend is running
curl http://localhost:3001/health

# Check frontend proxy in vite.config.ts
# Should point to http://localhost:3001

Build Errors

# Clean and rebuild
cd frontend
rm -rf node_modules build ios/App/build
npm install
npm run ios:build

� Project Status

Current Version: 1.0.0
Status: ✅ Production Ready

Recent Updates (Oct 2025):

• ✅ Camera plugin integration for gallery
• ✅ iOS permissions configured
• ✅ Notification system fixed
• ✅ Code cleanup (removed ~1,200 lines of unused code)
• ✅ Documentation consolidated

Completed Features:

• Task management with AI breakdown
• 5 AI coach personalities
• Photo gallery with camera access
• Smart notifications
• Statistics and analytics
• English/Chinese support
• Dark/light themes
• iOS Capacitor setup
• Local-first storage

Future Enhancements:

• Image compression for photos
• Cloud backup (optional)
• Social sharing
• Photo editing
• Android support
• Backend database implementation
• Purchase verification

🤝 Contributing

This is a private project. For issues or suggestions, contact the development team.

📄 License

Proprietary - All rights reserved

🔗 Resources

• Figma Design: https://www.figma.com/design/bu6Mf6DORIdP6KArRgHykc/TaskTitan
• Zhipu GLM-4 API: https://open.bigmodel.cn/
• Capacitor Docs: https://capacitorjs.com/

� Attributions

This project includes:

• Components from shadcn/ui - MIT License
• Photos from Unsplash - Unsplash License

📞 Support

For setup help or bug reports:

1. Check troubleshooting section above
2. Review console logs for detailed errors
3. Verify all dependencies are installed
4. Ensure backend is running (for AI features)

---

Built with ❤️ for productivity and personal growth