tinker_tickets/README.md

Tinker Tickets

A feature-rich PHP-based ticketing system designed for tracking and managing data center infrastructure issues with enterprise-grade workflow management.

Core Features

Dashboard & Ticket Management

• Smart Dashboard: Sortable columns, advanced filtering by status/priority/category/type
• Full-Text Search: Search across tickets, descriptions, and metadata
• Ticket Assignment: Assign tickets to specific users with quick-assign from dashboard
• Priority Tracking: P1 (Critical) to P5 (Minimal Impact) with color-coded indicators
• Custom Categories: Hardware, Software, Network, Security, General
• Ticket Types: Maintenance, Install, Task, Upgrade, Issue, Problem
• Export: Export selected tickets to CSV or JSON format

Workflow Management

• Status Transitions: Enforced workflow rules (Open → Pending → In Progress → Closed)
• Workflow Designer: Visual admin UI at /admin/workflow to configure transitions
• Workflow Validation: Server-side validation prevents invalid status changes
• Admin Controls: Certain transitions can require admin privileges
• Comment Requirements: Optional comment requirements for specific transitions

Collaboration Features

• Markdown Comments: Full Markdown support with live preview and toolbar
• @Mentions: Tag users in comments with autocomplete
• File Attachments: Upload files to tickets with drag-and-drop support
• Ticket Dependencies: Link tickets as blocks/blocked-by/relates-to/duplicates
• Activity Timeline: Complete audit trail of all ticket changes

Ticket Templates

• Template Management: Admin UI at /admin/templates to create/edit templates
• Quick Creation: Pre-configured templates for common issues
• Auto-fill: Templates populate title, description, category, type, and priority

Recurring Tickets

• Scheduled Tickets: Automatically create tickets on a schedule
• Admin UI: Manage at /admin/recurring-tickets
• Flexible Scheduling: Daily, weekly, or monthly recurrence
• Cron Integration: Run cron/create_recurring_tickets.php to process

Custom Fields

• Per-Category Fields: Define custom fields for specific ticket categories
• Admin UI: Manage at /admin/custom-fields
• Field Types: Text, textarea, select, checkbox, date, number
• Required Fields: Mark fields as required for validation

User Management & Authentication

• SSO Integration: Authelia authentication with LLDAP backend
• Role-Based Access: Admin and standard user roles
• User Activity: View per-user stats at /admin/user-activity
• Session Management: Secure PHP session handling with timeout

Bulk Actions (Admin Only)

• Bulk Close: Close multiple tickets at once
• Bulk Assign: Assign multiple tickets to a user
• Bulk Priority: Change priority for multiple tickets
• Bulk Status: Change status for multiple tickets

Admin Pages

Route	Description
/admin/recurring-tickets	Manage recurring ticket schedules
/admin/custom-fields	Define custom fields per category
/admin/workflow	Visual workflow transition designer
/admin/templates	Create and edit ticket templates
/admin/audit-log	Browse all audit log entries
/admin/user-activity	View per-user activity statistics

Notifications

• Discord Integration: Webhook notifications for ticket creation and updates
• Rich Embeds: Color-coded priority indicators and ticket links

Security Features

• CSRF Protection: Token-based protection on all forms
• Rate Limiting: API rate limiting to prevent abuse
• Security Headers: CSP, X-Frame-Options, X-Content-Type-Options
• SQL Injection Prevention: All queries use prepared statements
• XSS Protection: All output properly escaped
• Audit Logging: Complete audit trail of all actions

Technical Architecture

Backend

• Language: PHP 7.4+
• Database: MariaDB/MySQL
• Architecture: MVC pattern with models, views, controllers

Frontend

• HTML5/CSS3: Semantic markup with modern CSS
• JavaScript: Vanilla JS with Fetch API for AJAX
• Markdown: Custom markdown parser with toolbar

Database Tables

Table	Purpose
tickets	Core ticket data
ticket_comments	Markdown-supported comments
ticket_attachments	File attachment metadata
ticket_dependencies	Ticket relationships
users	User accounts synced from LLDAP
user_preferences	User settings and preferences
audit_log	Complete audit trail
status_transitions	Workflow configuration
ticket_templates	Reusable ticket templates
recurring_tickets	Scheduled ticket definitions
custom_field_definitions	Custom field schemas
custom_field_values	Custom field data per ticket
saved_filters	User-saved dashboard filters

API Endpoints

Endpoint	Method	Description
/api/update_ticket.php	POST	Update ticket with workflow validation
/api/assign_ticket.php	POST	Assign ticket to user
/api/add_comment.php	POST	Add comment to ticket
/api/get_template.php	GET	Fetch ticket template
/api/get_users.php	GET	Get user list for assignments
/api/bulk_operation.php	POST	Perform bulk operations
/api/ticket_dependencies.php	GET/POST/DELETE	Manage ticket dependencies
/api/upload_attachment.php	GET/POST	List or upload attachments
/api/delete_attachment.php	POST/DELETE	Delete attachment
/api/export_tickets.php	GET	Export tickets to CSV/JSON
/api/check_duplicates.php	GET	Check for duplicate tickets

Setup & Configuration

1. Environment Configuration

Create .env file in project root:

DB_HOST=10.10.10.50
DB_USER=tinkertickets
DB_PASS=your_password
DB_NAME=ticketing_system
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

2. Database Setup

The database schema is managed through migrations. For a fresh install, run all migrations in order using the migration runner.

3. Cron Jobs

Add to crontab for recurring tickets:

# Run every hour to create scheduled recurring tickets
0 * * * * php /var/www/html/tinkertickets/cron/create_recurring_tickets.php

Optional cleanup job:

# Run weekly to clean up orphaned upload files
0 2 * * 0 php /var/www/html/tinkertickets/scripts/cleanup_orphan_uploads.php

4. File Uploads

Ensure the uploads/ directory exists and is writable:

mkdir -p /var/www/html/tinkertickets/uploads
chown www-data:www-data /var/www/html/tinkertickets/uploads
chmod 755 /var/www/html/tinkertickets/uploads

5. Authelia Integration

Tinker Tickets uses Authelia for SSO. User information is passed via headers:

• Remote-User: Username
• Remote-Name: Display name
• Remote-Email: Email address
• Remote-Groups: User groups (comma-separated)

Admin users must be in the admins group in LLDAP.

Project Structure

tinker_tickets/
├── api/                    # API endpoints
├── assets/                 # Static assets (CSS, JS)
├── config/                 # Configuration
├── controllers/            # MVC Controllers
├── cron/                   # Scheduled task scripts
├── helpers/                # Utility classes
├── middleware/             # Request middleware
├── models/                 # Data models
├── scripts/                # Maintenance scripts
├── uploads/                # File upload storage
├── views/                  # View templates
│   └── admin/              # Admin panel views
├── migrations/             # Database migrations
├── index.php               # Main router
└── .env                    # Environment configuration

Workflow States

Default Workflow

Open → Pending → In Progress → Closed
         ↑           ↑
         └───────────┘

All states can transition to Closed (with comment). Closed tickets can be reopened to Open or In Progress.

License

Internal use only - LotusGuild Infrastructure