feat(insight-cards): add real-time agent-generated insight cards for …

backend/src/app.ts

@@ -47,6 +47,9 @@ import { detectSqlInjection } from './middleware/tenantSecurityMonitor.js';
 import auditAnalyticsRoutes from './routes/auditAnalyticsRoutes.js';
 import smartRateLimitRoutes from './routes/smartRateLimitRoutes.js';
 import tenantSecurityRoutes from './routes/tenantSecurityRoutes.js';
+
+// Insight Cards
+import insightCardsRoutes from './routes/insightCardsRoutes.js';
 import { enhancedAuditMiddleware } from './middleware/enhancedAuditAnalytics.js';
 import { smartRateLimitMiddleware } from './middleware/smartRateLimiter.js';
 import { tenantSecurityGuardMiddleware } from './middleware/tenantSecurityGuard.js';
@@ -175,6 +178,7 @@ app.use('/api/usage', tenantUsageRoutes);
 app.use('/api/audit-analytics', auditAnalyticsRoutes);
 app.use('/api/smart-rate-limit', smartRateLimitRoutes);
 app.use('/api/tenant-security', tenantSecurityRoutes);
+app.use('/api/v1/insight-cards', insightCardsRoutes);
 
 // 404 handler
 app.use((req, res) => {

backend/src/routes/insightCardsRoutes.ts

@@ -0,0 +1,30 @@
+import { Router, Request, Response } from 'express';
+import { insightCardsService } from '../services/insightCardsService.js';
+import { InsightCardsQuerySchema } from '../schemas/insightCardsSchema.js';
+import { authenticateJWT } from '../middlewares/auth.js';
+import { isolateOrganization, authorizeRoles } from '../middlewares/rbac.js';
+import logger from '../utils/logger.js';
+
+const router = Router();
+
+router.use(authenticateJWT);
+router.use(isolateOrganization);
+
+router.get('/', authorizeRoles('EMPLOYER'), async (req: Request, res: Response) => {
+  try {
+    const parsed = InsightCardsQuerySchema.safeParse(req.query);
+    if (!parsed.success) {
+      res.status(400).json({ success: false, error: parsed.error.flatten() });
+      return;
+    }
+
+    const organizationId = req.user!.organizationId;
+    const result = await insightCardsService.generate(organizationId, parsed.data.windowDays);
+    res.json({ success: true, data: result });
+  } catch (error) {
+    logger.error('Failed to generate insight cards', error);
+    res.status(500).json({ success: false, error: 'Internal server error' });
+  }
+});
+
+export default router;

backend/src/schemas/insightCardsSchema.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+export const InsightSeverity = z.enum(['info', 'warning', 'critical']);
+export type InsightSeverity = z.infer<typeof InsightSeverity>;
+
+export const InsightCategory = z.enum([
+  'payroll',
+  'liquidity',
+  'compliance',
+  'workforce',
+  'schedule',
+]);
+export type InsightCategory = z.infer<typeof InsightCategory>;
+
+export const InsightCard = z.object({
+  id: z.string(),
+  title: z.string(),
+  body: z.string(),
+  category: InsightCategory,
+  severity: InsightSeverity,
+  metric: z.string().optional(),
+  metricLabel: z.string().optional(),
+  actionLabel: z.string().optional(),
+  actionRoute: z.string().optional(),
+  generatedAt: z.string().datetime(),
+});
+export type InsightCard = z.infer<typeof InsightCard>;
+
+export const InsightCardsResponse = z.object({
+  cards: z.array(InsightCard),
+  generatedAt: z.string().datetime(),
+  windowDays: z.number().int().positive(),
+});
+export type InsightCardsResponse = z.infer<typeof InsightCardsResponse>;
+
+export const InsightCardsQuerySchema = z.object({
+  windowDays: z.coerce.number().int().positive().max(90).default(30),
+});
+export type InsightCardsQuerySchema = z.infer<typeof InsightCardsQuerySchema>;