# 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