Platform Modules Overview

AIV Platform includes 5 core modules that provide production-ready features for enterprise deployment.

Module Summary

Module	Purpose	Tests	Maturity
Daemon Management	Service generation for systemd/launchd	99	8.7/10
Cron Scheduler	Task scheduling with cron expressions	86	8.5/10
Heartbeat	Health monitoring & proactive wake	92	8.0/10
Config Hot-Reload	Live configuration updates	58	8.25/10
Onboarding Wizard	Setup wizard with validation	146	8.5/10

Total: 481 tests with comprehensive coverage.

Architecture

aiv-agents/src/
├── daemon/          # Service management
│   ├── daemon-manager.ts
│   ├── systemd-unit.ts
│   └── launchd-plist.ts
├── cron/            # Task scheduling
│   ├── scheduler.ts
│   ├── cron-parser.ts
│   └── job-runner.ts
├── heartbeat/       # Health monitoring
│   ├── heartbeat-service.ts
│   ├── health-checker.ts
│   └── proactive-wake.ts
├── config/          # Configuration
│   ├── config-manager.ts
│   └── file-watcher.ts
└── onboarding/      # Setup wizard
    ├── wizard.ts
    ├── step-runner.ts
    └── types.ts

Module Integration

The modules work together to provide a robust platform:

┌─────────────────────────────────────────────────────────────┐
│                     AIV Platform                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐  │
│  │  Onboarding │ ──▸ │   Config    │ ──▸ │   Daemon    │  │
│  │   Wizard    │     │  Manager    │     │   Manager   │  │
│  └─────────────┘     └──────┬──────┘     └─────────────┘  │
│                             │                              │
│         ┌───────────────────┼───────────────────┐         │
│         ▼                   ▼                   ▼         │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐  │
│  │    Cron     │     │  Heartbeat  │     │   Agents    │  │
│  │  Scheduler  │     │   Service   │     │   (Packs)   │  │
│  └─────────────┘     └─────────────┘     └─────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Data Flow

1. Onboarding → Creates initial configuration
2. Config Manager → Loads and watches config files
3. Daemon Manager → Generates service files for OS
4. Cron Scheduler → Schedules recurring tasks
5. Heartbeat → Monitors health of all components
6. Agents → Execute business logic

Quick Start by Module

Daemon Management

import { createDaemonManager } from '@aiversum/aiv-agents/daemon';

const daemon = createDaemonManager({
  name: 'my-agent',
  description: 'My custom agent service',
  command: 'node',
  args: ['agent.js'],
});

// Generate systemd unit file
const unitContent = daemon.generateUnit();

// Install the service
await daemon.install();

Cron Scheduler

import { createScheduler } from '@aiversum/aiv-agents/cron';

const scheduler = createScheduler();

// Add a job that runs every 5 minutes
scheduler.addJob({
  id: 'health-check',
  schedule: '*/5 * * * *',
  handler: async () => {
    console.log('Running health check...');
  },
});

// Start the scheduler
scheduler.start();

Heartbeat Service

import { createHeartbeatService } from '@aiversum/aiv-agents/heartbeat';

const heartbeat = createHeartbeatService({
  checkInterval: 30000, // 30 seconds
});

// Register a component
heartbeat.registerComponent('api', async () => {
  const response = await fetch('http://localhost:3000/health');
  return response.ok;
});

// Start monitoring
heartbeat.start();

Config Hot-Reload

import { createConfigManager } from '@aiversum/aiv-agents/config';
import { z } from 'zod';

const ConfigSchema = z.object({
  port: z.number(),
  debug: z.boolean(),
});

const manager = createConfigManager({
  configPath: './config.json',
  hotReload: { enabled: true },
}, ConfigSchema);

// Load and watch
await manager.load();
await manager.startWatching();

// React to changes
manager.on('config:change', ({ changes }) => {
  console.log('Config changed:', changes);
});

Onboarding Wizard

import { createOnboardingWizard } from '@aiversum/aiv-agents/onboarding';

const wizard = createOnboardingWizard();

wizard.on('step:complete', ({ step }) => {
  console.log(`Completed: ${step.name}`);
});

wizard.start();

// Complete steps
await wizard.completeStep(); // Welcome
await wizard.completeStep({ type: 'anthropic', apiKey: '...' }); // Provider
// ... continue with remaining steps

Security Features

All modules implement security best practices:

• Zod Validation - Runtime type checking
• Path Traversal Prevention - Blocks .. and symlink escapes
• Command Whitelisting - Only safe commands allowed
• Secure Permissions - 0o600 for secrets, 0o700 for directories
• Input Sanitization - Null byte and special character filtering

Testing

Each module has comprehensive tests:

# Run all tests
cd aiv-agents && npm test

# Run specific module tests
npm test -- --grep "daemon"
npm test -- --grep "cron"
npm test -- --grep "heartbeat"
npm test -- --grep "config"
npm test -- --grep "onboarding"

Next Steps

Dive deeper into each module:

• Daemon Management - Service lifecycle
• Cron Scheduler - Task scheduling
• Heartbeat - Health monitoring
• Config Hot-Reload - Live updates
• Onboarding Wizard - Setup flow