SuperDangerous App Framework

A comprehensive, production-ready framework for building enterprise internal tools and applications with TypeScript, React, and real-time capabilities.

📋 Documentation

Core Guides

• API - Complete API documentation with best practices
• Development - How to build applications with the framework
• Architecture - System design and structure

Features

• WebSocket - Real-time communication implementation
• Desktop - Desktop application support with Tauri
• Bundling - Desktop bundling guide
• AI - AI service integration
• Patterns - Proven architectural patterns

Configuration & Testing

• Testing - Testing guidelines and patterns
• Logging - Logging system documentation
• Theme - Theme system and customization
• Ports - Port configuration standards
• CORS - Dynamic CORS middleware

Test Suite Overview

The framework includes extensive test coverage:

• Unit Tests: 362+ tests covering all core modules
• Integration Tests: API and service integration testing
• TestServer: Built-in test server for application testing
• Mock Services: Comprehensive mocking utilities

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific suites
npm run test:unit
npm run test:integration

# Type checking
npm run typecheck

Test Infrastructure

• Jest with TypeScript support
• Built-in TestServer class for app testing
• Mock implementations for all services
• Async operation handling
• Port management utilities

🚀 Quick Start

# Install framework
npm install @superdangerous/app-framework

# Create your app
mkdir my-app && cd my-app
npm init -y
npm install @superdangerous/app-framework

Minimal Application

import { StandardServer } from "@superdangerous/app-framework";

const server = new StandardServer({
  appName: "My App",
  appVersion: "1.0.0",
  port: 8080,
  enableWebSocket: true,
  onInitialize: async (app) => {
    app.get("/health", (req, res) => res.json({ status: "ok" }));
  },
});

await server.initialize();
await server.start();

✨ Core Features

🖥️ Server Management

• StandardServer - Simplified server setup with Express
• Request Correlation - Automatic request IDs with structured request logging
• Safer Defaults - Request body limits, trust proxy, and sane HTTP timeouts
• Port Management - Automatic port conflict resolution
• Graceful Shutdown - Clean resource cleanup
• Health Checks - Real system metrics (CPU, memory, disk) - informational only
• Startup Banner - Professional application startup display

📝 Logging System

• Dual Logger System - Simple console + production file logging
• Enhanced Logger - File rotation, compression, archiving
• Category-based Logging - Organize logs by service/module
• Log Management - Statistics, cleanup, migration utilities
• Flat Structure - All logs in /data/logs for easy backup/restore

🔌 Real-Time Communication

• WebSocketManager - Unified Socket.IO management with namespace support
• Redis Adapter - Optional Redis adapter for scaling
• Room Management - Built-in room join/leave handlers
• Client Tracking - Track connected clients across namespaces
• Broadcast Options - Selective broadcasting with compression/volatile options
• React Hooks - useSocketIO, useConnectionStatus
• Connection Status - Monitor connection health

🔒 Security & Authentication

• Session Management - Express sessions with Redis support
• Authentication Middleware - Role-based access control
• Input Validation - Zod/Joi schema validation
• File Security - Safe file operations with validation
• CORS Configuration - Cross-origin resource sharing

⚙️ Configuration & Settings

• Settings Service - Dynamic settings with UI generation
• Environment Merging Automatic env variable merging
• File Watching Auto-reload on config file changes
• Change Events EventEmitter for config change tracking
• Common Schemas Pre-built Zod schemas for common configs

📊 Health Monitoring

• HealthCheckService Real system metrics collection
• CPU Metrics Real CPU usage with history tracking
• Memory Metrics Memory usage percentage and details
• Disk Metrics Disk space monitoring (platform-aware)
• Process Metrics Node.js process statistics
• Custom Health Checks Extensible health check framework
• Dependency Checks Monitor external service health
• Informational Only Never interrupts service operation

🔧 Services & Utilities

• Queue Service - Background job processing with persistence
• AI Service - Multi-provider AI integration (OpenAI, Claude)
• Port Utilities - Port availability checking and management
• File Handler - Secure file operations with MIME validation
• Network Service - Network interface discovery
• System Monitor - System resource monitoring

🎨 UI Components Library

Base Components (20+)

• Forms - Input, Select, Checkbox, Radio, Switch, Textarea
• Layout - Card, Dialog, Tabs, Accordion, Separator
• Data Display - Table, Badge, Alert, Progress, Avatar
• Navigation - Button, Dropdown, Context Menu, Navigation Menu
• Feedback - Toast, Tooltip, Popover, Alert Dialog

Advanced Components

• SettingsFramework - Complete settings UI with validation
• LogViewer - Real-time log display with filtering, stack coalescing, ANSI stripping, auto-refresh, archives, and per-level badges
• ConnectionStatus - WebSocket connection monitoring
• AppLayout - Standard application layout with navigation
• RealtimeDataTable - Live updating data tables
• DashboardStats - Metric display cards
• UpdateNotification - Application update notifications

