# VoilaJSX AppKit 🚀

[![npm version](https://img.shields.io/npm/v/@voilajsx/appkit.svg)](https://www.npmjs.com/package/@voilajsx/appkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![AI Ready](https://img.shields.io/badge/AI-Optimized-purple.svg)](https://github.com/voilajsx/appkit)

> **Minimal and framework agnostic Node.js toolkit designed for AI agentic
> backend development**

**Zero configuration. Enterprise features by default. Optimized for both human
developers and AI code generation.**

## 🚀 What VoilaJSX AppKit Really Is

VoilaJSX AppKit is a **complete Node.js development toolkit** that eliminates
the complexity of building production-ready applications. Instead of juggling
dozens of libraries and configuration files, you get 12 integrated modules that
work together seamlessly.

### **How Developers Can Leverage AppKit**

**🎯 For Rapid Development**

- **One function per module**: `authClass.get()`, `databaseClass.get()`,
  `securityClass.get()`
- **Instant setup**: No configuration files, just environment variables
- **Production patterns**: Enterprise-grade security and scalability built-in

**🏗️ For Maintainable Architecture**

- **Consistent APIs**: Same `{moduleClass}.get()` pattern across all modules
- **Progressive complexity**: Start simple, scale to enterprise automatically
- **Type-safe**: Full TypeScript support with intelligent IntelliSense

**⚡ For Performance**

- **Smart defaults**: Memory caching, connection pooling, resource management
- **Auto-scaling**: Modules automatically upgrade (Memory → Redis → Database)
- **Optimized**: Battle-tested patterns for high-throughput applications

## 🤖 Enhanced for AI-Driven Development

While perfectly designed for human developers, AppKit excels in AI-assisted
development:

- **🎯 Predictable Code Generation**: AI agents generate consistent, working
  applications
- **📝 LLM-Optimized Documentation**: Every function includes clear usage
  patterns
- **🔒 Built-in Best Practices**: Security, scalability, and maintainability by
  default
- **⚙️ Non-Ambiguous APIs**: Clear function signatures prevent common mistakes

### **Why This Matters for Developers**

| Traditional Approach                      | VoilaJSX AppKit Approach                |
| ----------------------------------------- | --------------------------------------- |
| Research → Configure → Integrate → Secure | **Import → Use → Deploy**               |
| Multiple libraries, version conflicts     | **Integrated modules, tested together** |
| Manual scaling decisions                  | **Environment-driven auto-scaling**     |
| Security implemented later                | **Security enabled by default**         |
| Inconsistent error handling               | **Unified error patterns**              |

## 🏢 Enterprise Benefits

### **Progressive Complexity**

```typescript
// Day 1: Simple development
const auth = authClass.get();
const token = auth.signToken({ userId: 123, role: 'user', level: 'basic' });

// Month 6: Multi-tenant (just add environment variable)
// VOILA_DB_TENANT=auto
const database = await databaseClass.get(); // Now auto-filtered by tenant

// Year 1: Multi-organization enterprise (same code)
// ORG_ACME=postgresql://acme.aws.com/prod
const acmeDatabase = await databaseClass.org('acme').get(); // Enterprise scaling
```

## 🚀 Quick Start for Developers & AI Agents

### **Installation**

```bash
npm install @voilajsx/appkit
```

### **30-Second Working App**

```typescript
import { authClass } from '@voilajsx/appkit/auth';
import { databaseClass } from '@voilajsx/appkit/database';
import { errorClass } from '@voilajsx/appkit/error';
import { loggerClass } from '@voilajsx/appkit/logger';

const auth = authClass.get();
const database = await databaseClass.get();
const error = errorClass.get();
const logger = loggerClass.get('api');

// Protected API endpoint
app.post(
  '/api/users',
  auth.requireRole('admin.tenant'),
  error.asyncRoute(async (req, res) => {
    const user = auth.user(req);

    if (!req.body.email) {
      throw error.badRequest('Email required');
    }

    const newUser = await database.user.create({ data: req.body });
    logger.info('User created', { userId: newUser.id });

    res.json({ user: newUser });
  })
);

// Error handling middleware (must be last)
app.use(error.handleErrors());
```

**Result**: Production-ready API with authentication, database, error handling,
and logging. **Zero configuration needed.**

## 🎭 Complete Module Ecosystem

| #   | Module                                  | Category                | Purpose                            | Details                                                                                                                  |
| --- | --------------------------------------- | ----------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 1   | **[Auth](/src/auth/README.md)**         | 🔧 Infrastructure       | JWT tokens, role-based permissions | `authClass.get()` - Semantic role hierarchy (user.basic → admin.system), automatic middleware, production-grade security |
| 2   | **[Database](/src/database/README.md)** | 🔧 Infrastructure       | Multi-tenant, progressive scaling  | `databaseClass.get()` - Auto-tenant filtering, org management (.org()), mandatory future-proofing with tenant_id         |
| 3   | **[Security](/src/security/README.md)** | 🔧 Infrastructure       | CSRF, rate limiting, encryption    | `securityClass.get()` - Enterprise-grade by default, AES-256-GCM encryption, input sanitization                          |
| 4   | **[Error](/src/error/README.md)**       | 🔧 Infrastructure       | HTTP status codes, semantic errors | `errorClass.get()` - Framework-agnostic middleware, semantic error types (badRequest, unauthorized)                      |
| 5   | **[Cache](/src/cache/README.md)**       | 📊 Data & Communication | Memory → Redis auto-scaling        | `cacheClass.get('namespace')` - Namespace isolation, TTL management, getOrSet pattern                                    |
| 6   | **[Storage](/src/storage/README.md)**   | 📊 Data & Communication | Local → S3/R2 auto-scaling         | `storageClass.get()` - CDN integration, signed URLs, automatic provider detection                                        |
| 7   | **[Queue](/src/queue/README.md)**       | 📊 Data & Communication | Memory → Redis → DB scaling        | `queueClass.get()` - Background jobs, scheduling, retry logic with exponential backoff                                   |
| 8   | **[Email](/src/email/README.md)**       | 📊 Data & Communication | Console → SMTP → Resend            | `emailClass.get()` - Templates, multi-provider, automatic strategy selection                                             |
| 9   | **[Event](/src/event/README.md)**       | 📊 Data & Communication | Memory → Redis distribution        | `eventClass.get('namespace')` - Real-time, pub/sub, wildcard patterns (user.\*)                                          |
| 10  | **[Util](/src/util/README.md)**         | 🛠️ Developer Experience | 12 essential utilities             | `utilClass.get()` - Safe property access (get), performance helpers (debounce, chunk)                                    |
| 11  | **[Config](/src/config/README.md)**     | 🛠️ Developer Experience | Environment variables              | `configClass.get()` - Type-safe, UPPER_SNAKE_CASE convention, validation included                                        |
| 12  | **[Logger](/src/logger/README.md)**     | 🛠️ Developer Experience | Structured logging                 | `loggerClass.get('component')` - Multi-transport, auto-scaling (Console → File → HTTP)                                   |

### **Category Summary**

- **🔧 Infrastructure (4 modules)**: Core application foundation - auth,
  database, security, error handling
- **📊 Data & Communication (5 modules)**: Data flow and external interactions -
  cache, storage, queue, email, events
- **🛠️ Developer Experience (3 modules)**: Development productivity - utilities,
  configuration, logging

## 🌍 Environment-Driven Progressive Scaling

### **Development** (Zero Configuration)

```bash
npm start  # Memory cache, local storage, console logs
```

### **Production** (Auto-Detection)

```bash
# Set these environment variables - everything scales automatically
DATABASE_URL=postgresql://prod-db/app     # → Database persistence
REDIS_URL=redis://prod-cache:6379         # → Distributed cache/queue
AWS_S3_BUCKET=prod-assets                 # → Cloud storage + CDN
RESEND_API_KEY=re_production_key          # → Professional email
VOILA_DB_TENANT=auto                      # → Multi-tenant mode
```

**Same code. Different environment. Enterprise features automatically enabled.**

## 🏢 Enterprise-Ready Examples

### **Multi-Tenant SaaS API**

```typescript
import { authClass } from '@voilajsx/appkit/auth';
import { databaseClass } from '@voilajsx/appkit/database';
import { securityClass } from '@voilajsx/appkit/security';
import { cacheClass } from '@voilajsx/appkit/cache';

const auth = authClass.get();
const database = await databaseClass.get(); // Auto-filtered by tenant
const security = securityClass.get();
const cache = cacheClass.get('api');

// User endpoint (tenant-isolated)
app.get(
  '/api/users',
  auth.requireLogin(),
  security.requests(100, 900000), // Rate limiting
  async (req, res) => {
    const users = await cache.getOrSet(
      'users',
      async () => {
        return await database.user.findMany(); // Only current tenant
      },
      300
    );

    res.json(users);
  }
);

// Admin endpoint (cross-tenant access)
app.get(
  '/api/admin/analytics',
  auth.requireRole('admin.system'),
  async (req, res) => {
    const dbTenants = await databaseClass.getTenants(); // All tenants
    const stats = await dbTenants.user.groupBy({
      by: ['tenant_id'],
      _count: true,
    });

    res.json(stats);
  }
);
```

### **Real-Time Chat Application**

```typescript
import { eventClass } from '@voilajsx/appkit/event';
import { authClass } from '@voilajsx/appkit/auth';
import { databaseClass } from '@voilajsx/appkit/database';

const events = eventClass.get();
const auth = authClass.get();
const database = await databaseClass.get();

// Handle user connections
events.on('user.connected', async (data) => {
  const { userId, socketId } = data;

  // Join user to their rooms
  await events.emit('socket.join', {
    socketId,
    rooms: [`user:${userId}`, `tenant:${data.tenantId}`],
  });
});

// Handle chat messages
events.on('message.send', async (data) => {
  const message = await database.message.create({
    data: {
      content: data.content,
      userId: data.userId,
      roomId: data.roomId,
    },
  });

  // Broadcast to room (tenant-isolated)
  await events.emit('message.broadcast', {
    roomId: data.roomId,
    message: {
      id: message.id,
      content: message.content,
      user: { name: data.userName },
      timestamp: message.createdAt,
    },
  });
});

// REST API integration
app.post('/api/notifications', auth.requireLogin(), async (req, res) => {
  const user = auth.user(req);

  // Send real-time notification
  await events.emit('notification.send', {
    userId: user.userId,
    type: 'info',
    message: req.body.message,
    timestamp: new Date(),
  });

  res.json({ sent: true });
});
```

### **File Upload with Background Processing**

```typescript
import { storageClass } from '@voilajsx/appkit/storage';
import { queueClass } from '@voilajsx/appkit/queue';
import { loggerClass } from '@voilajsx/appkit/logger';
import { securityClass } from '@voilajsx/appkit/security';

const storage = storageClass.get();
const queue = queueClass.get();
const logger = loggerClass.get('upload');
const security = securityClass.get();

// File upload with background processing
app.post(
  '/upload',
  security.requests(10, 60000), // 10 uploads per minute
  async (req, res) => {
    // Sanitize filename
    const safeName = security.input(req.file.originalname);
    const key = `uploads/${Date.now()}-${safeName}`;

    // Store file (auto-detects Local/S3/R2)
    await storage.put(key, req.file.buffer, {
      contentType: req.file.mimetype,
    });

    // Queue background processing
    await queue.add('process-image', {
      key,
      userId: req.user.id,
      originalName: req.file.originalname,
    });

    logger.info('File uploaded', { key, userId: req.user.id });

    res.json({
      url: storage.url(key),
      key,
      processing: true,
    });
  }
);

// Background processing
queue.process('process-image', async (data) => {
  const logger = loggerClass.get('processor');

  try {
    const buffer = await storage.get(data.key);

    // Process image (resize, optimize, etc.)
    const processed = await processImage(buffer);

    // Store processed version
    const processedKey = data.key.replace('.', '-processed.');
    await storage.put(processedKey, processed);

    logger.info('Image processed', {
      original: data.key,
      processed: processedKey,
    });

    return { processedKey };
  } catch (error) {
    logger.error('Processing failed', {
      key: data.key,
      error: error.message,
    });
    throw error;
  }
});
```

## 🤖 AI Agent Integration Examples

### **Prompt for Complete Auth System**

```
Create a Node.js API with user authentication, role-based access control,
and protected admin routes using VoilaJSX AppKit.
```

**AI Agent Output** (guaranteed to work):

```typescript
import { authClass } from '@voilajsx/appkit/auth';
import { errorClass } from '@voilajsx/appkit/error';
import { databaseClass } from '@voilajsx/appkit/database';
import { loggerClass } from '@voilajsx/appkit/logger';

const auth = authClass.get();
const error = errorClass.get();
const database = await databaseClass.get();
const logger = loggerClass.get('auth');

// Login endpoint
app.post(
  '/auth/login',
  error.asyncRoute(async (req, res) => {
    const { email, password } = req.body;

    if (!email || !password) {
      throw error.badRequest('Email and password required');
    }

    const user = await database.user.findUnique({ where: { email } });
    if (!user) {
      throw error.unauthorized('Invalid credentials');
    }

    const isValid = await auth.comparePassword(password, user.password);
    if (!isValid) {
      throw error.unauthorized('Invalid credentials');
    }

    const token = auth.signToken({
      userId: user.id,
      role: user.role,
      level: user.level,
    });

    logger.info('User logged in', { userId: user.id });
    res.json({ token, user: { id: user.id, email: user.email } });
  })
);

// Protected user route
app.get(
  '/api/profile',
  auth.requireLogin(),
  error.asyncRoute(async (req, res) => {
    const user = auth.user(req);
    const profile = await database.user.findUnique({
      where: { id: user.userId },
    });
    res.json(profile);
  })
);

// Admin-only route
app.get(
  '/api/admin/users',
  auth.requireRole('admin.tenant'),
  error.asyncRoute(async (req, res) => {
    const users = await database.user.findMany();
    res.json(users);
  })
);

// Error handling middleware (must be last)
app.use(error.handleErrors());
```

### **Prompt for Multi-Tenant Data API**

```
Build a multi-tenant API where users can only see their organization's data,
but admins can access all organizations.
```

**AI Agent Output**:

```typescript
import { databaseClass } from '@voilajsx/appkit/database';
import { authClass } from '@voilajsx/appkit/auth';
import { errorClass } from '@voilajsx/appkit/error';

const auth = authClass.get();
const error = errorClass.get();

// User data (tenant-isolated)
app.get(
  '/api/projects',
  auth.requireLogin(),
  error.asyncRoute(async (req, res) => {
    const database = await databaseClass.get(); // Auto-filtered by user's tenant
    const projects = await database.project.findMany({
      include: { tasks: true },
    });
    res.json(projects); // Only current tenant's projects
  })
);

// Admin data (cross-tenant)
app.get(
  '/api/admin/all-projects',
  auth.requireRole('admin.system'),
  error.asyncRoute(async (req, res) => {
    const dbTenants = await databaseClass.getTenants(); // All tenants
    const allProjects = await dbTenants.project.findMany({
      include: {
        tasks: true,
        _count: { select: { tasks: true } },
      },
    });
    res.json(allProjects); // All organizations' projects
  })
);

// Organization-specific admin access
app.get(
  '/api/admin/org/:orgId/projects',
  auth.requireRole('admin.org'),
  error.asyncRoute(async (req, res) => {
    const { orgId } = req.params;
    const orgDatabase = await databaseClass.org(orgId).get();
    const projects = await orgDatabase.project.findMany();
    res.json(projects); // Specific organization's projects
  })
);
```

## 🚀 Production Deployment

### **Required Environment Variables**

```bash
# Core Security (Required)
VOILA_AUTH_SECRET=your-super-secure-jwt-secret-minimum-32-chars

# Database (Required)
DATABASE_URL=postgresql://user:pass@host:5432/database

# Production Services (Auto-detected)
REDIS_URL=redis://user:pass@host:6379
AWS_S3_BUCKET=your-bucket
RESEND_API_KEY=re_your_api_key
VOILA_SECURITY_CSRF_SECRET=your-csrf-secret-32-chars

# Multi-tenancy (Optional)
VOILA_DB_TENANT=auto

# Organization Scaling (Optional)
ORG_ACME=postgresql://acme.dedicated.aws.com/prod
ORG_STARTUP=mongodb://startup.azure.com/db
```

### **Docker Production Setup**

```dockerfile
FROM node:18-alpine
WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci --only=production

# Copy application
COPY . .

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1) })"

EXPOSE 3000
CMD ["node", "server.js"]
```

### **Kubernetes Deployment**

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: voila-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: voila-app
  template:
    metadata:
      labels:
        app: voila-app
    spec:
      containers:
        - name: app
          image: my-app:latest
          ports:
            - containerPort: 3000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: app-secrets
                  key: database-url
            - name: REDIS_URL
              valueFrom:
                secretKeyRef:
                  name: app-secrets
                  key: redis-url
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 30
            periodSeconds: 10
```

## 📊 Performance & Scalability

### **Benchmarks**

- **Startup Time**: < 100ms (all modules loaded)
- **Memory Usage**: < 50MB baseline (production)
- **Request Throughput**: 10,000+ req/sec (with Redis)
- **Database Connections**: Automatic pooling and management

### **Scaling Characteristics**

| Environment     | Cache         | Storage     | Queue         | Database      |
| --------------- | ------------- | ----------- | ------------- | ------------- |
| **Development** | Memory        | Local       | Memory        | Single        |
| **Staging**     | Redis         | S3          | Redis         | Single        |
| **Production**  | Redis Cluster | S3/R2 + CDN | Redis Cluster | Read Replicas |
| **Enterprise**  | Multi-region  | Multi-cloud | Distributed   | Multi-tenant  |

## 🧪 Testing & Quality

### **Testing Setup**

```typescript
import { utilClass } from '@voilajsx/appkit/util';
import { loggerClass } from '@voilajsx/appkit/logger';
import { cacheClass } from '@voilajsx/appkit/cache';
import { databaseClass } from '@voilajsx/appkit/database';
import { authClass } from '@voilajsx/appkit/auth';

describe('API Tests', () => {
  beforeEach(() => {
    // Reset modules for clean tests
    utilClass.clearCache();
  });

  afterEach(async () => {
    // Clean up resources
    await loggerClass.clear();
    await cacheClass.clear();
    await databaseClass.clear();
  });

  test('should handle user creation safely', async () => {
    const auth = authClass.get();
    const util = utilClass.get();

    const userData = {
      email: 'test@example.com',
      name: 'Test User',
    };

    // Test safe property access
    const email = util.get(userData, 'email');
    expect(email).toBe('test@example.com');

    // Test JWT token creation
    const token = auth.signToken({
      userId: 123,
      role: 'user',
      level: 'basic',
    });

    expect(token).toBeDefined();

    // Test token verification
    const payload = auth.verifyToken(token);
    expect(payload.userId).toBe(123);
  });
});
```

### **Code Quality Standards**

- **100% TypeScript**: Full type safety across all modules
- **Comprehensive Tests**: Unit, integration, and e2e testing
- **Security Audits**: Regular dependency and vulnerability scanning
- **Performance Monitoring**: Built-in metrics and observability

## 🔍 SEO & Discovery

### **Keywords & Technologies**

- **Node.js Framework**: Enterprise-grade backend development
- **AI Code Generation**: LLM-optimized, agentic programming
- **Multi-tenant SaaS**: Progressive scaling, organization management
- **Zero Configuration**: Environment-driven, production-ready
- **TypeScript Ready**: Full type safety, modern development
- **Microservices**: Modular architecture, independent scaling
- **JWT Authentication**: Role-based access control, security
- **Real-time Applications**: WebSocket support, event-driven, pub/sub
- **Cloud Native**: Docker, Kubernetes, auto-scaling
- **Developer Experience**: Fast development, maintainable code

### **Use Cases**

- **SaaS Applications**: Multi-tenant, progressive scaling
- **API Backends**: RESTful, GraphQL, real-time
- **E-commerce Platforms**: Payments, inventory, user management
- **Content Management**: File handling, media processing
- **Enterprise Applications**: Security, compliance, audit trails
- **Microservices**: Independent, scalable, maintainable
- **AI Applications**: LLM integration, automated workflows
- **Startup MVPs**: Rapid development, production-ready

## 📚 Learning Resources

### **Quick References**

- [🚀 Getting Started Guide](docs/getting-started.md) - Zero to production in 10
  minutes
- [🏗️ Architecture Guide](docs/architecture.md) - How modules work together
- [🔒 Security Best Practices](docs/security.md) - Production-ready security
- [📈 Scaling Guide](docs/scaling.md) - Development to enterprise
- [🤖 AI Integration](docs/ai-integration.md) - LLM code generation patterns

### **Module Documentation**

- [Authentication & Authorization](/src/auth/README.md) - JWT, roles,
  permissions
- [Database & Multi-tenancy](/src/database/README.md) - Progressive scaling,
  organizations
- [File Storage & CDN](/src/storage/README.md) - Local to cloud, automatic
  optimization
- [Caching & Performance](/src/cache/README.md) - Memory to Redis, namespace
  isolation
- [Background Jobs](/src/queue/README.md) - Processing, scheduling, reliability
- [Email & Communications](/src/email/README.md) - Multi-provider, templates
- [Real-time Events](/src/event/README.md) - WebSocket, pub/sub, notifications
- [Security & Compliance](/src/security/README.md) - CSRF, encryption, rate
  limiting
- [Error Handling](/src/error/README.md) - HTTP status codes, semantic errors
- [Logging & Observability](/src/logger/README.md) - Structured, multi-transport
- [Configuration Management](/src/config/README.md) - Environment-driven,
  type-safe
- [Utilities & Helpers](/src/util/README.md) - 12 essential developer tools

## 🌟 Community & Support

### **Getting Help**

- 📖 [Documentation](https://docs.voilajsx.com) - Comprehensive guides and API
  reference
- 💬 [Discord Community](https://discord.gg/voilajsx) - Real-time help and
  discussions
- 🐙 [GitHub Issues](https://github.com/voilajsx/appkit/issues) - Bug reports
  and feature requests
- 🐦 [Twitter Updates](https://twitter.com/voilajsx) - Latest news and tips
- 📧 [Email Support](mailto:support@voilajsx.com) - Direct support for
  enterprises

### **Contributing**

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for:

- 🐛 Bug fixes and improvements
- 📝 Documentation enhancements
- ✨ New module features
- 🧪 Test coverage improvements
- 💡 Feature suggestions

## 📄 License

MIT © [VoilaJSX](https://github.com/voilajsx) - See [LICENSE](LICENSE) for
details.

---

<p align="center">
  <strong>🚀 Built for the AI-first future of software development</strong><br>
  <strong>Where enterprise applications are generated, not written</strong><br><br>
  <a href="https://github.com/voilajsx/appkit">⭐ Star us on GitHub</a> • 
  <a href="https://docs.voilajsx.com">📖 Read the Docs</a>
</p>

---

### **🔖 Tags**

`nodejs` `typescript` `framework` `ai-ready` `enterprise` `multi-tenant` `saas`
`microservices` `jwt-authentication` `zero-config` `production-ready`
`agentic-ai` `llm-optimized` `progressive-scaling` `real-time` `websocket`
`pub-sub` `developer-experience`