# Task 6.2: Basic Daemon Architecture
**Phase**: 6 - Configuration Foundation & CLI/TUI Parity
**Status**: ✅ COMPLETE (7/7 assignments completed)
**Created**: 2025-07-05
**Updated**: 2025-07-05
**Complexity**: High
**Approach**: Configuration-driven daemon process that manages single multi-folder MCP server lifecycle
**Progress**: 100% complete - All 7 assignments finished with comprehensive testing (127 unit tests passing)
## 📈 **Completed Implementations**
**✅ Complete Architecture** (Assignments 1-7):
- **Configuration System**: Comprehensive daemon config schema with validation and hierarchy support
- **Core Daemon Service**: Event-driven daemon class with DI integration and lifecycle management
- **Process Management**: Robust process lifecycle with auto-restart, exponential backoff, and PID management
- **Health Monitoring**: Configurable health checks with failure handling and status reporting
- **Signal Handling**: Cross-platform signal management with graceful shutdown and config reload
- **Performance Monitoring**: Metrics collection with trend analysis, custom metrics, and threshold alerts
- **CLI Integration**: Complete command-line interface with proper DI and module boundaries
**📊 Implementation Stats**:
- **Files Created**: 13 new source files + 6 comprehensive test suites
- **Lines of Code**: ~3,000 LOC of production code + ~2,200 LOC of tests
- **Test Coverage**: 127 unit tests across all daemon components
- **Platform Support**: Windows and Unix/Linux with platform-specific implementations
- **Configuration Options**: 20+ configurable daemon settings with validation
- **CLI Commands**: 5 daemon management commands with comprehensive options
## 🎯 **Task Objective**
Create configuration-driven daemon that manages single multi-folder MCP server
## 🔍 **Pre-Implementation Checklist**
- [ ] Review existing code in: `src/mcp-server.ts`, `src/domain/`, `src/application/`
- [ ] Identify reusable components: DI container, configuration system, process management patterns
- [ ] Check for similar patterns in: `src/interfaces/cli/`, `src/infrastructure/`
- [ ] Consider platform differences: Windows service vs Unix daemon, signal handling
- [ ] Review related tests: `tests/unit/`, `tests/integration/`
## 📋 **Scope**
- [ ] Daemon reads configuration on startup
- [ ] Configuration drives all daemon behavior
- [ ] Support configuration reload via signals
- [ ] Health checks and restart policies from config
- [ ] Performance monitoring per configuration
## 📚 **Essential Project Context**
### From Completed Work
- Phase 1-5: MCP endpoints, file processing, TUI framework
- Current capabilities: 9 MCP endpoints, FAISS search, Ollama embeddings
- Phase 6 Task 1: Configuration System Foundation (prerequisite)
### Critical Files to Understand
- `src/mcp-server.ts` - Current single-folder MCP server entry point
- `src/di/setup.ts` - Dependency injection configuration
- `src/config/manager-refactored.ts` - Configuration manager
- `src/domain/` - Domain services that need daemon management
- `src/application/` - Application workflows for indexing/monitoring/serving
## 🔗 **Dependencies & Related Work**
### Prerequisite Tasks
- **Task 6.1**: Configuration System Foundation - Must be complete for daemon to read config
### Task Sequence
- **Previous**: Task 6.1 Configuration System Foundation - Provides config loading and validation
- **Current**: Task 6.2 Basic Daemon Architecture - Adds configuration-driven process management
- **Next**: Task 6.3 Extend MCP Server for Multiple Folders - Will use daemon to manage multi-folder server
## 📍 **Context from Roadmap**
### Related User Stories
- **As a user, I want sensible defaults**: System works without any configuration
- **As a user, I want to customize behavior**: Easy configuration for common needs
- **As a power user, I want full control**: Every aspect configurable
- **As a user, I want to add a folder to be shared**: `folder-mcp add ~/Documents`
- **As a user, I want to see all shared folders**: `folder-mcp list`
- **As a user, I want to check configuration**: `folder-mcp config get`
### Configuration System Design
- **Config Schema**: Daemon section with process management options
- **Default Values**: Sensible defaults for port, pidFile, healthCheck intervals, autoRestart
- **Validation Rules**: Port range validation, file path validation, positive integers for intervals
- **Code Updates**: New daemon infrastructure, signal handlers, health monitoring
### Implementation Details
Core Configuration Structure includes:
- **daemon**: Process management (port, pidFile, healthCheck, autoRestart)
- **general**: Basic settings (autoStart, logLevel, telemetry)
- **performance**: Resource limits and monitoring
Configuration follows hierarchy: Defaults → System → User → Environment → Runtime
## 🔧 **Implementation Assignments**
### Assignment 1: Daemon Configuration Schema & Interfaces
**Goal**: Define configuration schema and interfaces for daemon behavior
**Estimated Time**: 4 hours
#### Sub-tasks:
1. [ ] **1.1 Configuration Schema Definition**
```typescript
// In src/config/schema/daemon.ts
export interface DaemonConfig {
enabled: boolean;
port?: number;
pidFile?: string;
healthCheck: {
enabled: boolean;
interval: number;
timeout: number;
retries: number;
};
autoRestart: {
enabled: boolean;
maxRetries: number;
delay: number;
};
performance: {
monitoring: boolean;
metricsInterval: number;
logLevel: 'debug' | 'info' | 'warn' | 'error';
};
}
```
2. [ ] **1.2 Daemon Domain Interfaces**
- Platform considerations: Windows vs Unix signal handling
- Related files: `src/domain/daemon/`, `src/config/interfaces.ts`
3. [ ] **1.3 Configuration Integration**
```typescript
// In src/config/manager-refactored.ts
// Add daemon configuration section
// Validate daemon-specific settings
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/config
# Expected: Build succeeds, config tests pass
```
**Implementation Notes**:
- Daemon config must be optional (enabled: false by default)
- Health check intervals should be reasonable (not too frequent)
- PID file location must be writable by user
- Port selection should avoid conflicts
**Completion Criteria**:
- [x] All sub-tasks complete
- [x] Configuration schema validates correctly
- [x] Default values work out-of-box
- [x] Platform-specific considerations handled
**✅ COMPLETED** (2025-07-05): Assignment 1 successfully implemented with comprehensive daemon configuration schema, interfaces, and validation. All tests passing.
---
### Assignment 2: Core Daemon Class Structure
**Goal**: Create the main daemon class with configuration-driven behavior
**Estimated Time**: 6 hours
#### Sub-tasks:
1. [ ] **2.1 Daemon Domain Service**
```typescript
// In src/domain/daemon/daemon-service.ts
export interface IDaemonService {
start(): Promise<void>;
stop(): Promise<void>;
restart(): Promise<void>;
getStatus(): DaemonStatus;
reload(): Promise<void>;
}
export class DaemonService implements IDaemonService {
constructor(
private config: DaemonConfig,
private mcpServer: IMcpServer,
private logger: ILogger
) {}
}
```
2. [ ] **2.2 Daemon Infrastructure Implementation**
```typescript
// In src/infrastructure/daemon/daemon-provider.ts
export class NodeDaemonProvider implements IDaemonService {
// Platform-specific daemon implementation
// Signal handling for SIGTERM, SIGHUP, etc.
// Process management
}
```
3. [ ] **2.3 DI Container Integration**
```typescript
// In src/di/setup.ts
// Register daemon services
container.register(DaemonServiceToken, {
useFactory: (container) => new DaemonService(...)
});
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/daemon
# Expected: Build succeeds, daemon tests pass
# Platform-specific validation:
# Unix: Check signal handling works
# Windows: Check service-like behavior
```
**Implementation Notes**:
- Daemon should gracefully handle shutdown signals
- Configuration reload should not restart MCP server unnecessarily
- Error handling for daemon operations
- Logging should respect configuration log levels
**Completion Criteria**:
- [x] Daemon class structure complete
- [x] DI integration working
- [x] Platform-specific implementations
- [x] Error handling implemented
**✅ COMPLETED** (2025-07-05): Assignment 2 successfully implemented with DaemonService class, DI integration, comprehensive error handling, and event-driven architecture. All tests passing.
---
### Assignment 3: Process Manager Implementation
**Goal**: Implement process lifecycle management based on configuration
**Estimated Time**: 5 hours
#### Sub-tasks:
1. [ ] **3.1 Process Lifecycle Management**
```typescript
// In src/domain/daemon/process-manager.ts
export class ProcessManager {
async startMcpServer(): Promise<void>;
async stopMcpServer(): Promise<void>;
async restartMcpServer(): Promise<void>;
getProcessStatus(): ProcessStatus;
}
```
2. [ ] **3.2 Configuration-Driven Restart Logic**
```typescript
// Auto-restart logic based on config
// Max retries, delay between attempts
// Exponential backoff for failures
```
3. [ ] **3.3 PID File Management**
```typescript
// In src/infrastructure/daemon/pid-manager.ts
export class PidManager {
writePidFile(path: string, pid: number): Promise<void>;
readPidFile(path: string): Promise<number>;
removePidFile(path: string): Promise<void>;
isProcessRunning(pid: number): boolean;
}
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/daemon/process-manager
# Expected: Process management tests pass
# Manual testing:
# Start daemon, check PID file created
# Stop daemon, check PID file removed
# Kill process, check auto-restart works
```
**Implementation Notes**:
- PID file should be created atomically
- Check if process is already running before starting
- Handle stale PID files gracefully
- Respect maximum retry limits from configuration
**Completion Criteria**:
- [x] Process lifecycle management complete
- [x] Auto-restart logic working
- [x] PID file management implemented
- [x] Configuration properly drives behavior
**✅ COMPLETED** (2025-07-05): Assignment 3 successfully implemented with ProcessManager class, auto-restart logic with exponential backoff, PID file management, and comprehensive process lifecycle control. All tests passing (18 tests).
---
### Assignment 4: Health Monitor Implementation
**Goal**: Create health monitoring system based on configuration
**Estimated Time**: 4 hours
#### Sub-tasks:
1. [ ] **4.1 Health Check Service**
```typescript
// In src/domain/daemon/health-monitor.ts
export interface IHealthMonitor {
startMonitoring(): void;
stopMonitoring(): void;
getHealthStatus(): HealthStatus;
performHealthCheck(): Promise<HealthCheckResult>;
}
```
2. [ ] **4.2 Configuration-Driven Health Checks**
```typescript
// Health check intervals from config
// Timeout and retry logic from config
// Different health check strategies
```
3. [ ] **4.3 Health Check Implementations**
```typescript
// In src/infrastructure/daemon/health-checks.ts
export class McpServerHealthCheck implements IHealthCheck {
// Check if MCP server is responding
// Verify endpoints are accessible
// Check resource usage
}
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/daemon/health-monitor
# Expected: Health monitoring tests pass
# Manual testing:
# Verify health checks run at configured intervals
# Test health check failure triggers restart
# Check health status reporting
```
**Implementation Notes**:
- Health checks should be lightweight
- Failed health checks should trigger configured actions
- Health status should be queryable via daemon interface
- Consider different types of health checks (ping, resource usage, etc.)
**Completion Criteria**:
- [x] Health monitoring service complete
- [x] Configuration-driven check intervals
- [x] Health check failure handling
- [x] Health status reporting working
**✅ COMPLETED** (2025-07-05): Assignment 4 successfully implemented with HealthMonitor class, configurable health checks, failure handling with retry logic, and comprehensive health status reporting. All tests passing (19 tests).
---
### Assignment 5: Signal Handler Implementation
**Goal**: Implement cross-platform signal handling for daemon control
**Estimated Time**: 3 hours
#### Sub-tasks:
1. [ ] **5.1 Signal Handler Service**
```typescript
// In src/domain/daemon/signal-handler.ts
export interface ISignalHandler {
registerHandlers(): void;
handleShutdown(): Promise<void>;
handleReload(): Promise<void>;
}
```
2. [ ] **5.2 Platform-Specific Signal Handling**
```typescript
// In src/infrastructure/daemon/signal-handlers.ts
export class UnixSignalHandler implements ISignalHandler {
// SIGTERM, SIGHUP, SIGINT handling
}
export class WindowsSignalHandler implements ISignalHandler {
// Windows-specific signal handling
}
```
3. [ ] **5.3 Graceful Shutdown Logic**
```typescript
// Graceful shutdown sequence
// Save state before shutdown
// Clean up resources
// Notify dependent services
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/daemon/signal-handler
# Expected: Signal handling tests pass
# Platform-specific validation:
# Unix: kill -TERM <pid> should trigger graceful shutdown
# Unix: kill -HUP <pid> should trigger config reload
# Windows: Ctrl+C should trigger graceful shutdown
```
**Implementation Notes**:
- Signal handlers should be idempotent
- Graceful shutdown should have timeout
- Configuration reload should validate before applying
- Different signals should have different behaviors
**Completion Criteria**:
- [x] Signal handlers implemented
- [x] Platform-specific behavior working
- [x] Graceful shutdown complete
- [x] Configuration reload via signals
**✅ COMPLETED** (2025-07-05): Assignment 5 successfully implemented with SignalHandler class, platform-specific Unix/Windows implementations, graceful shutdown with timeout, and configuration reload via SIGHUP. All tests passing (28 tests).
---
### Assignment 6: Performance Monitor Implementation
**Goal**: Create performance monitoring based on configuration
**Estimated Time**: 3 hours
#### Sub-tasks:
1. [ ] **6.1 Performance Metrics Collection**
```typescript
// In src/domain/daemon/performance-monitor.ts
export interface IPerformanceMonitor {
startMonitoring(): void;
stopMonitoring(): void;
getMetrics(): PerformanceMetrics;
recordMetric(name: string, value: number): void;
}
```
2. [ ] **6.2 Configuration-Driven Monitoring**
```typescript
// Metrics collection intervals from config
// What metrics to collect from config
// Retention policies from config
```
3. [ ] **6.3 System Resource Monitoring**
```typescript
// In src/infrastructure/daemon/system-monitor.ts
export class SystemResourceMonitor {
getCpuUsage(): Promise<number>;
getMemoryUsage(): Promise<MemoryUsage>;
getDiskUsage(): Promise<DiskUsage>;
}
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/daemon/performance-monitor
# Expected: Performance monitoring tests pass
# Manual testing:
# Check metrics are collected at configured intervals
# Verify resource usage reporting
# Test performance data persistence
```
**Implementation Notes**:
- Performance monitoring should be lightweight
- Metrics should be configurable (what to collect)
- Consider memory usage of monitoring itself
- Metrics should be queryable via daemon interface
**Completion Criteria**:
- [x] Performance monitoring implemented
- [x] Configuration-driven behavior
- [x] Resource usage tracking
- [x] Metrics collection working
**✅ COMPLETED** (2025-07-05): Assignment 6 successfully implemented with PerformanceMonitor class, configurable CPU/memory/disk tracking, custom metrics recording, trend analysis, and threshold monitoring. All tests passing (27 tests).
---
### Assignment 7: CLI Integration
**Goal**: Integrate daemon with CLI commands for management
**Estimated Time**: 2 hours
#### Sub-tasks:
1. [ ] **7.1 Daemon CLI Commands**
```typescript
// In src/interfaces/cli/commands/daemon.ts
export class DaemonCommand {
start(): Promise<void>;
stop(): Promise<void>;
restart(): Promise<void>;
status(): Promise<void>;
reload(): Promise<void>;
}
```
2. [ ] **7.2 Status Display**
```typescript
// Display daemon status
// Show configuration-driven settings
// Report health check results
// Show performance metrics
```
3. [ ] **7.3 Configuration Override Support**
```typescript
// CLI flags to override daemon config
// folder-mcp daemon start --port 3001
// folder-mcp daemon start --no-health-check
```
**Validation**:
```bash
npm run build && npm test -- tests/unit/cli/daemon
# Expected: CLI daemon commands work
# Manual testing:
folder-mcp daemon start
folder-mcp daemon status
folder-mcp daemon reload
folder-mcp daemon stop
```
**Implementation Notes**:
- CLI commands should provide clear feedback
- Status command should show comprehensive information
- Error messages should be helpful
- Configuration overrides should be documented
**Completion Criteria**:
- [x] CLI commands implemented
- [x] Status display working
- [x] Configuration overrides supported
- [x] Help documentation complete
**✅ COMPLETED** (2025-07-05): Assignment 7 successfully implemented with comprehensive CLI daemon management commands (start, stop, restart, status, reload), rich status display with table and JSON formats, configuration override support via CLI flags, and proper DI integration with module boundaries. All tests passing (24 tests).
## ✅ **Task Completion Criteria**
From roadmap:
- [x] Daemon respects all configuration settings
- [x] Configuration reload without restart
- [x] Health monitoring uses configured intervals
- [x] Auto-restart follows configuration
- [x] Performance metrics per configuration
Additional requirements:
- [x] All assignments completed
- [x] All tests passing
- [x] Documentation updated
## 🧪 **Testing Requirements**
### Unit Tests
- `tests/unit/daemon/daemon-service.test.ts` - Core daemon functionality
- `tests/unit/daemon/process-manager.test.ts` - Process lifecycle management
- `tests/unit/daemon/health-monitor.test.ts` - Health monitoring
- `tests/unit/daemon/signal-handler.test.ts` - Signal handling
- `tests/unit/daemon/performance-monitor.test.ts` - Performance monitoring
- `tests/unit/cli/daemon.test.ts` - CLI integration
### Integration Tests
- Configuration loading and daemon behavior
- Daemon startup with different configurations
- Signal handling in different scenarios
- Health check failure and recovery
- Performance monitoring integration
### Manual E2E Testing
- User starts daemon with default configuration
- User modifies configuration and reloads daemon
- User checks daemon status and metrics
- User stops daemon gracefully
- System recovers from daemon crashes
### Configuration Test Cases
- **Default Config**: Daemon works with zero configuration
- **Custom Config**: Daemon respects all configuration options
- **Invalid Config**: Proper error messages for invalid daemon settings
## 📊 **Progress Tracking**
### Assignment Status
- [x] Assignment 1: Daemon Configuration Schema & Interfaces ✅ **COMPLETED**
- [x] 1.1 Configuration Schema Definition
- [x] 1.2 Daemon Domain Interfaces
- [x] 1.3 Configuration Integration
- [x] Assignment 2: Core Daemon Class Structure ✅ **COMPLETED**
- [x] 2.1 Daemon Domain Service
- [x] 2.2 Daemon Infrastructure Implementation
- [x] 2.3 DI Container Integration
- [x] Assignment 3: Process Manager Implementation ✅ **COMPLETED**
- [x] 3.1 Process Lifecycle Management
- [x] 3.2 Configuration-Driven Restart Logic
- [x] 3.3 PID File Management
- [x] Assignment 4: Health Monitor Implementation ✅ **COMPLETED**
- [x] 4.1 Health Check Service
- [x] 4.2 Configuration-Driven Health Checks
- [x] 4.3 Health Check Implementations
- [x] Assignment 5: Signal Handler Implementation ✅ **COMPLETED**
- [x] 5.1 Signal Handler Service
- [x] 5.2 Platform-Specific Signal Handling
- [x] 5.3 Graceful Shutdown Logic
- [x] Assignment 6: Performance Monitor Implementation ✅ **COMPLETED**
- [x] 6.1 Performance Metrics Collection
- [x] 6.2 Configuration-Driven Monitoring
- [x] 6.3 System Resource Monitoring
- [x] Assignment 7: CLI Integration ✅ **COMPLETED**
- [x] 7.1 Daemon CLI Commands
- [x] 7.2 Status Display
- [x] 7.3 Configuration Override Support
### Time Tracking
| Assignment | Estimated | Actual | Status | Notes |
|------------|-----------|--------|--------|-------|
| 1: Configuration Schema | 4 hours | | Not Started | |
| 2: Core Daemon Class | 6 hours | | Not Started | |
| 3: Process Manager | 5 hours | | Not Started | |
| 4: Health Monitor | 4 hours | | Not Started | |
| 5: Signal Handler | 3 hours | | Not Started | |
| 6: Performance Monitor | 3 hours | | Not Started | |
| 7: CLI Integration | 2 hours | | Not Started | |
### Implementation Discoveries
[THIS SECTION GETS UPDATED AS WORK PROGRESSES]
- **Key Findings**: [Document what was discovered during implementation]
- **Decisions Made**: [Record important implementation decisions]
- **Changes from Plan**: [Note any deviations from original plan and why]
- **Reusable Patterns**: [Document patterns that could be used elsewhere]
### Platform-Specific Notes
[TRACK PLATFORM-SPECIFIC ISSUES AND SOLUTIONS]
- **Windows**: [Issues/solutions specific to Windows]
- **macOS**: [Issues/solutions specific to macOS]
- **Linux**: [Issues/solutions specific to Linux]
## 🔍 **Quick Reference**
### Key Commands
```bash
# Build and test
npm run build && npm test
# Run specific tests
npm test -- tests/unit/daemon
npm test -- tests/integration/daemon
```
### Common Issues
- **Build errors**: Check imports and types
- **Test failures**: Verify test setup and mocks
- **Signal handling**: Platform-specific behavior differences
- **PID file issues**: Ensure write permissions
---
**To implement this plan:**
Work on each assignment directly according to the specifications provided below.
## 📝 **Living Document Note**
**IMPORTANT**: This task plan is a LIVING DOCUMENT that should be updated throughout implementation:
- Update assignment status as work progresses (Not Started → In Progress → Complete)
- Document discoveries and decisions in the Implementation Discoveries section
- Add platform-specific notes as issues are encountered
- Update time tracking with actual hours spent
- If assignments need to be broken down further, add sub-tasks as needed
- Mark completed items with ✅ and include completion date
When marking an assignment complete, consider adding:
- What was actually implemented (if different from plan)
- Key code snippets showing the solution
- Any patterns that emerged
- Links to relevant commits
