SecureWatch TypeScript Architecture Guide v2.1.1¶

📋 Documentation Navigation: Main README | Quick Start | Deployment Guide | Monorepo Setup

📋 Table of Contents¶

Overview
Type System Architecture
Module Structure
Interface Definitions
API Type Safety
Component Type System
Development Workflow
Error Resolution Guide
Best Practices

🎯 Overview¶

SecureWatch v2.1.1 represents a major milestone in TypeScript architecture excellence, achieving zero compilation errors across all 51+ files. This guide documents the comprehensive type safety improvements that enhance developer experience and enterprise reliability.

Key Achievements¶

✅ Zero TypeScript Errors: Complete elimination of compilation issues
✅ Next.js 15 Compatibility: Full App Router support with async route handlers
✅ Enterprise Type Safety: Comprehensive type coverage for SIEM operations
✅ Developer Experience: Enhanced IntelliSense and error prevention
✅ Module Resolution: Proper import/export handling across packages

🏗️ Type System Architecture¶

Core Type Categories¶

1. Security Event Types¶

// Extended log entry with 100+ security fields
export interface ExtendedLogEntry {
  id: string;
  timestamp: string;
  organization_id: string;
  source_identifier: string;
  source_type: string;
  // ... 95+ additional security fields
  
  // MITRE ATT&CK fields
  attack_technique?: string;
  attack_tactic?: string;
  threat_indicator?: string;
  
  // UEBA fields
  user_risk_score?: number;
  behavior_anomaly?: boolean;
  
  // Compliance fields
  compliance_framework?: string;
  policy_violation?: boolean;
}

// Windows-specific event log types
export interface WindowsEventLogEntry extends Omit<ExtendedLogEntry, 'event_id'> {
  event_id: number; // Override string with number for Windows
  process_id?: number;
  logon_type?: number;
  authentication_package?: string;
}

2. API Response Types¶

// KQL query engine types
export interface KQLQueryRequest {
  query: string;
  timeRange?: TimeRange;
  limit?: number;
  offset?: number;
}

export interface KQLQueryResponse {
  results: ExtendedLogEntry[];
  totalCount: number;
  executionTime: number;
  queryId: string;
}

// Search API endpoints
export interface SearchParams {
  limit?: number;
  offset?: number;
  eventId?: string;
  keywords?: string;
  user?: string;
  sourceIp?: string;
  logLevel?: string;
  timeRangeStart?: string;
  timeRangeEnd?: string;
}

3. Next.js 15 Route Handler Types¶

// Dynamic route parameter handling
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  // Type-safe parameter handling
}

export async function PUT(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const body = await request.json();
  // Strongly typed request/response
}

📦 Module Structure¶

Package Type Declarations¶

KQL Engine (`packages/kql-engine/dist/index.d.ts`)¶

export interface KQLEngine {
  execute(query: string): Promise<any>;
  parse(query: string): any;
}

export class KQLParser {
  constructor();
  parse(query: string): any;
}

export class KQLToOpenSearchTranslator {
  constructor();
  translate(ast: any): any;
}

Shared Utilities (`packages/shared-utils/`)¶

export interface LogEntry {
  id: string;
  timestamp: string;
  source_identifier: string;
  log_file: string;
  message: string;
  enriched_data?: Record<string, unknown>;
}

export interface ApiResponse<T> {
  data: T;
  status: 'success' | 'error';
  message?: string;
  meta?: {
    total?: number;
    page?: number;
    limit?: number;
  };
}

🔌 Interface Definitions¶

Authentication & Authorization¶

export interface User {
  id: string;
  email: string;
  role: 'admin' | 'analyst' | 'viewer';
  permissions: Permission[];
  lastLogin?: string;
  mfaEnabled: boolean;
}

export interface JWTToken {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  tokenType: 'Bearer';
}

Notification System¶

// Real-time notification types
interface RealtimeNotification {
  id: string;
  type: 'critical_alert' | 'security_alert' | 'system_update' | 'integration_alert';
  title: string;
  description: string;
  timestamp: string;
  source: string;
  severity: 'critical' | 'high' | 'medium' | 'low' | 'info' | 'warning';
  actions?: { label: string; onClick: string }[];
  read: boolean;
}

// UI notification adapter
interface Notification {
  id: string;
  type: string;
  title: string;
  description: string;
  timestamp: string;
  source: string;
  severity: string;
  actions: string[];
  read: boolean;
}

// Type adapter function
const convertNotification = (realtimeNotif: RealtimeNotification): Notification => ({
  ...realtimeNotif,
  actions: realtimeNotif.actions?.map(action => action.label) || []
});

🌐 API Type Safety¶

HTTP Client Configuration¶

class ApiClient {
  private baseUrl: string;
  private searchApiUrl: string;

  constructor() {
    this.baseUrl = process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:4000';
    this.searchApiUrl = process.env.NEXT_PUBLIC_SEARCH_API_URL || 'http://localhost:4004';
  }

  async fetchLogs(params: SearchParams = {}): Promise<LogEntry[]> {
    // AbortController pattern for timeout handling
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    const response = await fetch(url, {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' },
      signal: controller.signal,
    });

    clearTimeout(timeoutId);
    return this.transformSearchApiResponse(await response.json());
  }
}

Service Health Types¶

