Repository docs from .qoder/repowiki

Terms and Conditions Acceptance

Referenced Files in This Document

• require-terms.middleware.ts
• user.route.ts
• user.controller.ts
• user.service.ts
• user.schema.ts
• audit-log.table.ts
• audit.service.ts
• record-audit.ts
• 0005_snapshot.json
• TermsForm.tsx
• auth.controller.ts
• auth.service.ts
• onboarding-error-handler.tsx

Table of Contents

1. Introduction
2. System Architecture
3. Core Components
4. Terms Acceptance Workflow
5. Audit Logging Implementation
6. Compliance Tracking
7. Integration with Authentication System
8. User Onboarding Process
9. Terms Version Management
10. API Endpoints
11. Troubleshooting Guide
12. Conclusion

Introduction

The Terms and Conditions Acceptance System is a critical compliance mechanism designed to ensure all users acknowledge and agree to the platform's terms before accessing core platform features. This system implements a multi-layered approach combining frontend user interface controls, backend enforcement mechanisms, comprehensive audit logging, and integration with the authentication and onboarding workflows.

The system operates on the principle that user engagement with platform features requires explicit consent to terms, creating a legally and technically enforceable acceptance record. This documentation provides comprehensive coverage of the implementation, workflows, and operational procedures.

System Architecture

The Terms Acceptance System follows a distributed architecture pattern with clear separation of concerns across frontend, backend, and database layers:

graph TB
subgraph "Frontend Layer"
TF[TermsForm Component]
UE[User Experience]
end
subgraph "API Gateway"
AR[API Routes]
AM[Auth Middleware]
TM[Terms Middleware]
end
subgraph "Business Logic"
UC[User Controller]
US[User Service]
AS[Auth Service]
end
subgraph "Persistence Layer"
DB[(PostgreSQL Database)]
AL[Audit Logs Table)]
end
subgraph "Compliance Layer"
RS[Record Audit Service]
AC[Audit Context]
end
TF --> AR
UE --> AR
AR --> AM
AM --> TM
TM --> UC
UC --> US
US --> DB
US --> RS
RS --> AC
AC --> AL
AS --> DB

Diagram sources

• user.route.ts
• require-terms.middleware.ts
• user.controller.ts
• user.service.ts
• audit-log.table.ts

Core Components

Frontend Terms Interface

The frontend implementation provides an intuitive user interface for terms acceptance through the TermsForm component, which presents users with platform terms and requires explicit consent before granting access to platform features.

Backend Enforcement Layer

The system implements a multi-tier enforcement mechanism through middleware components that intercept requests and validate terms acceptance status before allowing access to protected resources.

Audit and Compliance Engine

A comprehensive audit logging system captures all terms-related activities with detailed metadata for compliance reporting and legal requirements.

Section sources

• TermsForm.tsx
• require-terms.middleware.ts
• audit-log.table.ts

Terms Acceptance Workflow

The terms acceptance workflow follows a structured process ensuring user consent while maintaining system integrity and compliance requirements.

sequenceDiagram
participant U as User
participant F as TermsForm
participant A as API Gateway
participant C as User Controller
participant S as User Service
participant D as Database
participant L as Audit Logger
U->>F : View Terms Page
F->>U : Display Terms Content
U->>F : Accept Terms Checkbox
F->>A : Submit Acceptance Request
A->>C : POST /user/accept-terms
C->>S : acceptTerms(userId, authId)
S->>D : Update is_accepted_terms = true
S->>L : Record audit entry
L-->>S : Log stored
S-->>C : Success
C-->>A : Terms accepted successfully
A-->>F : Response
F-->>U : Access granted

Diagram sources

• user.controller.ts
• user.service.ts
• record-audit.ts

Workflow Phases

1. Terms Presentation Phase: Users encounter the TermsForm component displaying platform terms
2. Consent Collection Phase: Users explicitly check the acceptance checkbox
3. Validation Phase: System validates user authentication and terms status
4. Acceptance Processing Phase: Database updates reflect terms acceptance
5. Audit Recording Phase: Comprehensive audit trail is generated
6. Access Granting Phase: User gains access to platform features

