@bloomneo/appkit 1.2.9

package/bin/templates/backend/package.json.template

@@ -0,0 +1,34 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "Backend API with FBCA pattern",
+  "type": "module",
+  "main": "src/api/server.ts",
+  "scripts": {
+    "dev": "nodemon --exec tsx src/api/server.ts",
+    "start": "tsx src/api/server.ts",
+    "build": "tsc",
+    "start:prod": "node dist/api/server.js"
+  },
+  "keywords": [
+    "api",
+    "backend",
+    "fbca"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@bloomneo/appkit": "^1.0.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.4.0",
+    "nodemon": "^3.0.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/bin/templates/backend/src/api/features/welcome/welcome.http.template

@@ -0,0 +1,29 @@
+### Welcome API Testing with Frontend Key
+### Base URL: http://localhost:3000
+### Note: In development, X-Frontend-Key is not required but shown for testing
+
+### 1. Basic hello (without key - should work in dev)
+GET http://localhost:3000/api/welcome
+
+###
+
+### 2. Basic hello (with frontend key)
+GET http://localhost:3000/api/welcome
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 3. Test with wrong key (should fail in production)
+GET http://localhost:3000/api/welcome
+X-Frontend-Key: wrong_key_123
+
+###
+
+### Health Check (not protected)
+GET http://localhost:3000/health
+
+###
+
+### API Info (protected)
+GET http://localhost:3000/api
+X-Frontend-Key: {{frontendKey}}

package/bin/templates/backend/src/api/features/welcome/welcome.route.ts.template

@@ -0,0 +1,36 @@
+/**
+ * Welcome Feature Routes - Express endpoints with AppKit integration
+ * @module {{projectName}}/welcome-routes
+ * @file {{projectName}}/src/api/features/{featureName}/{featureName}.route.ts
+ *
+ * @llm-rule WHEN: Need HTTP endpoints for welcome feature with error handling
+ * @llm-rule AVOID: Adding routes without asyncRoute wrapper - breaks error handling
+ * @llm-rule NOTE: Auto-discovered by api-router.ts using FBCA pattern, exports default Express router
+ */
+
+import express from 'express';
+import { errorClass } from '@bloomneo/appkit/error';
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { welcomeService } from './welcome.service.js';
+
+const router = express.Router();
+const error = errorClass.get();
+const logger = loggerClass.get('welcome-routes');
+
+// GET /api/{featureName} - replies "hello"
+router.get('/', error.asyncRoute(async (_req, res) => {
+  logger.info('GET /api/{featureName} request received');
+  const result = await welcomeService.getHello();
+  res.json(result);
+}));
+
+// GET /api/{featureName}/:name - replies "hello :name"
+router.get('/:name', error.asyncRoute(async (req, res) => {
+  const name = req.params.name;
+  logger.info('GET /api/{featureName}/:name request received', { name });
+
+  const result = await welcomeService.getHelloWithName(name);
+  res.json(result);
+}));
+
+export default router;

package/bin/templates/backend/src/api/features/welcome/welcome.service.ts.template

@@ -0,0 +1,88 @@
+/**
+ * Welcome Feature Service - Business logic with AppKit integration
+ * @module {{projectName}}/welcome-service
+ * @file {{projectName}}/src/api/features/{featureName}/{featureName}.service.ts
+ *
+ * @llm-rule WHEN: Need business logic layer with validation, logging, and config
+ * @llm-rule AVOID: Direct database calls from routes - always use service layer
+ * @llm-rule NOTE: Demonstrates AppKit logger, config, and error patterns for FBCA
+ */
+
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { configClass } from '@bloomneo/appkit/config';
+import { errorClass } from '@bloomneo/appkit/error';
+import type { WelcomeResponse, PersonalizedWelcomeResponse } from './welcome.types.js';
+
+// Initialize AppKit modules following the pattern
+const logger = loggerClass.get('welcome');
+const config = configClass.get();
+const error = errorClass.get();
+
+export const welcomeService = {
+  /**
+   * Get basic hello message
+   */
+  async getHello(): Promise<WelcomeResponse> {
+    try {
+      logger.info('Processing basic hello request');
+
+      // Get default welcome from config (with fallback)
+      const defaultWelcome = config.get('welcome.default', 'hello') as string;
+
+      const result: WelcomeResponse = {
+        message: defaultWelcome,
+        timestamp: new Date().toISOString()
+      };
+
+      logger.info('Basic hello request completed', { result });
+      return result;
+
+    } catch (err) {
+      logger.error('Failed to process basic hello request', { error: err });
+      throw error.serverError('Failed to generate welcome message');
+    }
+  },
+
+  /**
+   * Get hello message with name
+   */
+  async getHelloWithName(name: string): Promise<PersonalizedWelcomeResponse> {
+    try {
+      logger.info('Processing personalized hello request', { name });
+
+      // Validate input
+      if (!name || typeof name !== 'string') {
+        logger.warn('Invalid name provided', { name });
+        throw error.badRequest('Name must be a valid string');
+      }
+
+      if (name.length > 100) {
+        logger.warn('Name too long', { name, length: name.length });
+        throw error.badRequest('Name must be less than 100 characters');
+      }
+
+      // Get welcome format from config
+      const welcomeFormat = config.get('welcome.format', 'hello {name}') as string;
+      const message = welcomeFormat.replace('{name}', name);
+
+      const result = {
+        message,
+        name,
+        timestamp: new Date().toISOString()
+      };
+
+      logger.info('Personalized hello request completed', { name, result });
+      return result;
+
+    } catch (err: any) {
+      // Re-throw AppKit errors as-is
+      if (err.statusCode) {
+        throw err;
+      }
+
+      // Convert other errors to server errors
+      logger.error('Failed to process personalized hello request', { name, error: err });
+      throw error.serverError('Failed to generate personalized welcome message');
+    }
+  }
+};

package/bin/templates/backend/src/api/features/welcome/welcome.types.ts.template

@@ -0,0 +1,18 @@
+/**
+ * Welcome Feature Type Definitions - Shared interfaces and types
+ * @module {{projectName}}/welcome-types
+ * @file {{projectName}}/src/api/features/{featureName}/{featureName}.types.ts
+ *
+ * @llm-rule WHEN: Need type safety for welcome feature data structures
+ * @llm-rule AVOID: Defining types inline - reduces reusability and consistency
+ * @llm-rule NOTE: Shared across service and route layers for type consistency
+ */
+
+export interface WelcomeResponse {
+  message: string;
+  timestamp: string;
+}
+
+export interface PersonalizedWelcomeResponse extends WelcomeResponse {
+  name: string;
+}

package/bin/templates/backend/src/api/lib/api-router.ts.template

@@ -0,0 +1,84 @@
+/**
+ * FBCA Auto-Discovery Router
+ * @module {{projectName}}/api-router
+ * @file {{projectName}}/src/api/lib/api-router.ts
+ *
+ * @llm-rule WHEN: Need automatic API route discovery based on feature directories
+ * @llm-rule AVOID: Manual route registration - defeats FBCA auto-discovery purpose
+ * @llm-rule NOTE: Follows {featureName}/{featureName}.route.ts naming convention for TypeScript or .js for JavaScript
+ */
+
+import express from 'express';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname, join } from 'path';
+import { readdir } from 'fs/promises';
+import { loggerClass } from '@bloomneo/appkit/logger';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export async function createApiRouter() {
+  const router = express.Router();
+  const discoveredRoutes: string[] = [];
+  const logger = loggerClass.get('api-router');
+
+  // API root route - list available endpoints
+  router.get('/', (_req, res) => {
+    res.json({
+      message: 'API Server - Feature-Based Component Architecture',
+      version: '1.0.0',
+      endpoints: {
+        health: '/health',
+        api: '/api',
+        features: discoveredRoutes.map(route => `/api${route}`)
+      },
+      timestamp: new Date().toISOString()
+    });
+  });
+
+  try {
+    // Auto-discover feature routes
+    const featuresPath = join(__dirname, '../features');
+    const features = await readdir(featuresPath, { withFileTypes: true });
+
+    logger.info('🔍 Discovering API routes:');
+
+    for (const feature of features) {
+      if (feature.isDirectory()) {
+        const featureName = feature.name;
+        // Try .ts first, then .js
+        const routeFiles = [
+          join(featuresPath, featureName, `${featureName}.route.ts`),
+          join(featuresPath, featureName, `${featureName}.route.js`)
+        ];
+
+        let loaded = false;
+        for (const routeFile of routeFiles) {
+          try {
+            const fileUrl = pathToFileURL(routeFile).href;
+            const { default: featureRouter } = await import(fileUrl);
+            router.use(`/${featureName}`, featureRouter);
+            discoveredRoutes.push(`/${featureName}`);
+            const fileType = routeFile.endsWith('.ts') ? '.ts' : '.js';
+            logger.info(`  /api/${featureName} -> ${featureName}.route${fileType}`);
+            loaded = true;
+            break;
+          } catch (error) {
+            // Continue to next file type
+          }
+        }
+
+        if (!loaded) {
+          logger.warn(`⚠️  Could not load route for feature "${featureName}"`);
+        }
+      }
+    }
+
+    logger.info('✅ API routes discovered');
+
+  } catch (error) {
+    logger.warn('⚠️ No features directory found');
+  }
+
+  return router;
+}

