MOHPortalTest-AllAgents-AllLangs/qwen/hack/ARCHITECTURE.md

MerchantsOfHope.org - Architecture Documentation

Overview

MerchantsOfHope.org is a multi-tenant recruiting platform built with Hack/PHP, designed to serve multiple lines of business within TSYS Group while maintaining complete isolation between tenants.

System Architecture

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Load Balancer │────│    Nginx        │────│   Application   │
└─────────────────┘    │  (Reverse Proxy)│    │   (PHP/Hack)    │
                       └─────────────────┘    └─────────────────┘
                                                      │
┌─────────────────┐    ┌─────────────────┐    ┌──────▼──────────┐
│   Frontend      │    │    Caching      │    │  PostgreSQL     │
│   (React/Vue)   │    │    (Redis)      │    │   Database      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                      │
                                        ┌─────────────▼──────────┐
                                        │    Mail Service        │
                                        │    (SMTP/MailHog)      │
                                        └────────────────────────┘

Service Architecture

• Application Service: Main PHP/Hack application serving business logic
• Database Service: PostgreSQL for primary data storage
• Cache Service: Redis for session storage and caching
• Mail Service: SMTP service for email communications
• OAuth Services: External providers for authentication (Google, GitHub)

Multi-Tenancy Implementation

Tenant Isolation Strategy

1. Data Isolation: Each tenant's data is isolated using a tenant_id column in all relevant tables
2. Request Context: Tenant context is determined via subdomain (tenant.merchantsofhope.org) or path (merchantsofhope.org/tenant)
3. Database Queries: All data access queries include tenant_id filters to prevent cross-tenant data access

Tenant Resolution Flow

1. Request comes in with hostname or path
2. TenantMiddleware extracts tenant identifier
3. TenantResolverService looks up tenant information
4. Tenant information attached to request context
5. All subsequent operations validate tenant access

Security & Compliance

Authentication & Authorization

• OIDC Integration: Support for OpenID Connect providers
• Social Login: Google and GitHub OAuth integration
• JWT Tokens: Stateful authentication using JWT tokens
• Role-Based Access Control: Different permissions for job seekers vs job providers

Compliance Frameworks Implemented

1. USA Employment Law Compliance

• Anti-Discrimination: Validation to prevent discriminatory language in job postings
• Data Retention: Automatic anonymization of personal data after required periods
• Audit Logging: Complete audit trail for all data access

2. Accessibility (Section 508/WCAG 2.1 AA)

• Semantic HTML: Proper heading hierarchy and structure
• Alt Text: Required for all images
• Form Labels: Associated with input elements
• Color Contrast: Sufficient contrast ratios

3. PCI DSS Compliance

• No Sensitive Data Storage: PAN, CVV, and track data are never stored
• Proper Masking: When PAN is displayed, it's properly masked (first 6, last 4)
• Audit Logs: Logging of all access to payment-related data

4. GDPR Compliance

• Data Subject Rights: APIs to handle access, rectification, erasure, portability, and restriction requests
• Consent Management: Explicit consent for data processing
• Data Minimization: Only necessary data is collected

5. SOC 2 Compliance

• Access Controls: Proper authentication and authorization for all operations
• Audit Logging: Complete audit trail of all system access
• Change Management: Proper procedures for system changes

6. FedRAMP Compliance

• Security Controls: Implementation of required security controls based on data classification
• Continuous Monitoring: Ongoing assessment of security posture
• Incident Response: Defined procedures for security incidents

Application Components

Models

• User: Represents users (job seekers or job providers)
• Job: Represents job postings
• Application: Represents job applications
• Tenant: Represents individual tenants

Services

• TenantResolverService: Resolves tenant from request context
• JobService: Handles job-related operations with tenant isolation
• ApplicationService: Manages job applications
• AuthService: Handles authentication and OAuth flows
• ComplianceService: Ensures compliance with various regulations
• AccessibilityService: Validates and generates accessible content
• SecurityComplianceService: Handles security compliance requirements

Controllers

• HomeController: Basic home page
• AuthController: Authentication endpoints
• JobController: Job-related endpoints
• ApplicationController: Application-related endpoints

Middleware

• TenantMiddleware: Ensures tenant isolation for each request

API Design

RESTful Endpoints

• Consistent naming conventions
• Proper HTTP methods (GET, POST, PUT, DELETE)
• Standard response formats
• Proper status codes

Error Handling

• Consistent error response format
• Appropriate HTTP status codes
• Detailed error messages (only in development)

Database Design

Key Tables

• tenants: Tenant isolation information
• users: User accounts with tenant_id
• jobs: Job postings with tenant_id
• applications: Job applications with tenant_id
• audit_logs: Compliance audit logs

Indexing Strategy

• Indexes on tenant_id for all tenant-isolated tables
• Indexes on frequently queried fields
• Proper foreign key constraints

Deployment Architecture

Kubernetes Configuration

The application is designed for Kubernetes deployment with:

• Deployments: For application and service scaling
• Services: For internal and external networking
• ConfigMaps: For configuration management
• Secrets: For sensitive data like API keys
• PersistentVolumes: For data persistence
• Ingress: For external access and load balancing

Environment Configuration

• Separate configurations for development, staging, and production
• Environment-specific variable management
• Database migration strategy
• Backup and recovery procedures

Security Considerations

Input Validation

• Server-side validation for all inputs
• Sanitization of user-generated content
• Prevention of SQL injection and XSS attacks

Data Protection

• Encryption at rest for sensitive data
• Encryption in transit using HTTPS
• Proper session management
• Secure password handling

Monitoring & Logging

• Comprehensive audit logging
• Performance monitoring
• Security event monitoring
• Log aggregation and analysis

Performance Considerations

Caching Strategy

• Redis for session storage
• Redis for application-level caching
• Database query optimization
• Response caching where appropriate

Scalability

• Stateless application design
• Horizontal pod scaling in Kubernetes
• Database read replicas for read-heavy operations
• CDN for static assets