191 lines
7.7 KiB
Markdown
191 lines
7.7 KiB
Markdown
# 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 |