docs: Add documentation for startup log utility

2026-03-10 12:57:32 -05:00
parent 326bf318a1
commit 6e8f747c8a
1 changed files with 167 additions and 0 deletions
--- a/server/utils/README.md
+++ 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