PROJECT OVERVIEW:
The application, named 'App Ghost', is a desktop-based utility designed to help non-technical users identify, manage, and terminate multiple instances of the same application running simultaneously on their computer. It solves the common user frustration of unexpected duplicate application processes (e.g., two instances of Microsoft Outlook) that consume resources and cause confusion. The core value proposition is simplifying system resource management and troubleshooting for the average computer user, making complex process management intuitive and accessible.
TECH STACK:
- Frontend: React (Next.js App Router)
- Styling: Tailwind CSS
- State Management: Zustand or Jotai for global state, React Context API for local/themed state.
- UI Components: shadcn/ui for a clean, modern, and accessible UI.
- Backend (for potential future cloud sync/user accounts, or local data persistence): Not strictly required for MVP if treated as a standalone desktop app. If desktop app packaging (like Electron) is used, a local Node.js backend could manage process interactions. For this MVP, assume direct OS process interaction via native modules or OS commands if packaging is used. If a web-based version is considered later, then: Drizzle ORM with PostgreSQL/SQLite on a Node.js (Express/Fastify) or Next.js API routes.
- Icons: Lucide React
- Data Fetching: React Query (for server state management if applicable) or direct API calls for serverless functions.
- Authentication (Optional for MVP, but good for future sync features): NextAuth.js or Clerk.
DATABASE SCHEMA (If a persistent local or cloud backend is implemented, e.g., for user settings or history):
1. `users` table:
- `id` (UUID, primary key)
- `email` (VARCHAR, unique)
- `name` (VARCHAR)
- `createdAt` (TIMESTAMP)
- `updatedAt` (TIMESTAMP)
2. `applicationInstances` table (for historical tracking if implemented):
- `id` (UUID, primary key)
- `userId` (UUID, foreign key to users.id)
- `appName` (VARCHAR)
- `processId` (INTEGER)
- `startTime` (TIMESTAMP)
- `endTime` (TIMESTAMP, nullable)
- `resourceUsage` (JSONB, e.g., { cpu: float, memory: float })
- `createdAt` (TIMESTAMP)
3. `userSettings` table:
- `id` (UUID, primary key)
- `userId` (UUID, foreign key to users.id)
- `settings` (JSONB, e.g., { autoRefreshInterval: integer, notificationsEnabled: boolean })
- `updatedAt` (TIMESTAMP)
CORE FEATURES & USER FLOW:
1. **Application Detection and Listing:**
- **User Flow:** Upon launching App Ghost, the application automatically scans the system for running processes. It identifies executables and attempts to map them to user-friendly application names (e.g., 'chrome.exe' -> 'Google Chrome'). The main view displays a list of detected applications.
- **Functionality:** Utilizes OS-level APIs (e.g., WMI on Windows, `psutil` or equivalent in a bundled Node.js environment) to get a list of running processes, their PIDs, and resource usage.
2. **Duplicate Instance Highlighting:**
- **User Flow:** As the list populates, App Ghost analyzes the detected applications. If multiple instances of the same named application are found (e.g., two 'outlook.exe' processes), it visually flags these entries in the list, perhaps with a distinct icon or background color.
- **Functionality:** Groups processes by a normalized application name. Counts instances for each name. Highlights applications where the count is greater than 1.
3. **Instance Details View:**
- **User Flow:** Users can click on an application in the list, especially a flagged duplicate, to see detailed information about each running instance. This includes Process ID (PID), CPU usage, Memory usage, and potentially the command line arguments used to launch it.
- **Functionality:** When an application is selected, a modal or an expandable row displays specific details for each related process. Fetches real-time resource usage for each PID.
4. **Instance Termination:**
- **User Flow:** From the instance details view or directly from the main list (with a confirmation step), a user can select a specific instance and click a 'Terminate' button. A confirmation dialog appears ('Are you sure you want to terminate [App Name] Instance [PID]?'). Upon confirmation, the selected process is terminated.
- **Functionality:** Uses OS commands (`taskkill` on Windows, `kill` on Linux/macOS via a packaged backend) to terminate the process by its PID. Includes error handling for cases where termination fails (e.g., insufficient privileges).
5. **Real-time Updates & Refresh:**
- **User Flow:** The list of running applications and their resource usage updates automatically at a configurable interval (e.g., every 5 seconds). Users can also manually trigger a refresh.
- **Functionality:** Implements an interval timer to re-fetch process data. Provides a manual refresh button. Potentially uses websockets if a client-server architecture is adopted.
API & DATA FETCHING:
- **Local Process Data:** If using a packaged desktop app (e.g., Electron), an internal API (Node.js) will expose endpoints like `/api/processes` (GET) to fetch the list of running processes and their stats. This API would interact directly with the OS.
- **Request:** `GET /api/processes`
- **Response:** `[ { name: 'string', pid: number, cpu: number, memory: number, instances: number, isDuplicate: boolean }, ... ]`
- **Termination API:** `POST /api/terminate` with body `{ pid: number }`. Response: `{ success: boolean, message: string }`.
- **Frontend Data Flow:** React components will call these internal API endpoints. State management (Zustand/Jotai) will hold the process list. UI components re-render based on state changes. React Query can be used to manage caching and background updates if the complexity warrants it.
COMPONENT BREAKDOWN (Next.js App Router Structure):
- **`app/layout.tsx`**: Root layout. Includes `<html>`, `<body>`, global Tailwind CSS imports, global providers (Theme Provider, possibly Zustand Provider).
- **`app/page.tsx`**: Dashboard/Main Page.
- **`components/ui/Header.tsx`**: App title, maybe a refresh button, settings icon.
- **`components/ui/ApplicationList.tsx`**: Main table/list component. Fetches and displays applications.
- State: `processData` (Array of process objects).
- Handles filtering and sorting.
- **`components/ui/ApplicationListItem.tsx`**: Individual row/item in the list. Displays app name, instance count, basic resource usage. Includes highlight for duplicates. Clickable to show details.
- **`components/ui/ProcessDetailModal.tsx`**: Modal dialog shown when an item is clicked. Displays detailed info (PID, CPU, Memory) for each instance of a selected app. Contains 'Terminate' buttons.
- **`components/ui/RefreshButton.tsx`**: Manual refresh trigger.
- **`components/ui/SettingsDialog.tsx`**: Modal for user preferences (e.g., refresh interval).
- **`app/api/processes/route.ts`** (If using Next.js API routes for a local server wrapper): Handles GET requests for process data.
- **`app/api/terminate/route.ts`**: Handles POST requests for terminating processes.
UI/UX DESIGN & VISUAL IDENTITY:
- **Design Style:** Minimalist Clean with subtle technological accents.
- **Color Palette:**
- Primary: `#007AFF` (Vibrant Blue for interactive elements)
- Secondary: `#F5F5F5` (Light Gray for backgrounds)
- Accent: `#4CAF50` (Green for success/running state), `#FFC107` (Amber for warnings/duplicates), `#F44336` (Red for termination actions/errors)
- Text: `#333333` (Dark Gray for primary text), `#757575` (Medium Gray for secondary text)
- Dark Mode Palette:
- Primary: `#4A90E2`
- Background: `#1E1E1E` (Very Dark Gray)
- Accent: `#8BC34A` (Light Green), `#FFB300` (Amber), `#E57373` (Light Red)
- Text: `#E0E0E0` (Light Gray), `#BDBDBD` (Medium Gray)
- **Typography:** A clean, sans-serif font family like Inter or Roboto.
- Headings: Semi-bold, 24-32px
- Body Text: Regular, 14-16px
- **Layout:** Single-column or two-column responsive layout. Main content area clearly defined. Modals for details and confirmations. Use of cards for distinct information blocks.
- **Responsiveness:** Mobile-first approach. Columns adapt, tables become scrollable or transform into stacked lists on smaller screens. Ensure usability on various screen sizes.
ANIMATIONS:
- **Transitions:** Smooth transitions for modal pop-ups (fade-in, slide-up), row expansions, and general UI element changes using `transition` utilities in Tailwind CSS.
- **Loading Indicators:** Subtle spinners or pulsing animations within list items or buttons when data is being fetched or a termination action is in progress.
- **Hover Effects:** Gentle background color changes or slight scaling on list items and buttons when hovered.
EDGE CASES:
- **No Applications Running:** Display a friendly message and an illustration indicating that no applications are currently detected.
- **Insufficient Permissions:** If the app cannot access process information or terminate a process due to user privileges, display a clear, actionable message guiding the user on how to grant necessary permissions (e.g., 'Run as Administrator').
- **Process Termination Failure:** If `terminate` API call fails, show an error message to the user, possibly with the specific OS error.
- **Invalid Input:** Validate PID inputs if manual termination is ever exposed directly.
- **Authentication Flow (if implemented):** Standard login/signup, password reset, session management.
- **Empty State for Settings:** Default values are used if `userSettings` record doesn't exist.
SAMPLE DATA:
1. **Normal State:**
`[
{ name: 'Google Chrome', pid: 1234, cpu: 5.2, memory: 250, instances: 3, isDuplicate: true },
{ name: 'Visual Studio Code', pid: 5678, cpu: 10.5, memory: 300, instances: 1, isDuplicate: false },
{ name: 'System Idle Process', pid: 0, cpu: 90.0, memory: 0, instances: 1, isDuplicate: false },
{ name: 'Microsoft Outlook', pid: 9101, cpu: 3.1, memory: 150, instances: 2, isDuplicate: true },
{ name: 'Microsoft Outlook', pid: 9105, cpu: 2.8, memory: 145, instances: 2, isDuplicate: true },
{ name: 'Discord', pid: 1122, cpu: 1.5, memory: 200, instances: 1, isDuplicate: false }
]`
2. **All Unique Instances:**
`[
{ name: 'Slack', pid: 3344, cpu: 2.0, memory: 180, instances: 1, isDuplicate: false },
{ name: 'Spotify', pid: 5566, cpu: 4.0, memory: 220, instances: 1, isDuplicate: false }
]`
3. **Multiple Duplicates:**
`[
{ name: 'Notepad', pid: 7788, cpu: 0.5, memory: 10, instances: 4, isDuplicate: true },
{ name: 'Notepad', pid: 7790, cpu: 0.4, memory: 12, instances: 4, isDuplicate: true },
{ name: 'Notepad', pid: 7792, cpu: 0.6, memory: 11, instances: 4, isDuplicate: true },
{ name: 'Notepad', pid: 7795, cpu: 0.5, memory: 10, instances: 4, isDuplicate: true },
{ name: 'Web Browser', pid: 9900, cpu: 15.0, memory: 500, instances: 2, isDuplicate: true },
{ name: 'Web Browser', pid: 9905, cpu: 14.5, memory: 490, instances: 2, isDuplicate: true }
]`
4. **Empty State (No Apps Found):**
`[]`
5. **High Resource Usage Example:**
`[
{ name: 'Game Process', pid: 1000, cpu: 75.0, memory: 2048, instances: 1, isDuplicate: false },
{ name: 'Antivirus Scan', pid: 1100, cpu: 30.0, memory: 512, instances: 1, isDuplicate: false }
]`
6. **Permissions Error Scenario (Conceptual Response):**
*API Response could be:* `{ success: false, message: 'Access denied. Insufficient privileges to terminate PID 1234.' }`
*UI should display:* A prominent error message and a button to 'Run as Administrator'.
7. **Post Termination State:**
*(If PID 9101 was terminated):*
`[
{ name: 'Google Chrome', pid: 1234, cpu: 5.2, memory: 250, instances: 3, isDuplicate: true },
{ name: 'Visual Studio Code', pid: 5678, cpu: 10.5, memory: 300, instances: 1, isDuplicate: false },
{ name: 'Microsoft Outlook', pid: 9105, cpu: 2.8, memory: 145, instances: 1, isDuplicate: false },
{ name: 'Discord', pid: 1122, cpu: 1.5, memory: 200, instances: 1, isDuplicate: false }
]`
8. **User Settings Example (JSONB):**
`{ "autoRefreshInterval": 10, "notificationsEnabled": true, "theme": "dark" }`
9. **App Ghost Internal Process (if bundled):**
`[{ name: 'AppGhost.exe', pid: 12345, cpu: 1.0, memory: 50, instances: 1, isDuplicate: false }]`
10. **Zombie/Defunct Process Example:**
`[{ name: 'StaleApp (defunct)', pid: 6789, cpu: 0.0, memory: 0, instances: 1, isDuplicate: false }]` (May appear differently depending on OS)