package/bin/templates/backend/src/api/server.ts.template

@@ -0,0 +1,188 @@
+/**
+ * FBCA Backend API Server with AppKit integration
+ * @module {{projectName}}/server
+ * @file {{projectName}}/src/api/server.ts
+ *
+ * @llm-rule WHEN: Creating backend APIs with Feature-Based Component Architecture
+ * @llm-rule AVOID: Using without AppKit modules - breaks structured logging and error handling
+ * @llm-rule NOTE: Auto-discovers features in features/ directory using naming convention
+ */
+
+import 'dotenv/config';
+import express from 'express';
+import cors from 'cors';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { errorClass } from '@bloomneo/appkit/error';
+import { configClass } from '@bloomneo/appkit/config';
+import { createApiRouter } from './lib/api-router.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Initialize AppKit modules following the pattern
+const logger = loggerClass.get('server');
+const error = errorClass.get();
+const config = configClass.get();
+
+/**
+ * Check if frontend build exists
+ */
+function checkFrontendExists(distPath: string): boolean {
+  try {
+    const indexPath = path.join(distPath, 'index.html');
+    return fs.existsSync(indexPath);
+  } catch {
+    return false;
+  }
+}
+
+const app = express();
+const PORT = config.get('server.port', process.env.PORT || 3000);
+
+// Middleware (following AppKit recommended order)
+app.use(cors());
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// Request logging middleware
+app.use((req, _res, next) => {
+  logger.info('Incoming request', {
+    method: req.method,
+    url: req.url,
+    userAgent: req.get('User-Agent'),
+    ip: req.ip
+  });
+  next();
+});
+
+// Frontend key protection for API routes (excluding /api root and /health)
+app.use('/api', (req, res, next) => {
+  // Skip for specific endpoints
+  if (req.path === '/' || req.path === '') {
+    logger.info('🔓 Frontend key check skipped for /api root');
+    return next();
+  }
+
+  // Skip in development environment
+  if (process.env.NODE_ENV === 'development') {
+    logger.info('🔓 Frontend key check skipped (development mode)');
+    return next();
+  }
+
+  const frontendKey = req.headers['x-frontend-key'] as string;
+  const expectedKey = process.env.VOILA_FRONTEND_KEY;
+
+  // Warn if no key is configured in production
+  if (!expectedKey) {
+    logger.warn('⚠️ VOILA_FRONTEND_KEY not configured in production environment');
+    return next(); // Fail gracefully
+  }
+
+  // Check if frontend key is provided and matches
+  if (!frontendKey) {
+    logger.warn('❌ Frontend key missing in request headers', { url: req.url });
+    return res.status(403).json({
+      error: 'Frontend access key required',
+      message: 'API access requires valid frontend key in X-Frontend-Key header'
+    });
+  }
+
+  if (frontendKey !== expectedKey) {
+    logger.warn('❌ Invalid frontend key provided', {
+      url: req.url,
+      providedKey: frontendKey.substring(0, 8) + '...'
+    });
+    return res.status(403).json({
+      error: 'Invalid frontend access key',
+      message: 'The provided frontend key is not valid'
+    });
+  }
+
+  logger.info('✅ Frontend key validated successfully', { url: req.url });
+  next();
+});
+
+// Health check with AppKit integration
+app.get('/health', error.asyncRoute(async (_req, res) => {
+  logger.info('Health check requested');
+
+  const healthData = {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+    environment: config.get('app.environment', 'development')
+  };
+
+  res.json(healthData);
+}));
+
+// Initialize server with async setup
+async function startServer() {
+  try {
+    logger.info('Initializing server...');
+
+    // API routes with auto-discovery
+    app.use('/api', await createApiRouter());
+
+    // Check if frontend build exists and we're not in API-only dev mode
+    const distPath = path.join(__dirname, '../../dist');
+    const frontendExists = checkFrontendExists(distPath);
+    const isApiOnlyMode = process.env.NODE_ENV !== 'production' && process.env.API_ONLY === 'true';
+
+    logger.info('Frontend check:', { distPath, frontendExists, isApiOnlyMode });
+
+    if (frontendExists && !isApiOnlyMode) {
+      // Serve static files from dist directory (production frontend)
+      logger.info('🌐 Serving frontend from dist directory');
+      app.use(express.static(distPath));
+
+      // SPA fallback - serve index.html for all non-API routes
+      app.get('*', (req, res) => {
+        const indexPath = path.join(distPath, 'index.html');
+        logger.info('Serving SPA route', { path: req.path });
+        res.sendFile(indexPath, (err) => {
+          if (err) {
+            logger.error('Failed to serve index.html', { error: err });
+            res.status(404).json({
+              error: 'Frontend not found',
+              message: 'Frontend files exist but failed to serve'
+            });
+          }
+        });
+      });
+    } else {
+      // Fallback to /api route when no frontend
+      logger.info('🔧 No frontend found, redirecting root to /api');
+      app.get('/', (_req, res) => {
+        logger.info('Root route requested, redirecting to /api');
+        res.redirect('/api');
+      });
+    }
+
+    // AppKit error handling middleware (ALWAYS LAST)
+    app.use(error.handleErrors());
+
+    app.listen(PORT, () => {
+      if (frontendExists) {
+        logger.info(`🚀 Full-stack server running on http://localhost:${PORT}`);
+        logger.info(`🌐 Frontend: http://localhost:${PORT}`);
+      } else {
+        logger.info(`🔧 API-only server running on http://localhost:${PORT}`);
+        logger.info(`🌐 Root: http://localhost:${PORT} → redirects to /api`);
+      }
+      logger.info(`📚 API routes: http://localhost:${PORT}/api`);
+      logger.info(`💊 Health check: http://localhost:${PORT}/health`);
+      logger.info('Server initialization completed successfully');
+    });
+
+  } catch (err: any) {
+    logger.error('Failed to start server', { error: err });
+    logger.error('❌ Server startup failed:', { error: err.message });
+    process.exit(1);
+  }
+}
+
+startServer();

