🤖 Wingman

React 18 TypeScript 5.2 Electron FastAPI Supabase Ollama SQLite

Project Category: Team Project (NUS Orbital Apollo 2025)

Local-first desktop AI assistant built with modern web technologies. Features task management, calendar integration, mood diary, and intelligent AI chat powered by Ollama. Cross-platform support with SQLite persistence and Supabase authentication.

🖼️ Custom Themes (6 Available)

Each theme provides a unique visual experience with synchronized AI personality:

🌙 Dark

Professional & Efficient

☀️ Light

Bright & Encouraging

🌸 Yandere

Devoted & Protective

❄️ Kuudere

Cool & Logical

🧡 Tsundere

Dynamic & Caring

💜 Dandere

Gentle & Supportive

🎭 AI Personality System

Wingman features 6 distinct AI personalities that synchronize with your selected theme. Each personality has unique traits, communication styles, and emoji preferences:

graph TD A[Theme Selection] --> B[Personality Sync] B --> C{Personality Type} C --> D[Lumen - Light] C --> E[Umbra - Dark] C --> F[Velvet - Yandere] C --> G[Frost - Kuudere] C --> H[Echo - Dandere] C --> I[Blaze - Tsundere] D --> J[Response Generation] E --> J F --> J G --> J H --> J I --> J

Name	Personality	Traits	Communication Style
Lumen	Supportive Buddy	Optimistic, encouraging, warm	Positive reinforcement ☀️✨
Umbra	Strategic Advisor	Analytical, direct, efficient	Minimal but insightful 🌑⚡
Velvet	Devoted Companion	Intensely loyal, protective	Highly personalized 💖👁️
Frost	Professional Assistant	Reserved, logical, professional	Analytical with care ❄️📊
Echo	Gentle Guide	Shy, soft-spoken, caring	Quiet encouragement 🌸💕
Blaze	Dynamic Motivator	Initially distant, caring	Reluctant affection 😤💖

🤖 AI Communication Architecture

Wingman uses a sophisticated dual-path architecture for handling both slash commands and natural conversations:

sequenceDiagram participant U as User participant FE as React Frontend participant API as FastAPI participant CC as ChatCoordinator participant CP as CommandParser participant PM as PersonalityManager participant OS as Ollama LLM participant DB as SQLite U->>FE: Send Message FE->>API: POST /chat/ API->>DB: Save Message alt Slash Command (/t /e /d /u) CC->>CP: Parse Command CP->>DB: Query Data CP->>PM: Add Personality PM->>API: Enhanced Response else Regular Conversation CC->>PM: Get Personality CC->>DB: Get Context CC->>OS: Send to LLM OS->>PM: AI Response PM->>API: Personality Response end API->>DB: Save Response API->>FE: JSON Response FE->>U: Display Message

🚀 Core Features

🤖 AI Chat Assistant

Intelligent conversations with personality-driven responses. Supports slash commands for instant data access (/t for tasks, /e for events, /d for diary, /u for users).

📅 Task Management

Complete task lifecycle with recurring tasks, priorities, and deadlines. Smart scheduling with AI-powered suggestions and automatic failure detection.

📊 Mood Diary

Daily mood tracking with sentiment analysis. Visual charts and insights for mental wellness monitoring with privacy-first local storage.

🔔 Background Notifications

Smart notification system with 30-minute and 5-minute reminders. Continues running when app is minimized or closed using Electron's system tray.

🔒 Privacy-First

Local-first architecture with SQLite database. Optional Supabase sync for cross-device access. Your data stays completely private on your machine.

🎨 6 Custom Themes

Beautiful themes with unique personalities. Each theme has synchronized AI personality, avatar, and custom color schemes with smooth transitions.

🔔 Notification System Architecture

Event-driven notification system with three complementary layers for reliable reminders:

graph TD A[User Creates Task/Event] --> B[NotificationScheduler] B --> C[In-Memory Timers] C --> D[30min Reminder] C --> E[5min Reminder] C --> F[Due/Start Alert] G[App Minimized/Closed] --> H[BackgroundService] H --> I[Electron Main Process] I --> J[OS Notifications] K[Real-time Updates] --> L[DataContext Events] L --> M[Scheduler Updates] M --> N[Timer Recalculation]

⚡ Slash Commands

Wingman supports instant data access through slash commands for quick information retrieval:

/t - Tasks        /e - Events       /d - Diary        /u - Users

Command Examples:

/t /date 2025-01-15 - View all tasks scheduled for January 15, 2025
/e /month jan - Display all events happening in January
/d /mood happy - Show diary entries where you felt happy
/u - List all registered users in the system
/more - Load additional results (pagination support)

🛠️ Technology Stack

Frontend (Electron + React)

React 18: Modern component architecture with hooks and concurrent features
TypeScript 5.2: Type-safe development with latest language features
Electron: Cross-platform desktop app framework with native OS integration
Tailwind CSS: Utility-first styling with custom theme system and dark mode support
Vite: Lightning-fast build tool with hot module replacement

Backend (FastAPI + Python)

FastAPI: High-performance async web framework for AI processing
Ollama Integration: Local LLM inference with automatic model management
SQLite: Embedded database for local data persistence with zero configuration
Supabase: Optional cloud sync with real-time subscriptions and authentication
Uvicorn: Lightning-fast ASGI server for Python async frameworks

AI Models (Ollama)

DeepSeek R1: 1.5B, 7B, 14B variants optimized for reasoning and logic tasks
Llama 3.2: 1B, 3B, 8B variants for general-purpose conversations
Mistral 7B: Multilingual support and instruction-following tasks
Automatic Recommendations: RAM-based model suggestions for optimal performance
Model Switching: Hot-swap models without restarting the application