export interface ServiceHealth {
  status: 'healthy' | 'unhealthy' | 'degraded';
  uptime: number;
  version: string;
  timestamp: string;
  dependencies: DependencyHealth[];
}

export interface DependencyHealth {
  name: string;
  status: 'connected' | 'disconnected' | 'error';
  responseTime?: number;
  error?: string;
}

🎨 Component Type System¶

React Component Types¶

// UI Component interfaces
interface ProgressProps {
  value: number;
  max?: number;
  className?: string;
  variant?: 'default' | 'secondary';
}

interface EventsTableProps {
  events: ExtendedLogEntry[];
  loading: boolean;
  onEventSelect: (event: ExtendedLogEntry) => void;
  virtualization?: boolean;
}

// Dashboard widget types
interface StatsCardProps {
  title: string;
  value: string;
  change: string;
  color: 'red' | 'green' | 'blue' | 'orange';
  Icon: React.ComponentType<any>;
}

Hook Types¶

// Real-time notifications hook
export function useRealTimeNotifications(
  callback: (notifications: RealtimeNotification[]) => void
): { isConnected: boolean } {
  const [isConnected, setIsConnected] = useState(false);
  
  useEffect(() => {
    // WebSocket connection logic with type safety
  }, [callback]);

  return { isConnected };
}

// API integration hooks
export function useApiStatus(): {
  searchApi: boolean;
  authService: boolean;
  loading: boolean;
} {
  // Service health monitoring with typed responses
}

🔄 Development Workflow¶

Type Checking Commands¶

# Verify TypeScript compilation across all packages
pnpm run typecheck

# Build all packages with type checking
pnpm run build

# Watch mode for development
pnpm run dev

# Lint TypeScript files
pnpm run lint

# Fix auto-fixable TypeScript issues
pnpm run lint:fix

IDE Configuration¶

// .vscode/settings.json
{
  "typescript.preferences.includePackageJsonAutoImports": "on",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  "editor.codeActionsOnSave": {
    "source.organizeImports": true,
    "source.fixAll.eslint": true
  }
}

⚠️ Error Resolution Guide¶

Common TypeScript Errors Fixed in v2.1.1¶

1. TS2344 - Route Handler Parameter Types¶

Problem: Next.js 15 dynamic route handlers require Promise

// ❌ Before (v2.1.0)
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const { id } = params; // Error: params might be Promise
}

// ✅ After (v2.1.1)
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params; // Correct async handling
}

2. TS2307 - Module Resolution¶

Problem: Missing type declarations for @securewatch/kql-engine

// ✅ Solution: Created packages/kql-engine/dist/index.d.ts
export interface KQLEngine {
  execute(query: string): Promise<any>;
  parse(query: string): any;
}

3. TS2430 - Interface Inheritance Conflicts¶

Problem: WindowsEventLogEntry conflicts with ExtendedLogEntry

// ✅ Solution: Use Omit pattern for type safety
export interface WindowsEventLogEntry extends Omit<ExtendedLogEntry, 'event_id'> {
  event_id: number; // Override string with number for Windows
}

4. TS2345 - Type Compatibility Issues¶

Problem: Notification type mismatches

// ✅ Solution: Type adapter pattern
const convertNotification = (realtimeNotif: RealtimeNotification): Notification => ({
  ...realtimeNotif,
  actions: realtimeNotif.actions?.map(action => action.label) || []
});

📝 Best Practices¶

1. Type Definition Guidelines¶

Use strict interfaces for all API contracts
Implement proper error handling with typed exceptions
Maintain backward compatibility with previous versions
Document complex type relationships with JSDoc comments

2. Module Organization¶

Keep type definitions close to implementation
Use barrel exports for clean import statements
Maintain consistent naming conventions across packages
Implement proper dependency injection patterns

3. Error Prevention¶

Use TypeScript strict mode across all packages
Implement comprehensive unit tests for type safety
Use ESLint rules for TypeScript best practices
Regular dependency updates with type compatibility checks

4. Performance Optimization¶

Lazy load heavy type definitions when possible
Use type-only imports where appropriate
Implement proper tree-shaking for type definitions
Monitor bundle size impact of type definitions

🔮 Future Enhancements¶

Planned Type System Improvements¶

GraphQL Schema Integration: Type-safe GraphQL operations
Real-time Type Validation: Runtime type checking for critical paths
Advanced Generic Types: More sophisticated type relationships
AI-Assisted Type Generation: Automatic type inference from data samples

Research Areas¶

Dependent Types: More precise type relationships
Effect Systems: Track side effects in type system
Gradual Typing: Smooth migration strategies for legacy code
Type-Level Computations: Advanced type-level programming

📞 Support & Contributing¶

Type System Documentation¶

Type Definitions: Comprehensive interface documentation
Error Resolution: Step-by-step troubleshooting guides
Best Practices: Community-driven standards
Migration Guides: Version upgrade instructions

Contributing Guidelines¶

Type Safety First: All new code must include proper types
Documentation: Update type definitions with code changes
Testing: Include type-level tests for complex interfaces
Review Process: Type safety review required for all PRs

Last Updated: December 8, 2025 - v2.1.1 TypeScript Excellence Release

Related Documentation: README.md | DEPLOYMENT_GUIDE.md | MONOREPO_SETUP.md | CHANGELOG.md