Appendix C: Code Templates
How to Use This Appendix
This appendix provides production-ready code templates for implementing the 25 patterns across multiple languages and frameworks. All examples are:
- ✅ Production-ready: Not toy examples, actual working code
- ✅ Well-commented: Explains what each section does
- ✅ Copy-paste friendly: Minimal dependencies, easy to adapt
- ✅ Multi-language: React, Node.js, Python, SQL where applicable
- ✅ Best practices: Error handling, validation, security
How to use: 1. Find the pattern you need to implement 2. Copy the relevant code template 3. Adapt to your specific use case 4. Test thoroughly before production
Table of Contents
Frontend Templates (React/TypeScript)
- Progressive Disclosure Component
- Smart Defaults Hook
- Inline Validation Component
- Contextual Help Component
- Error Recovery Form
- Conditional Logic Form
- Adaptive Behavior Hook
- Semantic Autocomplete
- Cascading Dropdowns
Backend Templates (Node.js/Express)
- Domain-Aware Validation Middleware
- Duplicate Detection Service
- Temporal Validation Utility
- State Machine Implementation
- Audit Trail Logger
- Version Control System
- Scheduled Actions (Cron Jobs)
- External Data Integration
- Real-Time Lookup Service
- API-Driven Business Rules
- Webhook Handler
- Cross-System Workflow Orchestrator
Database Templates (SQL)
- Audit Trail Schema
- Version Control Schema
- Master-Detail Relationship Schema
- State Machine Schema
Utilities
- Validation Helpers
- Error Handling Utilities
- API Client Wrapper
- Date/Time Utilities
Frontend Templates (React/TypeScript)
1. Progressive Disclosure Component
Multi-step wizard with validation at each step
// components/WizardForm.tsx
import React, { useState } from 'react';
interface Step {
id: string;
title: string;
component: React.ComponentType<any>;
validate?: (data: any) => Record<string, string>;
}
interface WizardFormProps {
steps: Step[];
onComplete: (data: any) => Promise<void>;
onCancel?: () => void;
}
export const WizardForm: React.FC<WizardFormProps> = ({
steps,
onComplete,
onCancel,
}) => {
const [currentStepIndex, setCurrentStepIndex] = useState(0);
const [formData, setFormData] = useState<any>({});
const [errors, setErrors] = useState<Record<string, string>>({});
const [isSubmitting, setIsSubmitting] = useState(false);
const currentStep = steps[currentStepIndex];
const isFirstStep = currentStepIndex === 0;
const isLastStep = currentStepIndex === steps.length - 1;
const handleNext = async () => {
// Validate current step
if (currentStep.validate) {
const stepErrors = currentStep.validate(formData);
if (Object.keys(stepErrors).length > 0) {
setErrors(stepErrors);
return;
}
}
setErrors({});
if (isLastStep) {
// Submit form
setIsSubmitting(true);
try {
await onComplete(formData);
} catch (error) {
setErrors({ submit: 'Failed to submit form. Please try again.' });
} finally {
setIsSubmitting(false);
}
} else {
// Move to next step
setCurrentStepIndex(currentStepIndex + 1);
}
};
const handleBack = () => {
setErrors({});
setCurrentStepIndex(currentStepIndex - 1);
};
const updateFormData = (updates: any) => {
setFormData({ ...formData, ...updates });
};
const StepComponent = currentStep.component;
return (
<div className="wizard-form">
{/* Progress indicator */}
<div className="wizard-progress">
{steps.map((step, index) => (
<div
key={step.id}
className={`progress-step ${
index === currentStepIndex ? 'active' : ''
} ${index < currentStepIndex ? 'completed' : ''}`}
>
<div className="step-number">{index + 1}</div>
<div className="step-title">{step.title}</div>
</div>
))}
</div>
{/* Current step content */}
<div className="wizard-content">
<h2>{currentStep.title}</h2>
<StepComponent
data={formData}
onChange={updateFormData}
errors={errors}
/>
</div>
{/* Navigation buttons */}
<div className="wizard-actions">
{onCancel && (
<button
type="button"
onClick={onCancel}
className="btn-secondary"
>
Cancel
</button>
)}
{!isFirstStep && (
<button
type="button"
onClick={handleBack}
className="btn-secondary"
disabled={isSubmitting}
>
Back
</button>
)}
<button
type="button"
onClick={handleNext}
className="btn-primary"
disabled={isSubmitting}
>
{isSubmitting
? 'Submitting...'
: isLastStep
? 'Submit'
: 'Next'}
</button>
</div>
</div>
);
};
// Example usage:
//
// const permitSteps: Step[] = [
// {
// id: 'basic',
// title: 'Basic Information',
// component: BasicInfoStep,
// validate: (data) => {
// const errors: any = {};
// if (!data.propertyAddress) errors.propertyAddress = 'Required';
// return errors;
// },
// },
// {
// id: 'details',
// title: 'Project Details',
// component: ProjectDetailsStep,
// },
// {
// id: 'review',
// title: 'Review & Submit',
// component: ReviewStep,
// },
// ];
//
// <WizardForm
// steps={permitSteps}
// onComplete={async (data) => {
// await submitPermit(data);
// }}
// />
2. Smart Defaults Hook
Custom hook for managing smart defaults from user history
// hooks/useSmartDefaults.ts
import { useState, useEffect } from 'react';
interface SmartDefaultsOptions<T> {
storageKey: string;
userId?: string;
defaultValues?: Partial<T>;
persistToBackend?: boolean;
}
export function useSmartDefaults<T extends Record<string, any>>(
options: SmartDefaultsOptions<T>
) {
const { storageKey, userId, defaultValues = {}, persistToBackend = false } = options;
const [defaults, setDefaults] = useState<Partial<T>>(defaultValues);
const [isLoading, setIsLoading] = useState(true);
// Load defaults on mount
useEffect(() => {
loadDefaults();
}, [userId, storageKey]);
const loadDefaults = async () => {
setIsLoading(true);
try {
if (persistToBackend && userId) {
// Load from backend
const response = await fetch(`/api/users/${userId}/preferences/${storageKey}`);
if (response.ok) {
const data = await response.json();
setDefaults({ ...defaultValues, ...data });
}
} else {
// Load from localStorage
const stored = localStorage.getItem(`${storageKey}_${userId || 'default'}`);
if (stored) {
setDefaults({ ...defaultValues, ...JSON.parse(stored) });
}
}
} catch (error) {
console.error('Failed to load smart defaults:', error);
} finally {
setIsLoading(false);
}
};
const updateDefaults = async (updates: Partial<T>) => {
const newDefaults = { ...defaults, ...updates };
setDefaults(newDefaults);
try {
if (persistToBackend && userId) {
// Save to backend
await fetch(`/api/users/${userId}/preferences/${storageKey}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(newDefaults),
});
} else {
// Save to localStorage
localStorage.setItem(
`${storageKey}_${userId || 'default'}`,
JSON.stringify(newDefaults)
);
}
} catch (error) {
console.error('Failed to save smart defaults:', error);
}
};
const clearDefaults = async () => {
setDefaults(defaultValues);
try {
if (persistToBackend && userId) {
await fetch(`/api/users/${userId}/preferences/${storageKey}`, {
method: 'DELETE',
});
} else {
localStorage.removeItem(`${storageKey}_${userId || 'default'}`);
}
} catch (error) {
console.error('Failed to clear smart defaults:', error);
}
};
return {
defaults,
updateDefaults,
clearDefaults,
isLoading,
};
}
// Example usage:
//
// interface PermitFormData {
// contractor: string;
// deckSize: number;
// material: string;
// }
//
// const MyForm = () => {
// const { defaults, updateDefaults } = useSmartDefaults<PermitFormData>({
// storageKey: 'permit_form',
// userId: currentUser.id,
// defaultValues: {
// deckSize: 150,
// material: 'pressure-treated',
// },
// });
//
// const handleSubmit = async (data: PermitFormData) => {
// await submitPermit(data);
// // Learn from this submission
// await updateDefaults(data);
// };
//
// return (
// <form>
// <input defaultValue={defaults.contractor} />
// <input defaultValue={defaults.deckSize} />
// <select defaultValue={defaults.material}>...</select>
// </form>
// );
// };
3. Inline Validation Component
Form field with real-time validation
// components/ValidatedField.tsx
import React, { useState, useEffect } from 'react';
interface ValidationRule {
validate: (value: any) => boolean | Promise<boolean>;
message: string;
}
interface ValidatedFieldProps {
label: string;
name: string;
type?: string;
value: any;
onChange: (name: string, value: any) => void;
rules?: ValidationRule[];
asyncValidation?: (value: any) => Promise<string | null>;
debounceMs?: number;
required?: boolean;
}
export const ValidatedField: React.FC<ValidatedFieldProps> = ({
label,
name,
type = 'text',
value,
onChange,
rules = [],
asyncValidation,
debounceMs = 500,
required = false,
}) => {
const [error, setError] = useState<string>('');
const [isValidating, setIsValidating] = useState(false);
const [touched, setTouched] = useState(false);
// Debounced validation
useEffect(() => {
if (!touched) return;
const timer = setTimeout(() => {
validateField(value);
}, debounceMs);
return () => clearTimeout(timer);
}, [value, touched]);
const validateField = async (fieldValue: any) => {
// Required check
if (required && (!fieldValue || fieldValue.toString().trim() === '')) {
setError('This field is required');
return false;
}
// Sync validation rules
for (const rule of rules) {
const isValid = await rule.validate(fieldValue);
if (!isValid) {
setError(rule.message);
return false;
}
}
// Async validation (e.g., uniqueness check)
if (asyncValidation && fieldValue) {
setIsValidating(true);
try {
const asyncError = await asyncValidation(fieldValue);
if (asyncError) {
setError(asyncError);
return false;
}
} finally {
setIsValidating(false);
}
}
setError('');
return true;
};
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
const newValue = e.target.value;
onChange(name, newValue);
};
const handleBlur = () => {
setTouched(true);
};
return (
<div className="form-field">
<label htmlFor={name}>
{label}
{required && <span className="required">*</span>}
</label>
<input
id={name}
name={name}
type={type}
value={value}
onChange={handleChange}
onBlur={handleBlur}
className={error ? 'error' : ''}
aria-invalid={!!error}
aria-describedby={error ? `${name}-error` : undefined}
/>
{isValidating && (
<span className="validating">Checking...</span>
)}
{error && touched && (
<span id={`${name}-error`} className="error-message">
{error}
</span>
)}
</div>
);
};
// Example validation rules:
const emailRules: ValidationRule[] = [
{
validate: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
message: 'Please enter a valid email address',
},
];
const passwordRules: ValidationRule[] = [
{
validate: (value) => value.length >= 8,
message: 'Password must be at least 8 characters',
},
{
validate: (value) => /[A-Z]/.test(value),
message: 'Password must contain at least one uppercase letter',
},
{
validate: (value) => /[0-9]/.test(value),
message: 'Password must contain at least one number',
},
];
// Example async validation:
const checkUsernameAvailable = async (username: string): Promise<string | null> => {
const response = await fetch(`/api/users/check-username?username=${username}`);
const { available } = await response.json();
return available ? null : 'Username is already taken';
};
// Usage:
// <ValidatedField
// label="Email"
// name="email"
// type="email"
// value={formData.email}
// onChange={updateFormData}
// rules={emailRules}
// required
// />
4. Contextual Help Component
Tooltip/popover with contextual help
// components/ContextualHelp.tsx
import React, { useState, useRef, useEffect } from 'react';
interface ContextualHelpProps {
content: React.ReactNode;
position?: 'top' | 'bottom' | 'left' | 'right';
trigger?: 'hover' | 'click';
icon?: React.ReactNode;
}
export const ContextualHelp: React.FC<ContextualHelpProps> = ({
content,
position = 'top',
trigger = 'hover',
icon = '?',
}) => {
const [isVisible, setIsVisible] = useState(false);
const helpRef = useRef<HTMLDivElement>(null);
const buttonRef = useRef<HTMLButtonElement>(null);
// Close on click outside
useEffect(() => {
if (trigger === 'click') {
const handleClickOutside = (event: MouseEvent) => {
if (
helpRef.current &&
!helpRef.current.contains(event.target as Node) &&
buttonRef.current &&
!buttonRef.current.contains(event.target as Node)
) {
setIsVisible(false);
}
};
document.addEventListener('mousedown', handleClickOutside);
return () => document.removeEventListener('mousedown', handleClickOutside);
}
}, [trigger]);
const handleMouseEnter = () => {
if (trigger === 'hover') setIsVisible(true);
};
const handleMouseLeave = () => {
if (trigger === 'hover') setIsVisible(false);
};
const handleClick = () => {
if (trigger === 'click') setIsVisible(!isVisible);
};
return (
<div className="contextual-help-wrapper">
<button
ref={buttonRef}
type="button"
className="help-icon"
onClick={handleClick}
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
aria-label="Help"
aria-expanded={isVisible}
>
{icon}
</button>
{isVisible && (
<div
ref={helpRef}
className={`help-popover help-popover-${position}`}
role="tooltip"
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
>
<div className="help-content">{content}</div>
</div>
)}
</div>
);
};
// Field with integrated help:
export const FieldWithHelp: React.FC<{
label: string;
helpContent: React.ReactNode;
children: React.ReactNode;
}> = ({ label, helpContent, children }) => {
return (
<div className="field-with-help">
<label>
{label}
<ContextualHelp content={helpContent} />
</label>
{children}
</div>
);
};
// Usage:
// <FieldWithHelp
// label="Routing Number"
// helpContent={
// <div>
// <p>Your routing number is the 9-digit number at the bottom left of your checks.</p>
// <p>Example: 123456789</p>
// <img src="/routing-number-example.png" alt="Routing number location" />
// </div>
// }
// >
// <input type="text" maxLength="9" />
// </FieldWithHelp>
5. Semantic Autocomplete
Autocomplete with intelligent suggestions
// components/SemanticAutocomplete.tsx
import React, { useState, useEffect, useRef } from 'react';
interface AutocompleteOption {
value: string;
label: string;
metadata?: any;
}
interface SemanticAutocompleteProps {
label: string;
name: string;
onSearch: (query: string) => Promise<AutocompleteOption[]>;
onSelect: (option: AutocompleteOption) => void;
placeholder?: string;
minChars?: number;
debounceMs?: number;
maxResults?: number;
}
export const SemanticAutocomplete: React.FC<SemanticAutocompleteProps> = ({
label,
name,
onSearch,
onSelect,
placeholder = 'Start typing...',
minChars = 2,
debounceMs = 300,
maxResults = 10,
}) => {
const [query, setQuery] = useState('');
const [suggestions, setSuggestions] = useState<AutocompleteOption[]>([]);
const [isLoading, setIsLoading] = useState(false);
const [isOpen, setIsOpen] = useState(false);
const [selectedIndex, setSelectedIndex] = useState(-1);
const inputRef = useRef<HTMLInputElement>(null);
const listRef = useRef<HTMLUListElement>(null);
// Debounced search
useEffect(() => {
if (query.length < minChars) {
setSuggestions([]);
setIsOpen(false);
return;
}
const timer = setTimeout(() => {
fetchSuggestions(query);
}, debounceMs);
return () => clearTimeout(timer);
}, [query]);
const fetchSuggestions = async (searchQuery: string) => {
setIsLoading(true);
try {
const results = await onSearch(searchQuery);
setSuggestions(results.slice(0, maxResults));
setIsOpen(results.length > 0);
setSelectedIndex(-1);
} catch (error) {
console.error('Autocomplete search failed:', error);
setSuggestions([]);
} finally {
setIsLoading(false);
}
};
const handleSelect = (option: AutocompleteOption) => {
setQuery(option.label);
setSuggestions([]);
setIsOpen(false);
onSelect(option);
inputRef.current?.blur();
};
const handleKeyDown = (e: React.KeyboardEvent) => {
if (!isOpen) return;
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
setSelectedIndex((prev) =>
prev < suggestions.length - 1 ? prev + 1 : prev
);
break;
case 'ArrowUp':
e.preventDefault();
setSelectedIndex((prev) => (prev > 0 ? prev - 1 : -1));
break;
case 'Enter':
e.preventDefault();
if (selectedIndex >= 0) {
handleSelect(suggestions[selectedIndex]);
}
break;
case 'Escape':
setIsOpen(false);
setSelectedIndex(-1);
break;
}
};
// Scroll selected item into view
useEffect(() => {
if (selectedIndex >= 0 && listRef.current) {
const selectedItem = listRef.current.children[selectedIndex] as HTMLElement;
selectedItem?.scrollIntoView({ block: 'nearest' });
}
}, [selectedIndex]);
return (
<div className="autocomplete-wrapper">
<label htmlFor={name}>{label}</label>
<div className="autocomplete-input-wrapper">
<input
ref={inputRef}
id={name}
type="text"
value={query}
onChange={(e) => setQuery(e.target.value)}
onKeyDown={handleKeyDown}
placeholder={placeholder}
autoComplete="off"
aria-autocomplete="list"
aria-controls={`${name}-listbox`}
aria-expanded={isOpen}
aria-activedescendant={
selectedIndex >= 0 ? `${name}-option-${selectedIndex}` : undefined
}
/>
{isLoading && <span className="loading-indicator">Loading...</span>}
</div>
{isOpen && suggestions.length > 0 && (
<ul
ref={listRef}
id={`${name}-listbox`}
className="autocomplete-suggestions"
role="listbox"
>
{suggestions.map((option, index) => (
<li
key={option.value}
id={`${name}-option-${index}`}
role="option"
aria-selected={index === selectedIndex}
className={index === selectedIndex ? 'selected' : ''}
onClick={() => handleSelect(option)}
onMouseEnter={() => setSelectedIndex(index)}
>
<div className="option-label">{option.label}</div>
{option.metadata && (
<div className="option-metadata">
{JSON.stringify(option.metadata)}
</div>
)}
</li>
))}
</ul>
)}
</div>
);
};
// Example usage with diagnosis codes:
// const DiagnosisAutocomplete = () => {
// const searchDiagnoses = async (query: string) => {
// const response = await fetch(`/api/diagnoses/search?q=${query}`);
// const data = await response.json();
// return data.map((d: any) => ({
// value: d.code,
// label: `${d.code} - ${d.description}`,
// metadata: { category: d.category },
// }));
// };
//
// return (
// <SemanticAutocomplete
// label="Diagnosis"
// name="diagnosis"
// onSearch={searchDiagnoses}
// onSelect={(option) => {
// console.log('Selected diagnosis:', option);
// }}
// minChars={3}
// />
// );
// };
Backend Templates (Node.js/Express)
6. Domain-Aware Validation Middleware
Express middleware for domain-specific validation
// middleware/validation.ts
import { Request, Response, NextFunction } from 'express';
import { z } from 'zod';
// Generic validation middleware using Zod
export const validate = (schema: z.ZodSchema) => {
return async (req: Request, res: Response, next: NextFunction) => {
try {
req.body = await schema.parseAsync(req.body);
next();
} catch (error) {
if (error instanceof z.ZodError) {
return res.status(400).json({
error: 'Validation failed',
details: error.errors.map((err) => ({
field: err.path.join('.'),
message: err.message,
})),
});
}
next(error);
}
};
};
// Domain-specific validators
export class PermitValidators {
// Validate deck permit with zoning rules
static deckPermit = z.object({
propertyAddress: z.string().min(1, 'Property address is required'),
parcelNumber: z.string().regex(/^\d{2}-\d{2}-\d{3}-\d{3}$/, 'Invalid parcel number format'),
deckSize: z.number()
.positive('Deck size must be positive')
.max(500, 'Deck size cannot exceed 500 sq ft'),
zoning: z.enum(['R-1', 'R-2', 'R-3', 'C-1', 'C-2']),
distanceFromProperty: z.number()
.min(10, 'Deck must be at least 10 feet from property line'),
contractorLicense: z.string().regex(/^[A-Z]{3}-\d{6}$/, 'Invalid contractor license format'),
}).refine(
(data) => {
// Domain rule: R-1 zoning requires variance for decks > 150 sq ft
if (data.zoning === 'R-1' && data.deckSize > 150) {
return false;
}
return true;
},
{
message: 'Decks over 150 sq ft require variance in R-1 zones',
path: ['deckSize'],
}
);
// Validate contractor license is active
static async validateContractorLicense(license: string): Promise<boolean> {
const contractor = await db.contractors.findOne({ license });
if (!contractor) {
throw new Error('Contractor license not found');
}
if (!contractor.isActive) {
throw new Error('Contractor license is not active');
}
if (contractor.expirationDate < new Date()) {
throw new Error('Contractor license has expired');
}
return true;
}
}
// Usage in routes:
// router.post('/permits/deck',
// validate(PermitValidators.deckPermit),
// async (req, res) => {
// // Validated data in req.body
// const permit = await createDeckPermit(req.body);
// res.json(permit);
// }
// );
7. Duplicate Detection Service
Service for detecting duplicate records
// services/DuplicateDetectionService.ts
import Fuse from 'fuse.js';
interface DuplicateCheckResult {
isDuplicate: boolean;
matches: any[];
confidence: number;
}
export class DuplicateDetectionService {
// Exact match on unique fields
static async checkExactDuplicate(
collection: string,
uniqueFields: string[],
values: any
): Promise<DuplicateCheckResult> {
const query: any = { $or: [] };
for (const field of uniqueFields) {
if (values[field]) {
query.$or.push({ [field]: values[field] });
}
}
if (query.$or.length === 0) {
return { isDuplicate: false, matches: [], confidence: 0 };
}
const matches = await db[collection].find(query).toArray();
return {
isDuplicate: matches.length > 0,
matches,
confidence: matches.length > 0 ? 1.0 : 0,
};
}
// Fuzzy matching for potential duplicates
static async checkFuzzyDuplicate(
collection: string,
searchFields: string[],
values: any,
threshold: number = 0.8
): Promise<DuplicateCheckResult> {
// Get all records to search
const allRecords = await db[collection].find({}).toArray();
// Configure fuzzy search
const fuse = new Fuse(allRecords, {
keys: searchFields,
threshold: 1 - threshold, // Fuse uses distance, we use similarity
includeScore: true,
});
// Build search pattern
const searchPattern = searchFields
.map((field) => values[field])
.filter(Boolean)
.join(' ');
if (!searchPattern) {
return { isDuplicate: false, matches: [], confidence: 0 };
}
const results = fuse.search(searchPattern);
const matches = results.map((r) => r.item);
const confidence = results[0]?.score ? 1 - results[0].score : 0;
return {
isDuplicate: confidence >= threshold,
matches,
confidence,
};
}
// Customer duplicate check example
static async checkDuplicateCustomer(customerData: {
email?: string;
phone?: string;
name?: string;
address?: string;
}): Promise<DuplicateCheckResult> {
// First check exact duplicates on email/phone
const exactCheck = await this.checkExactDuplicate(
'customers',
['email', 'phone'],
customerData
);
if (exactCheck.isDuplicate) {
return exactCheck;
}
// Then check fuzzy match on name + address
const fuzzyCheck = await this.checkFuzzyDuplicate(
'customers',
['name', 'address'],
customerData,
0.85 // 85% similarity threshold
);
return fuzzyCheck;
}
// Legal conflict of interest check
static async checkConflictOfInterest(
attorneyId: string,
clientName: string,
opposingPartyName: string
): Promise<DuplicateCheckResult> {
// Check if attorney ever represented opposing party
const conflicts = await db.cases.find({
attorneyId,
$or: [
{ clientName: opposingPartyName },
{ opposingPartyName: clientName },
],
}).toArray();
return {
isDuplicate: conflicts.length > 0,
matches: conflicts,
confidence: conflicts.length > 0 ? 1.0 : 0,
};
}
}
// Usage in API:
// router.post('/customers', async (req, res) => {
// const duplicateCheck = await DuplicateDetectionService.checkDuplicateCustomer(req.body);
//
// if (duplicateCheck.isDuplicate) {
// return res.status(409).json({
// error: 'Potential duplicate customer found',
// matches: duplicateCheck.matches,
// confidence: duplicateCheck.confidence,
// });
// }
//
// const customer = await createCustomer(req.body);
// res.json(customer);
// });
8. Audit Trail Logger
Comprehensive audit logging system
// services/AuditLogger.ts
interface AuditLogEntry {
timestamp: Date;
userId: string;
userName: string;
action: 'create' | 'read' | 'update' | 'delete';
entityType: string;
entityId: string;
changes?: {
before: any;
after: any;
};
metadata?: {
ipAddress?: string;
userAgent?: string;
sessionId?: string;
[key: string]: any;
};
}
export class AuditLogger {
// Log any action
static async log(entry: Omit<AuditLogEntry, 'timestamp'>): Promise<void> {
const auditEntry: AuditLogEntry = {
timestamp: new Date(),
...entry,
};
await db.auditLog.insertOne(auditEntry);
// Also log to external service for compliance
if (process.env.AUDIT_WEBHOOK_URL) {
await fetch(process.env.AUDIT_WEBHOOK_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(auditEntry),
}).catch((err) => {
console.error('Failed to send audit log to webhook:', err);
});
}
}
// Create action
static async logCreate(
userId: string,
userName: string,
entityType: string,
entityId: string,
data: any,
metadata?: any
): Promise<void> {
await this.log({
userId,
userName,
action: 'create',
entityType,
entityId,
changes: {
before: null,
after: data,
},
metadata,
});
}
// Update action with before/after diff
static async logUpdate(
userId: string,
userName: string,
entityType: string,
entityId: string,
before: any,
after: any,
metadata?: any
): Promise<void> {
await this.log({
userId,
userName,
action: 'update',
entityType,
entityId,
changes: { before, after },
metadata,
});
}
// Delete action
static async logDelete(
userId: string,
userName: string,
entityType: string,
entityId: string,
data: any,
metadata?: any
): Promise<void> {
await this.log({
userId,
userName,
action: 'delete',
entityType,
entityId,
changes: {
before: data,
after: null,
},
metadata,
});
}
// Read action (for sensitive data)
static async logRead(
userId: string,
userName: string,
entityType: string,
entityId: string,
metadata?: any
): Promise<void> {
await this.log({
userId,
userName,
action: 'read',
entityType,
entityId,
metadata,
});
}
// Get audit trail for entity
static async getAuditTrail(
entityType: string,
entityId: string
): Promise<AuditLogEntry[]> {
return await db.auditLog
.find({ entityType, entityId })
.sort({ timestamp: -1 })
.toArray();
}
// Search audit logs
static async searchAuditLogs(filters: {
userId?: string;
entityType?: string;
action?: string;
startDate?: Date;
endDate?: Date;
}): Promise<AuditLogEntry[]> {
const query: any = {};
if (filters.userId) query.userId = filters.userId;
if (filters.entityType) query.entityType = filters.entityType;
if (filters.action) query.action = filters.action;
if (filters.startDate || filters.endDate) {
query.timestamp = {};
if (filters.startDate) query.timestamp.$gte = filters.startDate;
if (filters.endDate) query.timestamp.$lte = filters.endDate;
}
return await db.auditLog.find(query).sort({ timestamp: -1 }).toArray();
}
}
// Express middleware to auto-log requests
export const auditMiddleware = (req: Request, res: Response, next: NextFunction) => {
const originalJson = res.json;
---
## Further Reading
### Code Template Libraries
**Frontend:**
- React: https://react.dev/learn
- Official React documentation and examples
- Vue.js: https://vuejs.org/guide/
- Vue.js guide with code examples
- Bootstrap: https://getbootstrap.com/docs/
- UI component templates
**Backend:**
- Express.js: https://expressjs.com/en/starter/examples.html
- Node.js web framework examples
- Django: https://docs.djangoproject.com/en/stable/intro/tutorial01/
- Python web framework tutorial
- Spring Boot: https://spring.io/guides
- Java application templates
### Code Quality
**Clean Code:**
- Martin, R. C. (2008). *Clean Code*. Prentice Hall.
- Writing maintainable, readable code
- Fowler, M. (2018). *Refactoring* (2nd ed.). Addison-Wesley.
- Improving code structure
**Code Review:**
- Atwood, J., et al. "Best practices for code review." Stack Exchange.
- GitHub Code Review Guidelines: https://github.com/features/code-review
### Using These Templates
**Adaptation:**
1. Copy template to your project
2. Rename variables/types to match your domain
3. Add domain-specific validation logic
4. Test thoroughly with your data
5. Refactor as needed
**Warning:** These are starting points, not production-ready code. Always:
- Review security implications
- Add appropriate error handling
- Write tests
- Follow your team's coding standards
### Code Repositories
- GitHub: https://github.com/
- Search for pattern implementations
- CodePen: https://codepen.io/
- Frontend code examples
- Stack Overflow: https://stackoverflow.com/
- Q&A with code examples
---
res.json = function (data) {
// Log after successful response
if (res.statusCode >= 200 && res.statusCode < 300) {
const action = req.method === 'POST' ? 'create'
: req.method === 'PUT' || req.method === 'PATCH' ? 'update'
: req.method === 'DELETE' ? 'delete'
: 'read';
// Extract entity info from route
const entityMatch = req.path.match(/\/api\/(\w+)\/?([\w-]+)?/);
const entityType = entityMatch?.[1] || 'unknown';
const entityId = entityMatch?.[2] || req.body?.id || data?.id || 'unknown';
AuditLogger.log({
userId: req.user?.id || 'anonymous',
userName: req.user?.name || 'Anonymous',
action,
entityType,
entityId,
metadata: {
ipAddress: req.ip,
userAgent: req.get('user-agent'),
path: req.path,
method: req.method,
},
}).catch((err) => console.error('Audit logging failed:', err));
}
return originalJson.call(this, data);
};
next();
};
// Usage:
// app.use(auditMiddleware);
//
// or explicit logging:
// await AuditLogger.logUpdate(
// req.user.id,
// req.user.name,
// 'permit',
// permit.id,
// oldPermit,
// updatedPermit,
// { ipAddress: req.ip }
// );
9. Scheduled Actions (Cron Jobs)
Scheduled task management
// services/ScheduledActions.ts
import cron from 'node-cron';
import { sendEmail } from './EmailService';
export class ScheduledActions {
private static tasks: Map<string, cron.ScheduledTask> = new Map();
// Start all scheduled tasks
static initialize() {
console.log('Initializing scheduled tasks...');
// Permit expiration reminders (daily at 9 AM)
this.schedule('permit-expiration-reminders', '0 9 * * *', async () => {
await this.sendPermitExpirationReminders();
});
// Invoice generation (1st of every month at midnight)
this.schedule('monthly-invoices', '0 0 1 * *', async () => {
await this.generateMonthlyInvoices();
});
// Cleanup old audit logs (weekly on Sunday at 2 AM)
this.schedule('cleanup-audit-logs', '0 2 * * 0', async () => {
await this.cleanupOldAuditLogs();
});
// Data backup (daily at 3 AM)
this.schedule('daily-backup', '0 3 * * *', async () => {
await this.performDailyBackup();
});
console.log(`${this.tasks.size} scheduled tasks initialized`);
}
// Schedule a task
private static schedule(
name: string,
cronExpression: string,
task: () => Promise<void>
) {
const scheduledTask = cron.schedule(cronExpression, async () => {
console.log(`[${new Date().toISOString()}] Running task: ${name}`);
try {
await task();
console.log(`[${new Date().toISOString()}] Task completed: ${name}`);
} catch (error) {
console.error(`[${new Date().toISOString()}] Task failed: ${name}`, error);
// Alert ops team
await this.alertOps({
task: name,
error: error.message,
timestamp: new Date(),
});
}
});
this.tasks.set(name, scheduledTask);
console.log(`Scheduled task: ${name} (${cronExpression})`);
}
// Permit expiration reminders
private static async sendPermitExpirationReminders() {
const thirtyDaysFromNow = new Date();
thirtyDaysFromNow.setDate(thirtyDaysFromNow.getDate() + 30);
const sevenDaysFromNow = new Date();
sevenDaysFromNow.setDate(sevenDaysFromNow.getDate() + 7);
// 30-day reminders
const permits30Days = await db.permits.find({
expirationDate: {
$gte: new Date(thirtyDaysFromNow.setHours(0, 0, 0, 0)),
$lt: new Date(thirtyDaysFromNow.setHours(23, 59, 59, 999)),
},
status: 'active',
reminder30DaysSent: { $ne: true },
}).toArray();
for (const permit of permits30Days) {
await sendEmail({
to: permit.applicantEmail,
subject: 'Permit Expiring in 30 Days',
template: 'permit-expiration-30days',
data: { permit },
});
await db.permits.updateOne(
{ _id: permit._id },
{ $set: { reminder30DaysSent: true } }
);
}
// 7-day reminders
const permits7Days = await db.permits.find({
expirationDate: {
$gte: new Date(sevenDaysFromNow.setHours(0, 0, 0, 0)),
$lt: new Date(sevenDaysFromNow.setHours(23, 59, 59, 999)),
},
status: 'active',
reminder7DaysSent: { $ne: true },
}).toArray();
for (const permit of permits7Days) {
await sendEmail({
to: permit.applicantEmail,
subject: 'URGENT: Permit Expiring in 7 Days',
template: 'permit-expiration-7days',
data: { permit },
});
await db.permits.updateOne(
{ _id: permit._id },
{ $set: { reminder7DaysSent: true } }
);
}
console.log(
`Sent ${permits30Days.length} 30-day and ${permits7Days.length} 7-day expiration reminders`
);
}
// Generate monthly invoices
private static async generateMonthlyInvoices() {
const lastMonth = new Date();
lastMonth.setMonth(lastMonth.getMonth() - 1);
const customers = await db.customers.find({ subscriptionActive: true }).toArray();
for (const customer of customers) {
const invoice = await generateInvoice({
customerId: customer._id,
period: lastMonth,
});
await sendEmail({
to: customer.email,
subject: `Invoice for ${lastMonth.toLocaleDateString('en-US', { month: 'long', year: 'numeric' })}`,
template: 'monthly-invoice',
data: { customer, invoice },
attachments: [
{
filename: `invoice-${invoice.number}.pdf`,
content: await generateInvoicePDF(invoice),
},
],
});
}
console.log(`Generated ${customers.length} monthly invoices`);
}
// Cleanup old audit logs
private static async cleanupOldAuditLogs() {
const retentionDays = 365; // Keep 1 year
const cutoffDate = new Date();
cutoffDate.setDate(cutoffDate.getDate() - retentionDays);
const result = await db.auditLog.deleteMany({
timestamp: { $lt: cutoffDate },
});
console.log(`Deleted ${result.deletedCount} audit logs older than ${retentionDays} days`);
}
// Perform daily backup
private static async performDailyBackup() {
// Backup logic here
console.log('Daily backup completed');
}
// Alert ops team
private static async alertOps(alert: any) {
await sendEmail({
to: process.env.OPS_EMAIL,
subject: `Scheduled Task Failure: ${alert.task}`,
template: 'ops-alert',
data: alert,
});
}
// Stop all tasks (for graceful shutdown)
static shutdown() {
console.log('Stopping all scheduled tasks...');
this.tasks.forEach((task, name) => {
task.stop();
console.log(`Stopped task: ${name}`);
});
this.tasks.clear();
}
}
// Initialize in app startup:
// ScheduledActions.initialize();
//
// Graceful shutdown:
// process.on('SIGTERM', () => {
// ScheduledActions.shutdown();
// process.exit(0);
// });
10. Webhook Handler
Webhook sending and receiving infrastructure
// services/WebhookService.ts
import crypto from 'crypto';
interface WebhookPayload {
event: string;
data: any;
timestamp: string;
}
export class WebhookService {
// Send webhook with retry logic
static async sendWebhook(
url: string,
payload: WebhookPayload,
secret?: string,
maxRetries: number = 3
): Promise<boolean> {
const headers: Record<string, string> = {
'Content-Type': 'application/json',
'X-Webhook-Timestamp': payload.timestamp,
};
// Add signature for verification
if (secret) {
const signature = this.generateSignature(payload, secret);
headers['X-Webhook-Signature'] = signature;
}
let attempt = 0;
while (attempt < maxRetries) {
try {
const response = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(payload),
timeout: 10000, // 10 second timeout
});
if (response.ok) {
// Log successful delivery
await db.webhookLog.insertOne({
url,
event: payload.event,
status: 'delivered',
timestamp: new Date(),
attempt: attempt + 1,
});
return true;
}
throw new Error(`Webhook failed with status ${response.status}`);
} catch (error) {
attempt++;
console.error(`Webhook delivery attempt ${attempt} failed:`, error);
if (attempt < maxRetries) {
// Exponential backoff
const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
await new Promise((resolve) => setTimeout(resolve, delay));
} else {
// Log failed delivery
await db.webhookLog.insertOne({
url,
event: payload.event,
status: 'failed',
error: error.message,
timestamp: new Date(),
attempts: maxRetries,
});
return false;
}
}
}
return false;
}
// Generate signature for webhook verification
static generateSignature(payload: any, secret: string): string {
const body = JSON.stringify(payload);
return crypto.createHmac('sha256', secret).update(body).digest('hex');
}
// Verify incoming webhook signature
static verifySignature(
payload: any,
signature: string,
secret: string
): boolean {
const expectedSignature = this.generateSignature(payload, secret);
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Trigger webhooks for event
static async triggerEvent(event: string, data: any): Promise<void> {
// Get all webhook subscriptions for this event
const subscriptions = await db.webhookSubscriptions.find({
events: event,
active: true,
}).toArray();
const payload: WebhookPayload = {
event,
data,
timestamp: new Date().toISOString(),
};
// Send to all subscribers
const promises = subscriptions.map((sub) =>
this.sendWebhook(sub.url, payload, sub.secret)
);
await Promise.allSettled(promises);
}
}
// Express middleware to handle incoming webhooks
export const webhookHandler = (secret: string) => {
return (req: Request, res: Response, next: NextFunction) => {
const signature = req.headers['x-webhook-signature'] as string;
if (!signature) {
return res.status(401).json({ error: 'Missing webhook signature' });
}
const isValid = WebhookService.verifySignature(req.body, signature, secret);
if (!isValid) {
return res.status(401).json({ error: 'Invalid webhook signature' });
}
next();
};
};
// Usage - sending webhooks:
// await WebhookService.triggerEvent('expense.approved', {
// expenseId: expense.id,
// amount: expense.amount,
// approvedBy: user.name,
// });
//
// Usage - receiving webhooks:
// router.post('/webhooks/finance',
// express.json(),
// webhookHandler(process.env.WEBHOOK_SECRET),
// async (req, res) => {
// const { event, data } = req.body;
//
// switch (event) {
// case 'expense.approved':
// await processApprovedExpense(data);
// break;
// case 'invoice.paid':
// await processInvoicePayment(data);
// break;
// }
//
// res.json({ received: true });
// }
// );
Database Templates (SQL)
11. Audit Trail Schema
-- Audit log table
CREATE TABLE audit_log (
id BIGSERIAL PRIMARY KEY,
timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
user_id VARCHAR(50) NOT NULL,
user_name VARCHAR(200) NOT NULL,
action VARCHAR(20) NOT NULL, -- 'create', 'read', 'update', 'delete'
entity_type VARCHAR(100) NOT NULL,
entity_id VARCHAR(100) NOT NULL,
changes_before JSONB,
changes_after JSONB,
ip_address INET,
user_agent TEXT,
session_id VARCHAR(100),
metadata JSONB
);
-- Indexes for performance
CREATE INDEX idx_audit_log_entity ON audit_log(entity_type, entity_id);
CREATE INDEX idx_audit_log_user ON audit_log(user_id);
CREATE INDEX idx_audit_log_timestamp ON audit_log(timestamp);
CREATE INDEX idx_audit_log_action ON audit_log(action);
-- Partition by month for better performance (PostgreSQL 10+)
CREATE TABLE audit_log_2025_01 PARTITION OF audit_log
FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');
CREATE TABLE audit_log_2025_02 PARTITION OF audit_log
FOR VALUES FROM ('2025-02-01') TO ('2025-03-01');
-- Continue for each month...
-- Query examples:
-- Get audit trail for specific entity
SELECT * FROM audit_log
WHERE entity_type = 'permit' AND entity_id = '12345'
ORDER BY timestamp DESC;
-- Get all changes by specific user
SELECT * FROM audit_log
WHERE user_id = 'user123'
ORDER BY timestamp DESC;
-- Get all deletions in date range
SELECT * FROM audit_log
WHERE action = 'delete'
AND timestamp BETWEEN '2025-01-01' AND '2025-01-31';
12. Version Control Schema
-- Versions table
CREATE TABLE document_versions (
id BIGSERIAL PRIMARY KEY,
document_id VARCHAR(100) NOT NULL,
version_number INTEGER NOT NULL,
content TEXT NOT NULL,
created_by VARCHAR(50) NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
comment TEXT,
metadata JSONB,
UNIQUE(document_id, version_number)
);
-- Current version pointer
CREATE TABLE documents (
id VARCHAR(100) PRIMARY KEY,
title VARCHAR(500) NOT NULL,
current_version INTEGER NOT NULL DEFAULT 1,
created_by VARCHAR(50) NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (id, current_version)
REFERENCES document_versions(document_id, version_number)
);
-- Indexes
CREATE INDEX idx_versions_document ON document_versions(document_id);
CREATE INDEX idx_versions_created_at ON document_versions(created_at);
-- Trigger to auto-increment version number
CREATE OR REPLACE FUNCTION increment_version_number()
RETURNS TRIGGER AS $$
BEGIN
NEW.version_number := (
SELECT COALESCE(MAX(version_number), 0) + 1
FROM document_versions
WHERE document_id = NEW.document_id
);
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER set_version_number
BEFORE INSERT ON document_versions
FOR EACH ROW
EXECUTE FUNCTION increment_version_number();
-- Query examples:
-- Get latest version
SELECT dv.*
FROM documents d
JOIN document_versions dv ON d.id = dv.document_id
AND d.current_version = dv.version_number
WHERE d.id = 'doc123';
-- Get all versions
SELECT * FROM document_versions
WHERE document_id = 'doc123'
ORDER BY version_number DESC;
-- Compare two versions
SELECT
v1.version_number as version_1,
v1.content as content_1,
v2.version_number as version_2,
v2.content as content_2
FROM document_versions v1
JOIN document_versions v2 ON v1.document_id = v2.document_id
WHERE v1.document_id = 'doc123'
AND v1.version_number = 1
AND v2.version_number = 2;
13. Master-Detail Relationship Schema
-- Master table (Family/Household)
CREATE TABLE families (
id SERIAL PRIMARY KEY,
family_name VARCHAR(200) NOT NULL,
primary_contact_name VARCHAR(200) NOT NULL,
primary_contact_email VARCHAR(200) NOT NULL,
primary_contact_phone VARCHAR(20),
address VARCHAR(500),
enrollment_date DATE NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'active',
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- Detail table (Students)
CREATE TABLE students (
id SERIAL PRIMARY KEY,
family_id INTEGER NOT NULL,
first_name VARCHAR(100) NOT NULL,
last_name VARCHAR(100) NOT NULL,
date_of_birth DATE NOT NULL,
grade_level VARCHAR(20),
allergies TEXT,
emergency_contact_name VARCHAR(200),
emergency_contact_phone VARCHAR(20),
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (family_id) REFERENCES families(id) ON DELETE CASCADE
);
-- Indexes
CREATE INDEX idx_students_family ON students(family_id);
CREATE INDEX idx_families_status ON families(status);
-- Trigger to update updated_at
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
NEW.updated_at = CURRENT_TIMESTAMP;
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER update_families_updated_at
BEFORE UPDATE ON families
FOR EACH ROW
EXECUTE FUNCTION update_updated_at_column();
CREATE TRIGGER update_students_updated_at
BEFORE UPDATE ON students
FOR EACH ROW
EXECUTE FUNCTION update_updated_at_column();
-- Query examples:
-- Get family with all students
SELECT
f.*,
jsonb_agg(
jsonb_build_object(
'id', s.id,
'firstName', s.first_name,
'lastName', s.last_name,
'grade', s.grade_level
)
) as students
FROM families f
LEFT JOIN students s ON f.id = s.family_id
WHERE f.id = 123
GROUP BY f.id;
-- Get student count per family
SELECT
f.id,
f.family_name,
COUNT(s.id) as student_count
FROM families f
LEFT JOIN students s ON f.id = s.family_id
GROUP BY f.id, f.family_name;
-- Cascade delete test
-- DELETE FROM families WHERE id = 123;
-- This will automatically delete all students for that family
Utility Functions
14. Validation Helpers
// utils/validators.ts
// Email validation
export const isValidEmail = (email: string): boolean => {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(email);
};
// Phone number validation (US format)
export const isValidPhone = (phone: string): boolean => {
// Remove non-digits
const digits = phone.replace(/\D/g, '');
return digits.length === 10 || digits.length === 11;
};
// Format phone number
export const formatPhone = (phone: string): string => {
const digits = phone.replace(/\D/g, '');
if (digits.length === 10) {
return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
}
return phone;
};
// SSN validation
export const isValidSSN = (ssn: string): boolean => {
const digits = ssn.replace(/\D/g, '');
return digits.length === 9 && !/^000|666|9\d{2}/.test(digits);
};
// Credit card validation (Luhn algorithm)
export const isValidCreditCard = (cardNumber: string): boolean => {
const digits = cardNumber.replace(/\D/g, '');
let sum = 0;
let isEven = false;
for (let i = digits.length - 1; i >= 0; i--) {
let digit = parseInt(digits[i]);
if (isEven) {
digit *= 2;
if (digit > 9) {
digit -= 9;
}
}
sum += digit;
isEven = !isEven;
}
return sum % 10 === 0;
};
// Date range validation
export const isValidDateRange = (start: Date, end: Date): boolean => {
return start < end;
};
// Age validation
export const calculateAge = (birthDate: Date): number => {
const today = new Date();
let age = today.getFullYear() - birthDate.getFullYear();
const monthDiff = today.getMonth() - birthDate.getMonth();
if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birthDate.getDate())) {
age--;
}
return age;
};
export const isMinimumAge = (birthDate: Date, minimumAge: number): boolean => {
return calculateAge(birthDate) >= minimumAge;
};
// URL validation
export const isValidURL = (url: string): boolean => {
try {
new URL(url);
return true;
} catch {
return false;
}
};
// ZIP code validation (US)
export const isValidZipCode = (zip: string): boolean => {
return /^\d{5}(-\d{4})?$/.test(zip);
};
// Money validation and formatting
export const formatCurrency = (amount: number): string => {
return new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD',
}).format(amount);
};
export const parseCurrency = (formatted: string): number => {
return parseFloat(formatted.replace(/[$,]/g, ''));
};
15. Error Handling Utilities
// utils/errorHandling.ts
// Custom error classes
export class ValidationError extends Error {
constructor(
message: string,
public field?: string,
public code?: string
) {
super(message);
this.name = 'ValidationError';
}
}
export class BusinessRuleError extends Error {
constructor(
message: string,
public rule?: string,
public data?: any
) {
super(message);
this.name = 'BusinessRuleError';
}
}
export class NotFoundError extends Error {
constructor(
message: string,
public entityType?: string,
public entityId?: string
) {
super(message);
this.name = 'NotFoundError';
}
}
export class UnauthorizedError extends Error {
constructor(message: string = 'Unauthorized') {
super(message);
this.name = 'UnauthorizedError';
}
}
// Express error handler middleware
export const errorHandler = (
err: Error,
req: Request,
res: Response,
next: NextFunction
) => {
console.error('[Error]', err);
// Validation errors (400)
if (err instanceof ValidationError) {
return res.status(400).json({
error: 'Validation failed',
message: err.message,
field: err.field,
code: err.code,
});
}
// Business rule errors (422)
if (err instanceof BusinessRuleError) {
return res.status(422).json({
error: 'Business rule violation',
message: err.message,
rule: err.rule,
data: err.data,
});
}
// Not found errors (404)
if (err instanceof NotFoundError) {
return res.status(404).json({
error: 'Resource not found',
message: err.message,
entityType: err.entityType,
entityId: err.entityId,
});
}
// Unauthorized errors (401)
if (err instanceof UnauthorizedError) {
return res.status(401).json({
error: 'Unauthorized',
message: err.message,
});
}
// Default server error (500)
res.status(500).json({
error: 'Internal server error',
message: process.env.NODE_ENV === 'production'
? 'An unexpected error occurred'
: err.message,
});
};
// Async handler wrapper (prevents try/catch in every route)
export const asyncHandler = (fn: Function) => {
return (req: Request, res: Response, next: NextFunction) => {
Promise.resolve(fn(req, res, next)).catch(next);
};
};
// Usage in routes:
// router.get('/permits/:id', asyncHandler(async (req, res) => {
// const permit = await db.permits.findById(req.params.id);
// if (!permit) {
// throw new NotFoundError('Permit not found', 'permit', req.params.id);
// }
// res.json(permit);
// }));
// Result wrapper for consistent API responses
export class Result<T> {
constructor(
public success: boolean,
public data?: T,
public error?: string,
public errors?: Array<{ field: string; message: string }>
) {}
static ok<T>(data: T): Result<T> {
return new Result(true, data);
}
static fail<T>(error: string, errors?: Array<{ field: string; message: string }>): Result<T> {
return new Result(false, undefined, error, errors);
}
}
// Usage:
// const result = await createPermit(permitData);
// if (result.success) {
// return res.json(result.data);
// } else {
// return res.status(400).json({ error: result.error, errors: result.errors });
// }
16. API Client Wrapper
// services/ApiClient.ts
interface RequestOptions {
method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
headers?: Record<string, string>;
body?: any;
timeout?: number;
retry?: {
maxRetries: number;
backoff?: 'linear' | 'exponential';
};
}
export class ApiClient {
private baseURL: string;
private defaultHeaders: Record<string, string>;
constructor(baseURL: string, defaultHeaders: Record<string, string> = {}) {
this.baseURL = baseURL;
this.defaultHeaders = {
'Content-Type': 'application/json',
...defaultHeaders,
};
}
// Generic request method with retry logic
async request<T>(
endpoint: string,
options: RequestOptions = {}
): Promise<T> {
const {
method = 'GET',
headers = {},
body,
timeout = 30000,
retry = { maxRetries: 3, backoff: 'exponential' },
} = options;
const url = `${this.baseURL}${endpoint}`;
const requestHeaders = { ...this.defaultHeaders, ...headers };
let lastError: Error;
for (let attempt = 0; attempt <= retry.maxRetries; attempt++) {
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);
const response = await fetch(url, {
method,
headers: requestHeaders,
body: body ? JSON.stringify(body) : undefined,
signal: controller.signal,
});
clearTimeout(timeoutId);
if (!response.ok) {
const errorBody = await response.text();
throw new Error(
`API error ${response.status}: ${errorBody}`
);
}
const data = await response.json();
return data as T;
} catch (error) {
lastError = error as Error;
// Don't retry on client errors (4xx)
if (error.message.includes('API error 4')) {
throw error;
}
// Retry with backoff
if (attempt < retry.maxRetries) {
const delay = retry.backoff === 'exponential'
? Math.pow(2, attempt) * 1000 // 1s, 2s, 4s, 8s
: (attempt + 1) * 1000; // 1s, 2s, 3s, 4s
console.log(`Request failed, retrying in ${delay}ms (attempt ${attempt + 1}/${retry.maxRetries})`);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
}
throw new Error(`Request failed after ${retry.maxRetries} retries: ${lastError.message}`);
}
// Convenience methods
async get<T>(endpoint: string, headers?: Record<string, string>): Promise<T> {
return this.request<T>(endpoint, { method: 'GET', headers });
}
async post<T>(endpoint: string, body: any, headers?: Record<string, string>): Promise<T> {
return this.request<T>(endpoint, { method: 'POST', body, headers });
}
async put<T>(endpoint: string, body: any, headers?: Record<string, string>): Promise<T> {
return this.request<T>(endpoint, { method: 'PUT', body, headers });
}
async patch<T>(endpoint: string, body: any, headers?: Record<string, string>): Promise<T> {
return this.request<T>(endpoint, { method: 'PATCH', body, headers });
}
async delete<T>(endpoint: string, headers?: Record<string, string>): Promise<T> {
return this.request<T>(endpoint, { method: 'DELETE', headers });
}
}
// Example API clients
export const internalApi = new ApiClient('http://localhost:3000/api');
export const uspsApi = new ApiClient('https://api.usps.com', {
'Authorization': `Bearer ${process.env.USPS_API_KEY}`,
});
export const stripeApi = new ApiClient('https://api.stripe.com/v1', {
'Authorization': `Bearer ${process.env.STRIPE_SECRET_KEY}`,
});
// Usage:
// const permit = await internalApi.get<Permit>('/permits/123');
//
// const validatedAddress = await uspsApi.post('/addresses/validate', {
// street: '123 Main St',
// city: 'Springfield',
// state: 'IL',
// zip: '62704',
// });
//
// const customer = await stripeApi.post('/customers', {
// email: 'customer@example.com',
// name: 'John Smith',
// });
17. State Machine Implementation
// utils/StateMachine.ts
interface StateConfig<TState extends string, TEvent extends string> {
initial: TState;
states: Record<TState, {
on?: Partial<Record<TEvent, TState>>;
onEnter?: () => void | Promise<void>;
onExit?: () => void | Promise<void>;
}>;
}
export class StateMachine<TState extends string, TEvent extends string> {
private currentState: TState;
private config: StateConfig<TState, TEvent>;
private listeners: Array<(state: TState) => void> = [];
constructor(config: StateConfig<TState, TEvent>) {
this.config = config;
this.currentState = config.initial;
}
getCurrentState(): TState {
return this.currentState;
}
canTransition(event: TEvent): boolean {
const transitions = this.config.states[this.currentState].on;
return transitions ? event in transitions : false;
}
async transition(event: TEvent): Promise<boolean> {
const currentStateConfig = this.config.states[this.currentState];
const transitions = currentStateConfig.on;
if (!transitions || !(event in transitions)) {
console.warn(`Invalid transition: ${event} from state ${this.currentState}`);
return false;
}
const nextState = transitions[event]!;
// Execute exit handler
if (currentStateConfig.onExit) {
await currentStateConfig.onExit();
}
// Change state
const previousState = this.currentState;
this.currentState = nextState;
// Execute enter handler
const nextStateConfig = this.config.states[nextState];
if (nextStateConfig.onEnter) {
await nextStateConfig.onEnter();
}
// Notify listeners
this.listeners.forEach(listener => listener(this.currentState));
console.log(`State transition: ${previousState} → ${nextState} (event: ${event})`);
return true;
}
onStateChange(listener: (state: TState) => void): () => void {
this.listeners.push(listener);
// Return unsubscribe function
return () => {
this.listeners = this.listeners.filter(l => l !== listener);
};
}
}
// Example: Expense approval workflow
type ExpenseState =
| 'draft'
| 'submitted'
| 'approved_manager'
| 'approved_finance'
| 'paid'
| 'rejected';
type ExpenseEvent =
| 'submit'
| 'approve_manager'
| 'approve_finance'
| 'pay'
| 'reject';
export const createExpenseStateMachine = (expenseId: string) => {
return new StateMachine<ExpenseState, ExpenseEvent>({
initial: 'draft',
states: {
draft: {
on: {
submit: 'submitted',
},
onExit: async () => {
await db.expenses.update(expenseId, { submittedAt: new Date() });
},
},
submitted: {
on: {
approve_manager: 'approved_manager',
reject: 'rejected',
},
onEnter: async () => {
await notifyManager(expenseId);
},
},
approved_manager: {
on: {
approve_finance: 'approved_finance',
reject: 'rejected',
},
onEnter: async () => {
await notifyFinance(expenseId);
},
},
approved_finance: {
on: {
pay: 'paid',
},
onEnter: async () => {
await postToGeneralLedger(expenseId);
},
},
paid: {
// Terminal state
onEnter: async () => {
await processPayment(expenseId);
await notifySubmitter(expenseId);
},
},
rejected: {
// Terminal state
onEnter: async () => {
await notifySubmitter(expenseId);
},
},
},
});
};
// Usage:
// const expense = await db.expenses.findById('exp-123');
// const stateMachine = createExpenseStateMachine('exp-123');
//
// // Subscribe to state changes
// const unsubscribe = stateMachine.onStateChange((newState) => {
// console.log('Expense state changed to:', newState);
// db.expenses.update('exp-123', { status: newState });
// });
//
// // Transition through workflow
// await stateMachine.transition('submit'); // draft → submitted
// await stateMachine.transition('approve_manager'); // submitted → approved_manager
// await stateMachine.transition('approve_finance'); // approved_manager → approved_finance
// await stateMachine.transition('pay'); // approved_finance → paid
18. Cross-System Workflow Orchestrator
// services/WorkflowOrchestrator.ts
interface WorkflowStep {
name: string;
execute: (context: any) => Promise<any>;
onError?: (error: Error, context: any) => Promise<void>;
timeout?: number;
}
interface WorkflowConfig {
name: string;
steps: WorkflowStep[];
onComplete?: (context: any) => Promise<void>;
onFailure?: (error: Error, context: any) => Promise<void>;
}
export class WorkflowOrchestrator {
private config: WorkflowConfig;
private context: any = {};
private currentStepIndex: number = 0;
private completedSteps: string[] = [];
constructor(config: WorkflowConfig, initialContext: any = {}) {
this.config = config;
this.context = { ...initialContext };
}
async execute(): Promise<any> {
console.log(`Starting workflow: ${this.config.name}`);
try {
for (let i = 0; i < this.config.steps.length; i++) {
this.currentStepIndex = i;
const step = this.config.steps[i];
console.log(`Executing step ${i + 1}/${this.config.steps.length}: ${step.name}`);
try {
// Execute step with timeout
const result = await this.executeWithTimeout(
step.execute(this.context),
step.timeout || 30000
);
// Add result to context
this.context[step.name] = result;
this.completedSteps.push(step.name);
console.log(`Step completed: ${step.name}`);
} catch (stepError) {
console.error(`Step failed: ${step.name}`, stepError);
// Run step-specific error handler
if (step.onError) {
await step.onError(stepError as Error, this.context);
}
throw stepError;
}
}
// All steps completed successfully
console.log(`Workflow completed: ${this.config.name}`);
if (this.config.onComplete) {
await this.config.onComplete(this.context);
}
return this.context;
} catch (error) {
console.error(`Workflow failed: ${this.config.name}`, error);
// Run workflow-level failure handler
if (this.config.onFailure) {
await this.config.onFailure(error as Error, this.context);
}
throw error;
}
}
private executeWithTimeout<T>(promise: Promise<T>, timeout: number): Promise<T> {
return Promise.race([
promise,
new Promise<T>((_, reject) =>
setTimeout(() => reject(new Error('Step timeout')), timeout)
),
]);
}
getCompletedSteps(): string[] {
return this.completedSteps;
}
getContext(): any {
return this.context;
}
}
// Example: Complete expense approval workflow
export const createExpenseApprovalWorkflow = (expenseId: string) => {
return new WorkflowOrchestrator({
name: 'Expense Approval',
steps: [
{
name: 'load_expense',
execute: async () => {
return await db.expenses.findById(expenseId);
},
},
{
name: 'validate_expense',
execute: async (context) => {
const expense = context.load_expense;
if (!expense.receipt) {
throw new ValidationError('Receipt required');
}
if (expense.amount <= 0) {
throw new ValidationError('Amount must be positive');
}
return { valid: true };
},
},
{
name: 'check_policy',
execute: async (context) => {
const expense = context.load_expense;
const policy = await db.expensePolicies.findOne({ active: true });
const withinPolicy = expense.amount <= policy.limits[expense.category];
return {
withinPolicy,
requiresManagerApproval: expense.amount > policy.managerApprovalThreshold,
requiresFinanceApproval: expense.amount > policy.financeApprovalThreshold,
};
},
},
{
name: 'manager_approval',
execute: async (context) => {
const policyCheck = context.check_policy;
if (!policyCheck.requiresManagerApproval) {
return { approved: true, autoApproved: true };
}
const expense = context.load_expense;
await sendEmail({
to: expense.managerEmail,
subject: 'Expense Approval Required',
template: 'expense-approval',
data: { expense },
});
// In real system, this would wait for manager's action
// For demo, auto-approve
return { approved: true, approvedBy: 'manager@company.com' };
},
timeout: 48 * 60 * 60 * 1000, // 48 hours
},
{
name: 'finance_review',
execute: async (context) => {
const policyCheck = context.check_policy;
if (!policyCheck.requiresFinanceApproval) {
return { approved: true, autoApproved: true };
}
const expense = context.load_expense;
await sendEmail({
to: 'finance@company.com',
subject: 'Finance Review Required',
template: 'finance-review',
data: { expense },
});
return { approved: true, reviewedBy: 'finance@company.com' };
},
},
{
name: 'post_to_gl',
execute: async (context) => {
const expense = context.load_expense;
const glEntry = await fetch('http://finance-system.com/api/gl/entries', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
account: expense.accountCode,
amount: expense.amount,
description: expense.description,
date: expense.date,
}),
}).then(r => r.json());
return { glEntryId: glEntry.id };
},
onError: async (error, context) => {
// If GL posting fails, mark expense for manual review
await db.expenses.update(expenseId, {
status: 'gl_posting_failed',
error: error.message,
});
},
},
{
name: 'process_payment',
execute: async (context) => {
const expense = context.load_expense;
const payment = await fetch('http://payment-system.com/api/payments', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
recipient: expense.submitterId,
amount: expense.amount,
method: 'ACH',
reference: `Expense ${expenseId}`,
}),
}).then(r => r.json());
return { paymentId: payment.id };
},
},
{
name: 'notify_submitter',
execute: async (context) => {
const expense = context.load_expense;
const payment = context.process_payment;
await sendEmail({
to: expense.submitterEmail,
subject: 'Expense Approved and Paid',
template: 'expense-paid',
data: {
expense,
paymentId: payment.paymentId,
},
});
return { notified: true };
},
},
],
onComplete: async (context) => {
const expense = context.load_expense;
await db.expenses.update(expenseId, {
status: 'paid',
paidAt: new Date(),
glEntryId: context.post_to_gl.glEntryId,
paymentId: context.process_payment.paymentId,
});
console.log(`Expense ${expenseId} fully processed`);
},
onFailure: async (error, context) => {
await db.expenses.update(expenseId, {
status: 'workflow_failed',
error: error.message,
completedSteps: Object.keys(context),
});
// Alert operations team
await sendEmail({
to: 'ops@company.com',
subject: 'Expense Workflow Failed',
body: `Expense ${expenseId} failed at step ${Object.keys(context).length + 1}. Error: ${error.message}`,
});
},
}, { expenseId });
};
// Usage:
// const workflow = createExpenseApprovalWorkflow('exp-123');
// try {
// const result = await workflow.execute();
// console.log('Workflow completed:', result);
// } catch (error) {
// console.error('Workflow failed:', error);
// console.log('Completed steps:', workflow.getCompletedSteps());
// }
19. Real-Time Lookup Service
// services/RealTimeLookupService.ts
interface LookupCache {
data: any;
timestamp: number;
ttl: number;
}
export class RealTimeLookupService {
private cache: Map<string, LookupCache> = new Map();
// Address validation with USPS
async validateAddress(address: {
street: string;
city: string;
state: string;
zip?: string;
}): Promise<{
isValid: boolean;
standardizedAddress?: any;
suggestions?: any[];
}> {
const cacheKey = `address:${JSON.stringify(address)}`;
// Check cache
const cached = this.getFromCache(cacheKey);
if (cached) return cached;
try {
const response = await fetch('https://api.usps.com/addresses/validate', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.USPS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(address),
});
const result = await response.json();
// Cache for 1 hour
this.setCache(cacheKey, result, 60 * 60 * 1000);
return result;
} catch (error) {
console.error('USPS validation failed:', error);
return { isValid: false };
}
}
// Credit check
async checkCredit(ssn: string): Promise<{
score: number;
approved: boolean;
}> {
// Don't cache credit checks (sensitive data)
try {
const response = await fetch('https://api.creditbureau.com/check', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.CREDIT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ssn }),
});
return await response.json();
} catch (error) {
console.error('Credit check failed:', error);
throw new Error('Credit check service unavailable');
}
}
// Inventory availability
async checkInventory(productId: string, quantity: number): Promise<{
available: boolean;
stock: number;
nextRestockDate?: string;
}> {
const cacheKey = `inventory:${productId}`;
// Check cache (5 minute TTL for inventory)
const cached = this.getFromCache(cacheKey);
if (cached) {
return {
available: cached.stock >= quantity,
stock: cached.stock,
nextRestockDate: cached.nextRestockDate,
};
}
try {
const response = await fetch(
`https://api.inventory.com/products/${productId}/stock`
);
const result = await response.json();
// Cache for 5 minutes
this.setCache(cacheKey, result, 5 * 60 * 1000);
return {
available: result.stock >= quantity,
stock: result.stock,
nextRestockDate: result.nextRestockDate,
};
} catch (error) {
console.error('Inventory check failed:', error);
return { available: false, stock: 0 };
}
}
// Shipping rate calculation
async calculateShipping(params: {
from: string;
to: string;
weight: number;
service: 'ground' | 'express' | 'overnight';
}): Promise<{
cost: number;
estimatedDays: number;
}> {
const cacheKey = `shipping:${JSON.stringify(params)}`;
// Check cache (1 day TTL)
const cached = this.getFromCache(cacheKey);
if (cached) return cached;
try {
const response = await fetch('https://api.shipping.com/rates', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SHIPPING_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(params),
});
const result = await response.json();
// Cache for 1 day
this.setCache(cacheKey, result, 24 * 60 * 60 * 1000);
return result;
} catch (error) {
console.error('Shipping calculation failed:', error);
throw new Error('Shipping service unavailable');
}
}
// Exchange rate lookup
async getExchangeRate(from: string, to: string): Promise<number> {
const cacheKey = `exchange:${from}-${to}`;
// Check cache (1 hour TTL)
const cached = this.getFromCache(cacheKey);
if (cached) return cached.rate;
try {
const response = await fetch(
`https://api.exchangerate.com/latest?base=${from}&symbols=${to}`
);
const result = await response.json();
const rate = result.rates[to];
// Cache for 1 hour
this.setCache(cacheKey, { rate }, 60 * 60 * 1000);
return rate;
} catch (error) {
console.error('Exchange rate lookup failed:', error);
throw new Error('Exchange rate service unavailable');
}
}
// Tax rate calculation
async getTaxRate(address: {
street: string;
city: string;
state: string;
zip: string;
}): Promise<{
rate: number;
breakdown: {
state: number;
county: number;
city: number;
special: number;
};
}> {
const cacheKey = `tax:${address.zip}`;
// Check cache (1 month TTL - tax rates change infrequently)
const cached = this.getFromCache(cacheKey);
if (cached) return cached;
try {
const response = await fetch('https://api.taxjar.com/rates', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.TAXJAR_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(address),
});
const result = await response.json();
// Cache for 30 days
this.setCache(cacheKey, result, 30 * 24 * 60 * 60 * 1000);
return result;
} catch (error) {
console.error('Tax rate lookup failed:', error);
throw new Error('Tax service unavailable');
}
}
// Cache management
private getFromCache(key: string): any | null {
const cached = this.cache.get(key);
if (!cached) return null;
// Check if expired
if (Date.now() - cached.timestamp > cached.ttl) {
this.cache.delete(key);
return null;
}
return cached.data;
}
private setCache(key: string, data: any, ttl: number): void {
this.cache.set(key, {
data,
timestamp: Date.now(),
ttl,
});
}
clearCache(): void {
this.cache.clear();
}
}
// Singleton instance
export const lookupService = new RealTimeLookupService();
// Usage:
// const addressResult = await lookupService.validateAddress({
// street: '123 Main St',
// city: 'Springfield',
// state: 'IL',
// });
//
// const inventory = await lookupService.checkInventory('prod-123', 5);
//
// const shipping = await lookupService.calculateShipping({
// from: '62704',
// to: '10001',
// weight: 2.5,
// service: 'ground',
// });
Python Templates
20. Domain-Aware Validation (Python)
# validators.py
from typing import Dict, List, Optional
from datetime import datetime, date
import re
class ValidationError(Exception):
"""Custom validation error"""
def __init__(self, field: str, message: str):
self.field = field
self.message = message
super().__init__(f"{field}: {message}")
class ValidationResult:
"""Result of validation"""
def __init__(self):
self.errors: List[ValidationError] = []
self.is_valid = True
def add_error(self, field: str, message: str):
self.errors.append(ValidationError(field, message))
self.is_valid = False
def get_errors_dict(self) -> Dict[str, str]:
return {err.field: err.message for err in self.errors}
class PermitValidator:
"""Domain-specific validator for building permits"""
@staticmethod
def validate_deck_permit(data: Dict) -> ValidationResult:
result = ValidationResult()
# Required fields
if not data.get('property_address'):
result.add_error('property_address', 'Property address is required')
if not data.get('parcel_number'):
result.add_error('parcel_number', 'Parcel number is required')
elif not re.match(r'^\d{2}-\d{2}-\d{3}-\d{3}$', data['parcel_number']):
result.add_error('parcel_number', 'Invalid parcel number format')
# Deck size validation
deck_size = data.get('deck_size')
if not deck_size:
result.add_error('deck_size', 'Deck size is required')
elif deck_size <= 0:
result.add_error('deck_size', 'Deck size must be positive')
elif deck_size > 500:
result.add_error('deck_size', 'Deck size cannot exceed 500 sq ft')
# Zoning rules
zoning = data.get('zoning')
if zoning == 'R-1' and deck_size and deck_size > 150:
result.add_error(
'deck_size',
'Decks over 150 sq ft require variance in R-1 zones'
)
# Setback requirements
distance = data.get('distance_from_property')
if distance and distance < 10:
result.add_error(
'distance_from_property',
'Deck must be at least 10 feet from property line'
)
# Contractor license
license = data.get('contractor_license')
if license and not re.match(r'^[A-Z]{3}-\d{6}$', license):
result.add_error(
'contractor_license',
'Invalid contractor license format'
)
return result
@staticmethod
def validate_temporal_constraints(data: Dict) -> ValidationResult:
result = ValidationResult()
start_date = data.get('start_date')
end_date = data.get('end_date')
if start_date and end_date:
if isinstance(start_date, str):
start_date = datetime.fromisoformat(start_date)
if isinstance(end_date, str):
end_date = datetime.fromisoformat(end_date)
if end_date <= start_date:
result.add_error('end_date', 'End date must be after start date')
duration = (end_date - start_date).days
if duration > 365:
result.add_error('end_date', 'Project duration cannot exceed 1 year')
return result
# Usage:
# permit_data = {
# 'property_address': '123 Main St',
# 'parcel_number': '14-21-356-003',
# 'deck_size': 175,
# 'zoning': 'R-1',
# 'distance_from_property': 12,
# 'contractor_license': 'ABC-123456',
# }
#
# result = PermitValidator.validate_deck_permit(permit_data)
# if not result.is_valid:
# print('Validation errors:', result.get_errors_dict())
21. Audit Trail Logger (Python)
# audit_logger.py
from typing import Optional, Dict, Any
from datetime import datetime
from dataclasses import dataclass, asdict
import json
@dataclass
class AuditLogEntry:
"""Audit log entry structure"""
timestamp: datetime
user_id: str
user_name: str
action: str # 'create', 'read', 'update', 'delete'
entity_type: str
entity_id: str
changes_before: Optional[Dict] = None
changes_after: Optional[Dict] = None
ip_address: Optional[str] = None
user_agent: Optional[str] = None
metadata: Optional[Dict] = None
class AuditLogger:
"""Comprehensive audit logging system"""
def __init__(self, db_connection):
self.db = db_connection
def log(self, entry: AuditLogEntry) -> None:
"""Log an audit entry"""
# Convert to dict for database
entry_dict = asdict(entry)
entry_dict['timestamp'] = entry.timestamp.isoformat()
# Convert changes to JSON strings
if entry_dict['changes_before']:
entry_dict['changes_before'] = json.dumps(entry_dict['changes_before'])
if entry_dict['changes_after']:
entry_dict['changes_after'] = json.dumps(entry_dict['changes_after'])
if entry_dict['metadata']:
entry_dict['metadata'] = json.dumps(entry_dict['metadata'])
# Insert into database
self.db.audit_log.insert_one(entry_dict)
def log_create(
self,
user_id: str,
user_name: str,
entity_type: str,
entity_id: str,
data: Dict[str, Any],
**kwargs
) -> None:
"""Log a create action"""
entry = AuditLogEntry(
timestamp=datetime.now(),
user_id=user_id,
user_name=user_name,
action='create',
entity_type=entity_type,
entity_id=entity_id,
changes_before=None,
changes_after=data,
**kwargs
)
self.log(entry)
def log_update(
self,
user_id: str,
user_name: str,
entity_type: str,
entity_id: str,
before: Dict[str, Any],
after: Dict[str, Any],
**kwargs
) -> None:
"""Log an update action"""
entry = AuditLogEntry(
timestamp=datetime.now(),
user_id=user_id,
user_name=user_name,
action='update',
entity_type=entity_type,
entity_id=entity_id,
changes_before=before,
changes_after=after,
**kwargs
)
self.log(entry)
def log_delete(
self,
user_id: str,
user_name: str,
entity_type: str,
entity_id: str,
data: Dict[str, Any],
**kwargs
) -> None:
"""Log a delete action"""
entry = AuditLogEntry(
timestamp=datetime.now(),
user_id=user_id,
user_name=user_name,
action='delete',
entity_type=entity_type,
entity_id=entity_id,
changes_before=data,
changes_after=None,
**kwargs
)
self.log(entry)
def get_audit_trail(
self,
entity_type: str,
entity_id: str
) -> List[Dict]:
"""Get audit trail for an entity"""
return list(self.db.audit_log.find({
'entity_type': entity_type,
'entity_id': entity_id
}).sort('timestamp', -1))
def search_audit_logs(
self,
user_id: Optional[str] = None,
entity_type: Optional[str] = None,
action: Optional[str] = None,
start_date: Optional[datetime] = None,
end_date: Optional[datetime] = None
) -> List[Dict]:
"""Search audit logs with filters"""
query = {}
if user_id:
query['user_id'] = user_id
if entity_type:
query['entity_type'] = entity_type
if action:
query['action'] = action
if start_date or end_date:
query['timestamp'] = {}
if start_date:
query['timestamp']['$gte'] = start_date.isoformat()
if end_date:
query['timestamp']['$lte'] = end_date.isoformat()
return list(self.db.audit_log.find(query).sort('timestamp', -1))
# Usage:
# from pymongo import MongoClient
#
# client = MongoClient('mongodb://localhost:27017/')
# db = client.permits_db
#
# audit_logger = AuditLogger(db)
#
# # Log a create
# audit_logger.log_create(
# user_id='user123',
# user_name='John Smith',
# entity_type='permit',
# entity_id='perm-456',
# data={'status': 'submitted', 'amount': 150},
# ip_address='192.168.1.1'
# )
#
# # Get audit trail
# trail = audit_logger.get_audit_trail('permit', 'perm-456')
22. Scheduled Tasks (Python with APScheduler)
# scheduled_tasks.py
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.cron import CronTrigger
from datetime import datetime, timedelta
from typing import Callable
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
class ScheduledTasks:
"""Manage scheduled background tasks"""
def __init__(self, db_connection, email_service):
self.db = db_connection
self.email = email_service
self.scheduler = BackgroundScheduler()
def start(self):
"""Initialize and start all scheduled tasks"""
logger.info('Starting scheduled tasks...')
# Permit expiration reminders (daily at 9 AM)
self.scheduler.add_job(
func=self.send_permit_expiration_reminders,
trigger=CronTrigger(hour=9, minute=0),
id='permit_reminders',
name='Send permit expiration reminders',
replace_existing=True
)
# Monthly invoices (1st of month at midnight)
self.scheduler.add_job(
func=self.generate_monthly_invoices,
trigger=CronTrigger(day=1, hour=0, minute=0),
id='monthly_invoices',
name='Generate monthly invoices',
replace_existing=True
)
# Cleanup old audit logs (weekly on Sunday at 2 AM)
self.scheduler.add_job(
func=self.cleanup_old_audit_logs,
trigger=CronTrigger(day_of_week='sun', hour=2, minute=0),
id='cleanup_audit',
name='Cleanup old audit logs',
replace_existing=True
)
self.scheduler.start()
logger.info(f'{len(self.scheduler.get_jobs())} scheduled tasks started')
def send_permit_expiration_reminders(self):
"""Send reminders for expiring permits"""
logger.info('Running: Send permit expiration reminders')
try:
# 30-day reminders
thirty_days = datetime.now() + timedelta(days=30)
permits_30 = self.db.permits.find({
'expiration_date': {
'$gte': thirty_days.replace(hour=0, minute=0, second=0),
'$lt': thirty_days.replace(hour=23, minute=59, second=59)
},
'status': 'active',
'reminder_30_days_sent': {'$ne': True}
})
count_30 = 0
for permit in permits_30:
self.email.send(
to=permit['applicant_email'],
subject='Permit Expiring in 30 Days',
template='permit_expiration_30days',
data={'permit': permit}
)
self.db.permits.update_one(
{'_id': permit['_id']},
{'$set': {'reminder_30_days_sent': True}}
)
count_30 += 1
# 7-day reminders
seven_days = datetime.now() + timedelta(days=7)
permits_7 = self.db.permits.find({
'expiration_date': {
'$gte': seven_days.replace(hour=0, minute=0, second=0),
'$lt': seven_days.replace(hour=23, minute=59, second=59)
},
'status': 'active',
'reminder_7_days_sent': {'$ne': True}
})
count_7 = 0
for permit in permits_7:
self.email.send(
to=permit['applicant_email'],
subject='URGENT: Permit Expiring in 7 Days',
template='permit_expiration_7days',
data={'permit': permit}
)
self.db.permits.update_one(
{'_id': permit['_id']},
{'$set': {'reminder_7_days_sent': True}}
)
count_7 += 1
logger.info(f'Sent {count_30} 30-day and {count_7} 7-day reminders')
except Exception as e:
logger.error(f'Failed to send permit reminders: {e}')
self.alert_ops('permit_reminders', str(e))
def generate_monthly_invoices(self):
"""Generate invoices for all active subscriptions"""
logger.info('Running: Generate monthly invoices')
try:
customers = self.db.customers.find({'subscription_active': True})
count = 0
for customer in customers:
invoice = self.create_invoice(customer)
self.email.send(
to=customer['email'],
subject=f'Invoice for {datetime.now().strftime("%B %Y")}',
template='monthly_invoice',
data={'customer': customer, 'invoice': invoice}
)
count += 1
logger.info(f'Generated {count} monthly invoices')
except Exception as e:
logger.error(f'Failed to generate invoices: {e}')
self.alert_ops('monthly_invoices', str(e))
def cleanup_old_audit_logs(self):
"""Remove audit logs older than retention period"""
logger.info('Running: Cleanup old audit logs')
try:
retention_days = 365 # Keep 1 year
cutoff_date = datetime.now() - timedelta(days=retention_days)
result = self.db.audit_log.delete_many({
'timestamp': {'$lt': cutoff_date.isoformat()}
})
logger.info(f'Deleted {result.deleted_count} old audit logs')
except Exception as e:
logger.error(f'Failed to cleanup audit logs: {e}')
self.alert_ops('cleanup_audit', str(e))
def alert_ops(self, task_name: str, error: str):
"""Alert operations team of task failure"""
self.email.send(
to='ops@company.com',
subject=f'Scheduled Task Failure: {task_name}',
body=f'Task {task_name} failed with error: {error}'
)
def shutdown(self):
"""Gracefully shutdown scheduler"""
logger.info('Shutting down scheduled tasks...')
self.scheduler.shutdown(wait=True)
logger.info('Scheduled tasks stopped')
# Usage:
# from pymongo import MongoClient
# from email_service import EmailService
#
# db = MongoClient('mongodb://localhost:27017/').permits_db
# email = EmailService()
#
# tasks = ScheduledTasks(db, email)
# tasks.start()
#
# # Keep running
# try:
# while True:
# time.sleep(1)
# except (KeyboardInterrupt, SystemExit):
# tasks.shutdown()
23. React Error Boundary
// components/ErrorBoundary.tsx
import React, { Component, ReactNode } from 'react';
interface Props {
children: ReactNode;
fallback?: ReactNode;
onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
}
interface State {
hasError: boolean;
error: Error | null;
}
export class ErrorBoundary extends Component<Props, State> {
constructor(props: Props) {
super(props);
this.state = {
hasError: false,
error: null,
};
}
static getDerivedStateFromError(error: Error): State {
return {
hasError: true,
error,
};
}
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
// Log error to service
console.error('Error caught by boundary:', error, errorInfo);
// Call custom error handler
if (this.props.onError) {
this.props.onError(error, errorInfo);
}
// Send to error tracking service
if (process.env.NODE_ENV === 'production') {
// Example: Sentry
// Sentry.captureException(error, { contexts: { react: errorInfo } });
}
}
handleReset = () => {
this.setState({
hasError: false,
error: null,
});
};
render() {
if (this.state.hasError) {
if (this.props.fallback) {
return this.props.fallback;
}
return (
<div className="error-boundary">
<h2>Something went wrong</h2>
<details style={{ whiteSpace: 'pre-wrap' }}>
<summary>Error details</summary>
{this.state.error?.toString()}
</details>
<button onClick={this.handleReset}>
Try again
</button>
</div>
);
}
return this.props.children;
}
}
// Usage:
// <ErrorBoundary
// fallback={<div>Custom error UI</div>}
// onError={(error, info) => {
// logErrorToService(error, info);
// }}
// >
// <MyComponent />
// </ErrorBoundary>
Testing Templates
24. Unit Test Template (Jest + React Testing Library)
// __tests__/ValidatedField.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ValidatedField } from '../components/ValidatedField';
describe('ValidatedField', () => {
const mockOnChange = jest.fn();
beforeEach(() => {
mockOnChange.mockClear();
});
test('renders label and input', () => {
render(
<ValidatedField
label="Email"
name="email"
value=""
onChange={mockOnChange}
/>
);
expect(screen.getByLabelText('Email')).toBeInTheDocument();
});
test('shows required indicator when required', () => {
render(
<ValidatedField
label="Email"
name="email"
value=""
onChange={mockOnChange}
required
/>
);
expect(screen.getByText('*')).toBeInTheDocument();
});
test('validates email format on blur', async () => {
const emailRules = [
{
validate: (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
message: 'Please enter a valid email address',
},
];
render(
<ValidatedField
label="Email"
name="email"
value=""
onChange={mockOnChange}
rules={emailRules}
/>
);
const input = screen.getByLabelText('Email');
// Enter invalid email
await userEvent.type(input, 'invalid-email');
fireEvent.blur(input);
// Wait for validation
await waitFor(() => {
expect(screen.getByText('Please enter a valid email address')).toBeInTheDocument();
});
// Enter valid email
await userEvent.clear(input);
await userEvent.type(input, 'valid@email.com');
fireEvent.blur(input);
// Error should disappear
await waitFor(() => {
expect(screen.queryByText('Please enter a valid email address')).not.toBeInTheDocument();
});
});
test('calls onChange with correct values', async () => {
render(
<ValidatedField
label="Name"
name="name"
value=""
onChange={mockOnChange}
/>
);
const input = screen.getByLabelText('Name');
await userEvent.type(input, 'John');
expect(mockOnChange).toHaveBeenCalledWith('name', 'John');
});
test('shows async validation error', async () => {
const asyncValidation = jest.fn().mockResolvedValue('Username already taken');
render(
<ValidatedField
label="Username"
name="username"
value=""
onChange={mockOnChange}
asyncValidation={asyncValidation}
/>
);
const input = screen.getByLabelText('Username');
await userEvent.type(input, 'existinguser');
fireEvent.blur(input);
// Should show loading state
await waitFor(() => {
expect(screen.getByText('Checking...')).toBeInTheDocument();
});
// Should show error
await waitFor(() => {
expect(screen.getByText('Username already taken')).toBeInTheDocument();
});
expect(asyncValidation).toHaveBeenCalledWith('existinguser');
});
});
25. Integration Test Template (API Testing)
// __tests__/permits.integration.test.ts
import request from 'supertest';
import { app } from '../app';
import { db } from '../database';
describe('Permits API', () => {
let authToken: string;
let testPermitId: string;
beforeAll(async () => {
// Connect to test database
await db.connect(process.env.TEST_DATABASE_URL);
// Create test user and get auth token
const response = await request(app)
.post('/api/auth/login')
.send({
email: 'test@example.com',
password: 'testpassword',
});
authToken = response.body.token;
});
afterAll(async () => {
// Cleanup test data
await db.permits.deleteMany({ test: true });
await db.disconnect();
});
describe('POST /api/permits', () => {
test('creates a new permit with valid data', async () => {
const permitData = {
propertyAddress: '123 Main St',
parcelNumber: '14-21-356-003',
deckSize: 150,
zoning: 'R-1',
distanceFromProperty: 12,
contractorLicense: 'ABC-123456',
test: true, // Mark as test data
};
const response = await request(app)
.post('/api/permits')
.set('Authorization', `Bearer ${authToken}`)
.send(permitData)
.expect(201);
expect(response.body).toMatchObject({
propertyAddress: '123 Main St',
status: 'submitted',
});
testPermitId = response.body.id;
});
test('rejects permit with invalid data', async () => {
const invalidData = {
propertyAddress: '123 Main St',
// Missing required fields
};
const response = await request(app)
.post('/api/permits')
.set('Authorization', `Bearer ${authToken}`)
.send(invalidData)
.expect(400);
expect(response.body.error).toBe('Validation failed');
expect(response.body.details).toHaveLength(greaterThan(0));
});
test('enforces zoning rules', async () => {
const invalidZoning = {
propertyAddress: '123 Main St',
parcelNumber: '14-21-356-003',
deckSize: 200, // Exceeds R-1 limit
zoning: 'R-1',
distanceFromProperty: 12,
contractorLicense: 'ABC-123456',
test: true,
};
const response = await request(app)
.post('/api/permits')
.set('Authorization', `Bearer ${authToken}`)
.send(invalidZoning)
.expect(422);
expect(response.body.message).toContain('variance');
});
});
describe('GET /api/permits/:id', () => {
test('retrieves permit by ID', async () => {
const response = await request(app)
.get(`/api/permits/${testPermitId}`)
.set('Authorization', `Bearer ${authToken}`)
.expect(200);
expect(response.body.id).toBe(testPermitId);
expect(response.body.propertyAddress).toBe('123 Main St');
});
test('returns 404 for non-existent permit', async () => {
await request(app)
.get('/api/permits/nonexistent-id')
.set('Authorization', `Bearer ${authToken}`)
.expect(404);
});
});
describe('PUT /api/permits/:id', () => {
test('updates permit', async () => {
const updates = {
deckSize: 140, // Reduced size
};
const response = await request(app)
.put(`/api/permits/${testPermitId}`)
.set('Authorization', `Bearer ${authToken}`)
.send(updates)
.expect(200);
expect(response.body.deckSize).toBe(140);
});
test('creates audit log entry', async () => {
// Check audit trail
const auditLog = await db.auditLog.findOne({
entityType: 'permit',
entityId: testPermitId,
action: 'update',
});
expect(auditLog).toBeTruthy();
expect(auditLog.userId).toBe('test-user-id');
});
});
describe('Workflow integration', () => {
test('progresses through approval workflow', async () => {
// Submit for approval
await request(app)
.post(`/api/permits/${testPermitId}/submit`)
.set('Authorization', `Bearer ${authToken}`)
.expect(200);
let permit = await db.permits.findById(testPermitId);
expect(permit.status).toBe('pending_review');
// Approve (as inspector)
await request(app)
.post(`/api/permits/${testPermitId}/approve`)
.set('Authorization', `Bearer ${inspectorToken}`)
.expect(200);
permit = await db.permits.findById(testPermitId);
expect(permit.status).toBe('approved');
});
});
});
Deployment & CI/CD Templates
26. Docker Configuration
# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
# Copy package files
COPY package*.json ./
COPY tsconfig.json ./
# Install dependencies
RUN npm ci
# Copy source code
COPY src ./src
# Build TypeScript
RUN npm run build
# Production image
FROM node:18-alpine
WORKDIR /app
# Install production dependencies only
COPY package*.json ./
RUN npm ci --production
# Copy built files from builder
COPY --from=builder /app/dist ./dist
# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
adduser -S nodejs -u 1001
# Set ownership
RUN chown -R nodejs:nodejs /app
# Switch to non-root user
USER nodejs
# Expose port
EXPOSE 3000
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
# Start application
CMD ["node", "dist/server.js"]
# docker-compose.yml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DATABASE_URL=mongodb://mongo:27017/permits
- REDIS_URL=redis://redis:6379
depends_on:
- mongo
- redis
restart: unless-stopped
mongo:
image: mongo:6
volumes:
- mongo-data:/data/db
ports:
- "27017:27017"
restart: unless-stopped
redis:
image: redis:7-alpine
volumes:
- redis-data:/data
ports:
- "6379:6379"
restart: unless-stopped
volumes:
mongo-data:
redis-data:
27. GitHub Actions CI/CD
# .github/workflows/ci-cd.yml
name: CI/CD Pipeline
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
jobs:
test:
runs-on: ubuntu-latest
services:
mongodb:
image: mongo:6
ports:
- 27017:27017
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run type check
run: npm run type-check
- name: Run tests
run: npm test
env:
TEST_DATABASE_URL: mongodb://localhost:27017/permits_test
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/coverage-final.json
build:
needs: test
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Build application
run: |
npm ci
npm run build
- name: Build Docker image
run: |
docker build -t myapp:${{ github.sha }} .
docker tag myapp:${{ github.sha }} myapp:latest
- name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Push to Docker Hub
run: |
docker push myapp:${{ github.sha }}
docker push myapp:latest
deploy:
needs: build
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- name: Deploy to production
uses: appleboy/ssh-action@master
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_KEY }}
script: |
cd /app
docker pull myapp:latest
docker-compose down
docker-compose up -d
docker system prune -f