# Django Cronjob Utils - Documentation

## Overview

This documentation describes the PHP-based cronjob handling system that will be converted to a Django package. The system provides a robust middleware layer between OS-level cronjobs and application business logic.

## Documentation Structure

### Core Documentation

1. **[Architecture Overview](architecture-overview.md)**
   - System purpose and design
   - Component relationships
   - High-level architecture

2. **[CronBase Class](cronbase-class.md)**
   - Base class functionality
   - Database management
   - Error handling
   - Execution tracking

3. **[Cron Class](cron-class.md)**
   - Implementation details
   - Individual cronjob methods
   - Execution patterns
   - Dependencies

4. **[Execution Flow](execution-flow.md)**
   - Step-by-step execution process
   - State transitions
   - Special execution patterns
   - Error scenarios

5. **[Database Schema](database-schema.md)**
   - Table structures
   - Field descriptions
   - Indexes and queries
   - Migration considerations

6. **[Error Handling](error-handling.md)**
   - Error code system
   - Error types and handling
   - Logging mechanisms
   - Recovery strategies

## Key Concepts

### Execution Tracking

Every cronjob execution is tracked in the database with:
- Start and end timestamps
- Success/failure status
- Error codes and messages
- Date-based indexing for querying

### Duplicate Prevention

The system prevents duplicate executions through:
- Date-based checking (`is_cron_ran()`)
- Success-based checking (`is_cron_ran_success()`)
- Optional rerun flags

### Error Management

Comprehensive error handling includes:
- Hierarchical error codes
- Detailed logging
- Database error storage
- Critical error alerts

## System Flow

```
OS Cronjob
    ↓
Entry Point (PHP script)
    ↓
Cron::method()
    ↓
Validation → Duplicate Check → Record Start
    ↓
Business Logic Execution
    ↓
Update Completion Status
    ↓
Logging
```

## Common Patterns

### Standard Pattern
1. Validate input
2. Check if already executed
3. Record start
4. Execute business logic
5. Update completion

### Always Execute Pattern
1. Validate input
2. Record start (skip duplicate check)
3. Execute business logic
4. Update completion

### Rerun on Failure Pattern
1. Validate input
2. Check if successfully executed
3. Record start (if not successful)
4. Execute business logic
5. Update completion

## Conversion Considerations

When converting to Django, consider:

1. **Models**: Convert database tables to Django models
2. **Management Commands**: Use Django management commands instead of PHP scripts
3. **Error Handling**: Leverage Django's exception handling
4. **Logging**: Use Django's logging framework
5. **Testing**: Add comprehensive test coverage
6. **Configuration**: Use Django settings for configuration
7. **Admin Interface**: Consider Django admin for monitoring

## Known Issues

The PHP implementation has several issues to address in Django conversion:

1. **Undefined Variables**: Some methods reference `$rerun` without parameter
2. **Missing Initialization**: Some methods use `$result` without initialization
3. **Incomplete Methods**: `insert_bet_details()` has commented-out logic
4. **Inconsistent Patterns**: Some methods skip duplicate checks without clear reason

## Next Steps

1. Review this documentation
2. Identify enhancements for Django version
3. Design Django package structure
4. Implement core functionality
5. Add tests and documentation
6. Create migration scripts

## File Structure

```
docs/
├── README.md                 # This file
├── architecture-overview.md  # System architecture
├── cronbase-class.md        # Base class documentation
├── cron-class.md            # Implementation class
├── execution-flow.md         # Execution process details
├── database-schema.md        # Database structure
└── error-handling.md         # Error handling system
```

## References

- Original PHP files: `php/CronBase.class.php`, `php/Cron.class.php`
- Database tables: `cron`, `cron_rapid`
- Error codes: See [Error Handling](error-handling.md) documentation