package/bin/templates/backend/tsconfig.api.json.template

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "Node16",
+    "skipLibCheck": true,
+    "moduleResolution": "node16",
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": false,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "src/api/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "src/web"
+  ]
+}

package/bin/templates/backend/tsconfig.json.template

@@ -0,0 +1,40 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "checkJs": false,
+    "declaration": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "removeComments": false,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": false,
+    "noPropertyAccessFromIndexSignature": false,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ],
+  "ts-node": {
+    "esm": true
+  }
+}

package/bin/templates/feature/feature.http.template

@@ -0,0 +1,63 @@
+### {{FeatureName}} API Testing with Frontend Key
+### Base URL: http://localhost:3000
+### Note: In development, X-Frontend-Key is not required but shown for testing
+
+### 1. Get all {{featureName}} (without key - should work in dev)
+GET http://localhost:3000/api/{{featureName}}
+
+###
+
+### 2. Get all {{featureName}} (with frontend key)
+GET http://localhost:3000/api/{{featureName}}
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 3. Create a new {{featureName}} (with frontend key)
+POST http://localhost:3000/api/{{featureName}}
+Content-Type: application/json
+X-Frontend-Key: {{frontendKey}}
+
+{
+  "name": "Sample {{FeatureName}}"
+}
+
+###
+
+### 4. Get {{featureName}} by ID (with frontend key)
+GET http://localhost:3000/api/{{featureName}}/1
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 5. Update {{featureName}} by ID (with frontend key)
+PUT http://localhost:3000/api/{{featureName}}/1
+Content-Type: application/json
+X-Frontend-Key: {{frontendKey}}
+
+{
+  "name": "Updated {{FeatureName}}"
+}
+
+###
+
+### 6. Delete {{featureName}} by ID (with frontend key)
+DELETE http://localhost:3000/api/{{featureName}}/1
+X-Frontend-Key: {{frontendKey}}
+
+###
+
+### 7. Test with wrong key (should fail in production)
+GET http://localhost:3000/api/{{featureName}}
+X-Frontend-Key: wrong_key_123
+
+###
+
+### Health Check (not protected)
+GET http://localhost:3000/health
+
+###
+
+### API Info (protected)
+GET http://localhost:3000/api
+X-Frontend-Key: {{frontendKey}}