UI bundle note: the UI package bundles ESM-heavy dependencies (react-markdown, remark-gfm, react-syntax-highlighter) for better Jest/Node compatibility. The LogViewer is now single-source and virtualized; legacy variants have been removed.

🧪 Testing Utilities

• TestServer - Standardized test server for integration tests
• Test Utilities - Request helpers, WebSocket testing
• Mock Services - Pre-configured mocks for services

📊 Middleware

• Validation - Request/response validation
• Error Handling - Centralized error management
• File Upload - Secure file upload handling
• OpenAPI - Automatic API documentation
• Health Checks - Liveness/readiness probes
• Rate Limiting - API rate limiting

📦 Installation

Full Framework (Backend + Frontend)

npm install @superdangerous/app-framework

Import Examples

// Backend
import { StandardServer, createLogger } from "@superdangerous/app-framework";

// Frontend UI components
import {
  Button,
  Card,
  useSocketIO,
  useConnectionStatus,
} from "@superdangerous/app-framework/ui";

## 💡 Usage Examples

### REST API with Database

```typescript
import { StandardServer, validate, createLogger } from '@superdangerous/app-framework';
import { z } from 'zod';

const logger = createLogger('API');

const server = new StandardServer({
  appName: 'REST API',
  appVersion: '1.0.0',
  onInitialize: async (app) => {
    // Validation middleware
    const userSchema = z.object({
      name: z.string(),
      email: z.string().email()
    });

    app.post('/api/users', validate(userSchema), async (req, res) => {
      // Validated request body
      const user = await createUser(req.body);
      res.json({ success: true, data: user });
    });
  }
});

Real-Time Dashboard

import {
  StandardServer,
  getWebSocketServer,
} from "@superdangerous/app-framework";

const server = new StandardServer({
  appName: "Dashboard",
  appVersion: "1.0.0",
  enableWebSocket: true,
  onStart: async () => {
    const ws = getWebSocketServer();

    // Stream metrics every second
    setInterval(() => {
      const metrics = collectMetrics();
      ws.broadcast("metrics:update", metrics);
    }, 1000);
  },
});

React WebSocket Integration

import {
  useSocketIO,
  useConnectionStatus,
} from "@superdangerous/app-framework/ui";

function Dashboard() {
  const [state, actions] = useSocketIO();
  const { connected } = useConnectionStatus();
  const [metrics, setMetrics] = useState([]);

  useEffect(() => {
    if (!connected) return;
    const handler = (data) => setMetrics(data);
    actions.on("metrics:update", handler);
    return () => actions.off("metrics:update", handler);
  }, [connected, actions]);

  return <MetricsDisplay data={metrics} />;
}

Background Job Processing

import { QueueService } from "@superdangerous/app-framework";

const queue = new QueueService({
  concurrent: 5,
  persistent: true,
});

queue.registerHandler("send-email", async (job) => {
  await sendEmail(job.data);
});

await queue.addJob("send-email", {
  to: "[email protected]",
  subject: "Welcome!",
});

Settings Management

import { SettingsService } from '@superdangerous/app-framework';

const settings = new SettingsService();

settings.registerCategory({
  id: 'general',
  label: 'General Settings',
  settings: [{
    key: 'app.theme',
    label: 'Theme',
    type: 'select',
    options: ['light', 'dark', 'auto'],
    defaultValue: 'auto'
  }]
});

// React component
<SettingsFramework
  categories={settings.getUISchema()}
  onSave={async (values) => settings.update(values)}
/>

Health Monitoring

import {
  createHealthCheckRouter,
  getHealthCheckService,
} from "@superdangerous/app-framework";

// Add health check endpoints
const healthRouter = createHealthCheckRouter({
  version: "1.0.0",
  customChecks: [
    {
      name: "database",
      check: async () => ({
        name: "database",
        status: (await db.ping()) ? "healthy" : "unhealthy",
      }),
    },
  ],
});

app.use("/api", healthRouter);

// Get real-time metrics
const healthService = getHealthCheckService();
const metrics = await healthService.getMetrics();
console.log(
  `CPU: ${metrics.cpu.usage}%, Memory: ${metrics.memory.percentage}%`,
);

Settings Management

import {
  SettingsService,
  CommonSettingsCategories,
} from "@superdangerous/app-framework";

// Initialize settings service
const settings = new SettingsService({
  filePath: "./settings.json",
  categories: CommonSettingsCategories,
  onSettingChange: async (key, value) => {
    console.log(`Setting ${key} changed to ${value}`);
  },
});

await settings.initialize();

// Get setting value
const port = await settings.get("server.port");

// Update setting
await settings.set("server.port", 8080);

WebSocket Manager

import { getWebSocketManager } from "@superdangerous/app-framework";

// Initialize WebSocket manager
const wsManager = getWebSocketManager({
  cors: { origin: "http://localhost:3000" },
  adapter: "redis", // Optional Redis scaling
  redisUrl: process.env.REDIS_URL,
});

await wsManager.initialize(httpServer);

// Register namespace with handlers
wsManager.registerNamespace("/dashboard", {
  subscribe: (socket, topic) => {
    socket.join(`topic:${topic}`);
    socket.emit("subscribed", { topic });
  },
  unsubscribe: (socket, topic) => {
    socket.leave(`topic:${topic}`);
  },
});

// Broadcast to specific rooms
wsManager.broadcast("update", data, {
  namespace: "/dashboard",
  room: "topic:metrics",
  compress: true,
});

// Get connection stats
const stats = wsManager.getStats();
console.log(`Connected clients: ${stats.totalClients}`);

🏗️ Architecture

Framework Structure:
├── Core Layer
│   ├── StandardServer      # Server management
│   ├── Logger System       # Logging infrastructure
│   ├── Port Utilities      # Port management
│   └── File Handler        # Secure file operations
├── Service Layer
│   ├── WebSocket Server    # Real-time communication
│   ├── Configuration       # Config management
│   ├── Queue Service       # Job processing
│   ├── AI Service          # AI integration
│   └── Settings Service    # Settings management
├── Middleware Layer
│   ├── Authentication      # Auth & sessions
│   ├── Validation         # Input validation
│   ├── Error Handling     # Error management
│   └── Health Checks      # Health monitoring
└── UI Layer
    ├── Base Components    # Core UI elements
    ├── Advanced Components # Complex UI patterns
    ├── Hooks              # React hooks
    └── Utilities          # UI helpers

🔧 Configuration

Environment Variables

# Server
NODE_ENV=production
PORT=8080
HOST=0.0.0.0

# Logging
LOG_LEVEL=info
LOG_DIR=./logs

# Session
SESSION_SECRET=your-secret-key

# Database
DATABASE_URL=postgresql://...

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# AI Services (optional)
OPENAI_API_KEY=sk-...
CLAUDE_API_KEY=sk-ant-...

# WebSocket
WS_PING_INTERVAL=25000
WS_PING_TIMEOUT=60000

Configuration Files

// data/config/app.json
{
  "server": {
    "port": 8080,
    "cors": {
      "origins": ["http://localhost:3000"]
    }
  },
  "features": {
    "enableWebSocket": true,
    "enableMetrics": true
  }
}

📚 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  StandardServerConfig,
  Logger,
  WebSocketClient,
  JobStatus,
  SettingType,
  ApiResponse,
  ValidationSchema,
} from "@superdangerous/app-framework";

import type {
  ButtonProps,
  TableColumn,
  SettingCategory,
  WebSocketHook,
} from "@superdangerous/app-framework/ui";

🧪 Testing

import { TestServer, setupTestServer } from "@superdangerous/app-framework";

describe("API Tests", () => {
  let server: TestServer;

  beforeAll(async () => {
    server = await setupTestServer({
      setupApp: (app) => {
        app.get("/test", (req, res) => res.json({ ok: true }));
      },
    });
  });

  test("endpoint works", async () => {
    const res = await server.request("/test");
    expect(res.body.ok).toBe(true);
  });
});

🚀 Production Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
ENV NODE_ENV=production
HEALTHCHECK CMD curl -f http://localhost:8080/health || exit 1
CMD ["node", "dist/index.js"]

PM2

module.exports = {
  apps: [
    {
      name: "my-app",
      script: "./dist/index.js",
      instances: "max",
      exec_mode: "cluster",
      env: {
        NODE_ENV: "production",
      },
    },
  ],
};

🛠️ Development Tools

• Hot Reload - Automatic restart on changes
• TypeScript - Full type safety
• ESLint - Code quality enforcement
• Prettier - Code formatting
• Jest - Testing framework
• Nodemon - Development server

📖 For AI Assistants

This framework is designed to be AI-friendly. When building applications:

1. Always use StandardServer - Never use deprecated StartupOrchestrator
2. Validate all inputs - Use zod schemas for validation
3. Handle errors properly - Use try-catch and error middleware
4. Use TypeScript - Define interfaces for all data structures
5. Follow the patterns - See Development Guide

🔒 Security

• Input validation on all endpoints
• Secure session management
• File upload restrictions
• Rate limiting support
• CORS configuration
• Environment variable secrets

🛠️ Development Tools

Node Process Monitor

Monitor and manage all your running framework apps from the macOS menu bar.

• Real-time monitoring of all processes started with dev-server
• Grouped by app with hierarchical view of backend/frontend/websocket processes
• Resource tracking - CPU, memory, uptime for each process
• Easy management - Kill individual processes or entire apps
• Lightweight - Built in Rust for minimal overhead

Installation

# Quick install (macOS)
curl -sSL https://raw.githubusercontent.com/EPISENSOR/epi-node-process-monitor/main/install.sh | bash

Learn more: github.com/SuperDangerous/epi-node-process-monitor

📄 License

MIT License - see LICENSE for details

🤝 Support

• Documentation: See /docs folder for all guides
• Issues: Internal issue tracker
• Examples: Check example applications using this framework

Built with ❤️ by SuperDangerous