breedr/server/utils/README.md

# 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