@cravern/smart-app

Production-ready backend modules for enterprise applications: MessageLog, Authentication, RBAC, and Dynamic Navigation.

🎯 Overview

The Cravern Smart App package provides four independent, production-ready backend modules that can be used together or separately in your Node.js/Express applications:

1. MessageLog Module - Webhook delivery with Kafka/n8n integration and retry logic
2. Authentication Module - Microsoft OAuth + local login with session management
3. RBAC Module - Multi-tenant role-based access control
4. Dynamic Navigation Module - Database-driven responsive navigation

📦 Installation

npm install @cravern/smart-app

Peer Dependencies

npm install express react react-dom drizzle-orm @neondatabase/serverless

🚀 Quick Start

Using All Modules

import express from 'express';
import * as CravernSmartApp from '@cravern/smart-app';

const app = express();

// Register all module routes
CravernSmartApp.MessageLog.registerRoutes(app);
CravernSmartApp.Auth.registerAuthRoutes(app);
CravernSmartApp.RBAC.registerRBACRoutes(app);
CravernSmartApp.Navigation.registerNavigationRoutes(app);

app.listen(5000);

Using Individual Modules

MessageLog Module

import { MessageLog } from '@cravern/smart-app';

// Start the message delivery daemon
MessageLog.messageLogDaemon.start();

// Register message routes
MessageLog.registerRoutes(app);

// Send a webhook message
const message = await storage.createMessage({
  eventType: "order.created",
  payload: { orderId: "123", total: 99.99 }
});

Authentication Module

import { Auth } from '@cravern/smart-app';

// Register authentication routes
Auth.registerAuthRoutes(app);

// Protect routes
app.get('/api/protected', Auth.requireAuth, (req, res) => {
  res.json({ user: req.user });
});

// Admin-only routes
app.get('/api/admin', Auth.requireAdmin, (req, res) => {
  res.json({ message: 'Admin access granted' });
});

RBAC Module

import { RBAC } from '@cravern/smart-app';

// Register RBAC routes
RBAC.registerRBACRoutes(app);

// Protect with permissions
app.get('/api/users', 
  RBAC.requirePermission('users', 'read'),
  (req, res) => {
    // Handle request
  }
);

// Protect with roles
app.get('/api/system-settings', 
  RBAC.requireRole('system_admin'),
  (req, res) => {
    // Handle request
  }
);

Navigation Module

import { Navigation } from '@cravern/smart-app';

// Register navigation routes
Navigation.registerNavigationRoutes(app);

// Seed navigation data on startup
await Navigation.seedNavigationData();

📚 Module Documentation

MessageLog Module

Handles webhook message delivery with intelligent retry logic:

Features:

• ✅ 90-day message retention with automatic cleanup
• ✅ Intelligent retry logic (30s → 5min → 30min intervals)
• ✅ Kafka and n8n integration support
• ✅ Background daemon for queue processing
• ✅ Monotonic attempt tracking across retries

API Endpoints:

• POST /api/messages - Create message
• GET /api/messages - List messages
• GET /api/messages/:id - Get message details
• POST /api/messages/:id/retry - Retry failed message

Example:

const message = await storage.createMessage({
  eventType: "order.created",
  payload: { orderId: "ORD-123", customerId: "CUST-456", total: 99.99 }
});

Authentication Module

Complete authentication system with Microsoft OAuth and local login:

Features:

• ✅ Microsoft OAuth (Azure AD) integration
• ✅ Local username/password authentication
• ✅ Configurable registration flows
• ✅ Email verification system
• ✅ Session management with bcrypt hashing
• ✅ Multi-layer authentication (session, JWT cookies, Bearer tokens)

API Endpoints:

• POST /api/auth/register - User registration
• POST /api/auth/login - Local login
• GET /auth/microsoft - Microsoft OAuth login
• POST /api/auth/logout - Logout
• GET /api/auth/me - Get current user

Environment Variables:

MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
SESSION_SECRET=your_session_secret

RBAC Module

Enterprise-grade role-based access control with multi-tenant support:

Features:

• ✅ Multi-tenant organization isolation
• ✅ Custom roles and permissions
• ✅ Business units for department organization
• ✅ Security clearance levels (public to top_secret)
• ✅ Row-level security (ScopedStorage)
• ✅ Automatic permission creation for transactions

API Endpoints:

• GET /api/organizations - List organizations
• GET /api/roles - List roles
• GET /api/permissions - List permissions
• POST /api/user-roles - Assign roles to users
• GET /api/business-units - List business units

Example:

// Check user permission
if (req.securityContext?.hasPermission('users', 'delete')) {
  // User has permission
}

// Check user role
if (req.securityContext?.hasRole('admin')) {
  // User is admin
}

Navigation Module

Database-driven responsive navigation with permission filtering:

Features:

• ✅ Database-stored navigation structure
• ✅ Permission-based menu filtering
• ✅ Responsive layouts (Desktop, Tablet, Mobile)
• ✅ Independent menu controls (sidebar vs bottom menu)
• ✅ Icon management with 80+ Lucide icons
• ✅ Transaction-based routing

API Endpoints:

• GET /api/navigation/menu - Get side menu items
• GET /api/navigation/bottom-menu - Get bottom menu items
• GET /api/transactions - List all transactions
• PATCH /api/transactions/:id - Update transaction settings

🗄️ Database Setup

The package uses PostgreSQL with Drizzle ORM:

# Set database URL
export DATABASE_URL=postgresql://user:password@host:port/database

# Push schema to database
npm run db:push

The package automatically:

• Creates all required tables
• Seeds initial RBAC data
• Seeds navigation structure
• Sets up default permissions

🔧 Configuration

Environment Variables

# Database (required for production)
DATABASE_URL=postgresql://...

# Authentication
SESSION_SECRET=your_random_secret
MICROSOFT_CLIENT_ID=your_azure_client_id
MICROSOFT_CLIENT_SECRET=your_azure_secret

# MessageLog Webhooks
WEBHOOK_URL_KAFKA=https://kafka.example.com
WEBHOOK_URL_N8N=https://n8n.example.com/webhook

TypeScript Configuration

{
  "compilerOptions": {
    "types": ["@cravern/smart-app"]
  }
}

🎨 Frontend Components

The package also includes React frontend components:

// Using namespace import
import { Client } from '@cravern/smart-app';

function App() {
  return (
    <Client.DesktopLayout>
      <YourContent />
    </Client.DesktopLayout>
  );
}

// Or using direct subpath imports
import { Settings, UserManagement, IconPicker } from '@cravern/smart-app/client';
import { DesktopLayout } from '@cravern/smart-app/client';

Available components:

• DesktopLayout - Persistent sidebar layout
• TabletLayout - Slide-out sidebar with footer
• MobileLayout - Bottom navigation with "More" sheet
• Settings - Complete settings page with tabs
• UserManagement - User management interface
• IconPicker - Icon selection component
• HelpDialog - Context-sensitive help
• AuthProvider, useAuth - Authentication context and hooks
• useMenuItems, useBottomMenuItems - Navigation hooks

🔄 Updating

To get the latest version:

npm update @cravern/smart-app

Check the CHANGELOG for breaking changes and new features.

📖 Full Documentation

For detailed documentation on each module, see:

• MessageLog Module Documentation
• Authentication Module Documentation
• RBAC Module Documentation
• Navigation Module Documentation
• NPM Publishing Guide

🤝 Contributing

This package is maintained by Cravern. For issues or feature requests, please open an issue on GitHub.

📄 License

MIT License - see LICENSE for details.

🏗️ Built With

• Express.js - Web framework
• TypeScript - Type-safe development
• Drizzle ORM - Database ORM
• PostgreSQL - Database
• React - Frontend framework
• Passport.js - Authentication
• Lucide React - Icons
• Shadcn/ui - UI components

🔗 Links

• GitHub Repository
• npm Package
• Issue Tracker
• Documentation

Made with ❤️ by Cravern