package/bin/templates/feature/feature.route.ts.template

@@ -0,0 +1,36 @@
+/**
+ * {{featureName}} Feature Routes - Express endpoints with AppKit integration
+ * @module {{projectName}}/{{featureName}}-routes
+ * @file src/api/features/{{featureName}}/{{featureName}}.route.ts
+ *
+ * @llm-rule WHEN: Need HTTP endpoints for {{featureName}} feature with error handling
+ * @llm-rule AVOID: Adding routes without asyncRoute wrapper - breaks error handling
+ * @llm-rule NOTE: Auto-discovered by router.ts, exports default Express router
+ */
+
+import express from 'express';
+import { errorClass } from '@bloomneo/appkit/error';
+import { loggerClass } from '@bloomneo/appkit/logger';
+import { {{featureName}}Service } from './{{featureName}}.service.js';
+
+const router = express.Router();
+const error = errorClass.get();
+const logger = loggerClass.get('{{featureName}}-routes');
+
+// GET /api/{{featureName}} - Basic {{featureName}} endpoint
+router.get('/', error.asyncRoute(async (_req, res) => {
+  logger.info('GET /api/{{featureName}} request received');
+  const result = await {{featureName}}Service.getAll();
+  res.json(result);
+}));
+
+// GET /api/{{featureName}}/:id - Get specific {{featureName}} by ID
+router.get('/:id', error.asyncRoute(async (req, res) => {
+  const id = req.params.id;
+  logger.info('GET /api/{{featureName}}/:id request received', { id });
+
+  const result = await {{featureName}}Service.getById(id);
+  res.json(result);
+}));
+
+export default router;