diff --git a/server/utils/README.md b/server/utils/README.md new file mode 100644 index 0000000..0415335 --- /dev/null +++ b/server/utils/README.md @@ -0,0 +1,167 @@ +# Server Utilities + +## Startup Log (`startupLog.js`) + +Comprehensive server startup logging utility that displays system information, configuration, and health checks on application boot. + +### Features + +- **ASCII Banner** - Eye-catching branded header with BREEDR logo +- **Application Info** - Version, environment, timestamp, Node.js version +- **Server Configuration** - Port, access URL, database status +- **Directory Status** - Checks existence and write permissions for data/uploads/static directories +- **System Resources** - Hostname, platform, architecture, CPU, memory +- **Process Info** - PID, heap usage, uptime + +### Usage + +```javascript +const { logStartupBanner } = require('./utils/startupLog'); + +app.listen(PORT, '0.0.0.0', () => { + logStartupBanner({ + appName: 'BREEDR', + port: PORT, + environment: process.env.NODE_ENV || 'development', + dataDir: DATA_DIR, + uploadPath: UPLOAD_PATH, + staticPath: STATIC_PATH, + dbStatus: '✓ Connected' + }); +}); +``` + +### Configuration Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `appName` | string | `'BREEDR'` | Application name | +| `port` | number | `3000` | Server port | +| `environment` | string | `'development'` | Environment (development/production) | +| `dataDir` | string | `'./data'` | Data directory path | +| `uploadPath` | string | `'./uploads'` | Uploads directory path | +| `staticPath` | string | `'./static'` | Static assets directory path | +| `dbStatus` | string | `'unknown'` | Database connection status | + +### Exported Functions + +#### `logStartupBanner(config)` + +Displays the complete startup banner with all system information. + +**Parameters:** +- `config` (object) - Configuration options (see table above) + +**Returns:** void + +#### `getSystemInfo()` + +Returns system information object. + +**Returns:** +```javascript +{ + hostname: string, + platform: string, + arch: string, + nodeVersion: string, + cpuCores: number, + totalMemory: string, // in GB + freeMemory: string, // in GB + uptime: string // in seconds +} +``` + +#### `getProcessInfo()` + +Returns current process information. + +**Returns:** +```javascript +{ + pid: number, + heapUsed: string, // in MB + heapTotal: string, // in MB + external: string // in MB +} +``` + +#### `checkDirectories(dirs)` + +Checks directory existence and write permissions. + +**Parameters:** +- `dirs` (array) - Array of `{ name, path }` objects + +**Returns:** +```javascript +{ + [name]: { + exists: boolean, + path: string, + writable: boolean + } +} +``` + +#### `getAppVersion()` + +Reads version from package.json. + +**Returns:** string - Version number or 'unknown' + +### Example Output + +``` +╔══════════════════════════════════════════════════════════╗ +║ ║ +║ ██████╗ ██████╗ ███████╗███████╗██████╗ ██████╗ ║ +║ Dog Breeding Genealogy Management System ║ +╚══════════════════════════════════════════════════════════╝ + +┌─────────────────────────────────────────────────────────┐ +│ 📦 APPLICATION INFO │ +├─────────────────────────────────────────────────────────┤ +│ Version : 0.6.0 │ +│ Environment : production │ +│ Node.js : v18.19.0 │ +└─────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────┐ +│ 🌐 SERVER CONFIGURATION │ +├─────────────────────────────────────────────────────────┤ +│ Port : 3000 │ +│ Access URL : http://localhost:3000 │ +│ Database : ✓ Connected │ +└─────────────────────────────────────────────────────────┘ + +🚀 Server is ready and listening for connections +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### Benefits + +1. **Instant System Visibility** - See all critical system info at startup +2. **Troubleshooting** - Quickly identify configuration or resource issues +3. **Professional Logging** - Clean, organized output for production environments +4. **Directory Health** - Immediate feedback on filesystem permissions +5. **Resource Monitoring** - Memory and process info at a glance + +### Integration Checklist + +- [x] Create `server/utils/startupLog.js` +- [x] Update `server/index.js` to import and call `logStartupBanner()` +- [x] Replace simple console.log startup with comprehensive banner +- [x] Test in development environment +- [ ] Test in production Docker container +- [ ] Verify all directory checks work correctly +- [ ] Update main README.md if needed + +### Future Enhancements + +- [ ] Add color support using chalk or similar library +- [ ] Log to file option for production environments +- [ ] Add API endpoint status checks +- [ ] Display loaded routes count +- [ ] Show database migration status +- [ ] Add startup time measurement \ No newline at end of file