🎯 My Contributions

AI Integration Pipeline

Architected the complete Ollama integration system with model switching, context management, and intelligent response parsing. Implemented automatic model recommendations based on system RAM.

Theme System Design

Created the comprehensive 6-theme system with CSS variables, smooth transitions, and theme persistence. Implemented dynamic theme switching with real-time UI updates.

Personality AI System

Built the personality-driven AI response engine with theme synchronization and context-aware interactions. Each personality has unique traits and emoji preferences.

Notification Architecture

Designed the event-driven background notification system with smart timing (30min, 5min reminders) and cross-platform OS integration using Electron's system tray.

Task Management Logic

Built the core task scheduling algorithm with priority queuing, deadline tracking, recurring task support, and automatic failure detection for overdue tasks.

Cross-Platform Packaging

Set up Electron Builder configuration for Windows, macOS, and Linux distributions. Implemented auto-updating capabilities and portable executable generation.

📊 Project Metrics

Team Size: 2 developers (NUS Orbital Apollo 2025)
Project Duration: 4 months (May 2025 - August 2025)
Tech Stack: 7 major technologies integrated (React, TypeScript, Electron, FastAPI, Ollama, SQLite, Supabase)
Features: 15+ core functionalities implemented
Themes: 6 custom UI themes with unique personalities and animations
AI Personalities: 6 distinct personality types with synchronized avatars
Platforms: Windows, macOS, Linux support with native installers
Database: SQLite with local-first architecture and optional cloud sync
Code Quality: TypeScript strict mode, ESLint, Prettier integration

🚀 Getting Started

Prerequisites

Node.js 18+ and npm (or yarn)
Python 3.8+ with pip
Ollama installed and running (automatic installation supported)
Git for version control
Windows 10+, macOS 10.13+, or Linux (Ubuntu 18.04+)

Quick Start

# Clone the repository
git clone https://github.com/Yxiang-828/Wingman.git
cd Wingman

# Install dependencies
npm install
pip install -r requirements.txt

# Start Ollama service
ollama serve

# Run in development mode
npm run dev:electron

Production Build

# One-command complete build (Windows)
.\complete-build.bat

# Manual build steps
npm run build
npm run dist

💻 Development Setup

Development Mode

npm run dev:electron    # Starts Vite dev server + Electron + FastAPI backend

Available Scripts

npm run dev - Frontend only development with Vite HMR
npm run dev:electron - Full stack development (Frontend + Backend + Electron)
npm run build - Production build for all platforms
npm run package - Package for current platform only
npm run dist - Build distributables for all platforms
npm run lint - Run ESLint for code quality checks

🔧 Supported AI Models

📋 Model Recommendations by RAM:

≥12GB RAM: DeepSeek R1 14B (Logic Master) - Best reasoning capabilities
≥8GB RAM: DeepSeek R1 7B (Reasoning Pro) - Recommended
≥4GB RAM: Llama 3.2 3B (Balanced) - Good balance of speed and quality
<4GB RAM: DeepSeek R1 1.5B (Ultra Fast) - Fastest responses

🔧 Troubleshooting

Ollama Not Found

# Windows (PowerShell)
winget install --id Ollama.Ollama

# macOS
brew install ollama

# Linux
curl https://ollama.ai/install.sh | sh

AI Model Download Issues

# Check available models
ollama list

# Download model manually
ollama run "deepseek-r1:7b"

# Remove corrupted model
ollama rm "model-name"

# Then restart Wingman

Port Conflicts

If port 8080 is busy, Wingman will automatically find an available port. You can also manually set the port in the configuration file.

Build Errors

# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Python cache
pip cache purge
pip install -r requirements.txt --force-reinstall

✅ Final Evaluation - NUS Orbital Apollo 2025

All Features Accepted by Tutor

Evaluator: Aakash S/O Rengarajan Ramaswamy (NUS Orbital Tutor)

Our Wingman project successfully passed the final evaluation with all 8 core features accepted. The tutor praised the implementation quality, user experience, and technical execution across the entire application:

Wingman Final Evaluation - All Features Accepted

Evaluation Highlights:

✅ Feature 1 - Dashboard & Sidebar: "Really nice central hub that shows everything clearly. I like how you can complete tasks right from the dashboard without navigating elsewhere. Accepted."
✅ Feature 2 - Task Management System: "The auto-fail mechanism is a clever way to encourage task completion. Notifications work as expected and creating tasks from different places feels intuitive. Accepted."
✅ Feature 3 - Recurring Tasks: "Good implementation of the template system. The weekday selection works well and the algorithm you described makes sense. Accepted."
✅ Feature 4 - Calendar Management: "The three view modes work smoothly and switching between them is seamless. Good integration with other features. Accepted."
✅ Feature 5 - Diary & Journaling: "The mood tracking is a nice touch and the search functionality works well. The writing interface is clean and focused. Accepted."
✅ Feature 6 - Background Notifications: "Notifications work properly even when the app is closed. The timing options cover practical use cases. Accepted."
✅ Feature 7 - AI Chat Assistant: "Solid integration with local models and the personality system works as intended. Good fallback handling when AI isn't available. Accepted."
✅ Feature 8 - Holistic Persona System: "This ties everything together nicely. The themes, avatars, and personalities feel consistent across the app. Accepted."

🎉 Final Result: 8/8 Features Accepted - Project Evaluation Successful

View on GitHub → Download Latest Release →