# SuperDangerous App Framework

A full-stack TypeScript framework for vibecoding enterprise web and desktop apps — 20+ UI components, WebSocket, Electron, and production services pre-wired.

## 📋 Documentation

### Core Guides

- **[API](./docs/API.md)** - Complete API documentation with best practices
- **[Development](./docs/DEVELOPMENT.md)** - How to build applications with the framework
- **[Architecture](./docs/ARCHITECTURE.md)** - System design and structure

### Features

- **[WebSocket](./docs/WEBSOCKET.md)** - Real-time communication implementation
- **[Desktop](./docs/DESKTOP.md)** - Desktop application support with Electron
- **[Bundling](./docs/BUNDLING.md)** - Desktop bundling guide
- **[AI](./docs/AI.md)** - AI service integration
- **[Patterns](./docs/PATTERNS.md)** - Proven architectural patterns

### Configuration & Testing

- **[Testing](./docs/TESTING.md)** - Testing guidelines and patterns
- **[Logging](./docs/LOGGING.md)** - Logging system documentation
- **[Theme](./docs/THEME.md)** - Theme system and customization
- **[Ports](./docs/PORTS.md)** - Port configuration standards
- **[CORS](./docs/CORS.md)** - 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

```bash
# 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

- Vitest with TypeScript support (framework core)
- Jest with TypeScript support (UI package tests under `ui/`)
- Built-in TestServer class for app testing
- Mock implementations for all services
- Async operation handling
- Port management utilities

## 🚀 Quick Start

```bash
# 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

```typescript
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)

```bash
npm install @superdangerous/app-framework
```

### Import Examples

```javascript
// 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

```typescript
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

```tsx
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

```typescript
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: "user@example.com",
  subject: "Welcome!",
});
```

### Settings Management

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```bash
# 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

```json
// 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:

```typescript
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

```typescript
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

```dockerfile
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

```javascript
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](./docs/DEVELOPMENT.md)

## 🔒 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

```bash
# 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](https://github.com/SuperDangerous/epi-node-process-monitor)

## 📄 License

MIT License - see [LICENSE](./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