the middle of the idiots

2025-10-24 16:29:40 -05:00
parent 6a58e19b10
commit 721301c779
2472 changed files with 237076 additions and 418 deletions
--- a/qwen/hack/ARCHITECTURE.md
+++ b/qwen/hack/ARCHITECTURE.md
@@ -0,0 +1,191 @@
+# 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