Section sources

• TermsForm.tsx
• user.controller.ts
• user.service.ts

Audit Logging Implementation

The audit logging system provides comprehensive tracking of all terms-related activities with detailed metadata for compliance and legal requirements.

Audit Log Schema

The audit log table structure captures essential information for compliance reporting and legal discovery:

| Field | Type | Description | Required | |-------|------|-------------|----------| | id | UUID | Primary key with random default | Yes | | occured_at | TIMESTAMP WITH TIME ZONE | Timestamp of event occurrence | Yes | | actor_id | TEXT | Identifier of acting user/system | No | | actor_type | ENUM | Role type (user, system, admin, service) | Yes | | action | TEXT | Specific action performed | Yes | | entity_type | ENUM | Type of affected entity | Yes | | entity_id | TEXT | Identifier of affected entity | No | | before | JSONB | State before change | No | | after | JSONB | State after change | No | | ip_address | INET | IP address of request origin | No | | user_agent | TEXT | Browser/device information | No | | request_id | UUID | Correlation identifier | No | | reason | TEXT | Explanation for action | No | | metadata | JSONB | Additional contextual data | No |

Audit Event Types

The system generates specific audit events for terms acceptance activities:

flowchart TD
A[Terms Acceptance Event] --> B[user:accepted:terms]
A --> C[other:action]
B --> D[Entity: User]
B --> E[Change: isAcceptedTerms false → true]
B --> F[Actor: User]
B --> G[Metadata: Device info, IP, User-Agent]
C --> H[Entity: User Profile]
C --> I[Change: Branch update]
C --> J[Actor: System/User]

Diagram sources

• audit-log.table.ts
• record-audit.ts

Section sources

• audit-log.table.ts
• audit.service.ts
• record-audit.ts

Compliance Tracking

The compliance tracking system ensures regulatory adherence through comprehensive monitoring and reporting capabilities.

Compliance Features

1. Legal Discovery Support: Complete audit trails enable legal discovery processes
2. Regulatory Reporting: Structured data export for compliance reporting
3. Temporal Tracking: Full history of user consent and changes
4. Device Fingerprinting: Comprehensive device and browser identification
5. Geolocation Integration: IP-based geographic tracking capabilities

Compliance Indicators

The system maintains several key indicators for compliance monitoring:

• Consent Verification: Timestamped evidence of user acceptance
• Change Auditing: Complete modification history for sensitive fields
• Access Control: Real-time enforcement of terms requirements
• Reporting Metrics: Aggregate statistics for compliance reporting

Section sources

• audit.service.ts
• record-audit.ts

Integration with Authentication System

The terms acceptance system integrates seamlessly with the authentication framework, ensuring that user consent is required before granting access to authenticated features.

Authentication Integration Points

graph LR
subgraph "Authentication Flow"
AU[Auth User] --> TA[Terms Required]
TA --> UA[User Active]
TA --> NA[Not Accepted]
end
subgraph "Middleware Chain"
AM[Auth Middleware] --> TM[Terms Middleware]
TM --> RF[Route Functions]
end
subgraph "User States"
UA --> AC[Access Granted]
NA --> TR[Terms Required]
end

Diagram sources

• require-terms.middleware.ts
• auth.controller.ts

Integration Benefits

1. Seamless User Experience: Terms acceptance occurs naturally within the authentication flow
2. State Consistency: User state reflects both authentication and terms acceptance
3. Security Enhancement: Prevents access to authenticated features without consent
4. Compliance Automation: Automatic enforcement of terms requirements

Section sources

• require-terms.middleware.ts
• auth.controller.ts

User Onboarding Process

The terms acceptance system integrates with the broader user onboarding process, creating a comprehensive user lifecycle management approach.

Onboarding Workflow Integration

stateDiagram-v2
[*] --> Registration
Registration --> TermsReview
TermsReview --> TermsAccepted
TermsAccepted --> ProfileCompletion
ProfileCompletion --> ActiveUser
TermsReview --> TermsRejected
TermsRejected --> TermsReview
ActiveUser --> [*]

Onboarding State Management

The system manages user states through distinct phases:

1. Registration Phase: Initial user creation with ONBOARDING status
2. Terms Review Phase: User presented with terms for acceptance
3. Terms Accepted Phase: User granted basic platform access
4. Profile Completion Phase: Additional user information collection
5. Active User Phase: Full platform access granted

Section sources

• auth.service.ts
• 0005_snapshot.json

Terms Version Management

The system supports terms version management through database schema evolution and audit trail maintenance.

Database Schema Evolution

The user table includes explicit terms acceptance tracking through the is_accepted_terms field, enabling version-specific compliance tracking:

erDiagram
USER {
uuid id PK
text auth_id FK
text username
uuid college_id
text branch
integer karma
boolean is_accepted_terms
user_status status
}
AUDIT_LOGS {
uuid id PK
timestamp occured_at
text actor_id
text actor_type
text action
text entity_type
text entity_id
jsonb before
jsonb after
inet ip_address
text user_agent
uuid request_id
text reason
jsonb metadata
}
USER ||--o{ AUDIT_LOGS : affects

Diagram sources

• 0005_snapshot.json
• audit-log.table.ts

Version Control Implementation

The system maintains version control through:

1. Schema Evolution: Database migrations support terms field modifications
2. Audit History: Complete change history for terms acceptance
3. Backward Compatibility: Support for legacy terms versions
4. Compliance Archival: Historical records for legal requirements

Section sources

• 0005_snapshot.json
• audit-log.table.ts

API Endpoints

The system exposes dedicated API endpoints for terms management and acceptance workflows.

Terms Management Endpoints

| Endpoint | Method | Description | Authentication | Response | |----------|--------|-------------|----------------|----------| | /user/accept-terms | POST | Accept platform terms and conditions | Required | Success/Failure | | /user/me | GET | Get current user profile | Required | User data | | /user/me | PATCH | Update user profile | Required | Updated user data |

Request/Response Patterns

The API follows consistent patterns for terms-related operations:

Accept Terms Request

{
  "headers": {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  "body": {}
}

Accept Terms Response

{
  "status": "success",
  "message": "Terms accepted successfully",
  "data": null
}

Section sources

• user.route.ts
• user.controller.ts

Troubleshooting Guide

Common issues and resolution strategies for the terms acceptance system.

Terms Not Accepted Errors

Symptoms: Users receive "Terms not accepted" errors when accessing platform features

Causes:

1. User has not yet accepted terms
2. Authentication session expired
3. Database synchronization issues

Resolutions:

1. Redirect users to terms acceptance page
2. Refresh authentication tokens
3. Clear application cache and retry

Audit Logging Issues

Symptoms: Missing or incomplete audit records for terms acceptance

Causes:

1. Network connectivity issues during logging
2. Database write failures
3. Context extraction errors

Resolutions:

1. Implement retry mechanisms for audit logging
2. Monitor database connection health
3. Validate context extraction processes

Frontend Integration Problems

Symptoms: Terms acceptance form not displaying properly

Causes:

1. JavaScript errors blocking form rendering
2. Missing dependencies
3. Authentication state inconsistencies

Resolutions:

1. Check browser console for JavaScript errors
2. Verify all required dependencies are loaded
3. Ensure user authentication state is properly established

Section sources

• require-terms.middleware.ts
• onboarding-error-handler.tsx

Conclusion

The Terms and Conditions Acceptance System provides a robust, compliant solution for managing user consent within the platform. Through its multi-layered architecture, comprehensive audit logging, and seamless integration with authentication and onboarding workflows, the system ensures legal compliance while maintaining excellent user experience.

Key strengths of the implementation include:

• Comprehensive Audit Trail: Complete tracking of all terms-related activities
• Real-time Enforcement: Immediate validation of terms acceptance requirements
• Scalable Architecture: Distributed design supporting high-volume operations
• Compliance Ready: Structured data capture meeting legal and regulatory requirements
• User-Friendly Interface: Intuitive terms acceptance process minimizing friction

The system's modular design enables future enhancements such as terms versioning, automated compliance reporting, and advanced analytics capabilities while maintaining backward compatibility and system stability.