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 and a retro terminal aesthetic.

Core Features

Dashboard & Ticket Management

• View Modes: Toggle between Table view and Kanban card view
• Collapsible Sidebar: Click the arrow to collapse/expand the filter sidebar
• Inline Ticket Preview: Hover over ticket IDs for a quick preview popup
• Stats Widgets: Clickable cards for quick filtering (Open, Critical, Unassigned, Today's tickets)
• Full-Text Search: Search across tickets, descriptions, and metadata
• Advanced Search: Date ranges, priority ranges, user filters with saved filter support
• 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
• Ticket Linking: Reference other tickets in comments using #123456789 format

Ticket Visibility Levels

• Public: All authenticated users can view the ticket
• Internal: Only users in specified groups can view the ticket
• Confidential: Only the creator, assignee, and admins can view the ticket

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, toolbar, and table rendering
• @Mentions: Tag users in comments with autocomplete
• Comment Edit/Delete: Comment owners and admins can edit or delete comments
• Auto-linking: URLs in comments are automatically converted to clickable links
• 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

API Key Management

• Admin UI: Generate and manage API keys at /admin/api-keys
• Bearer Token Auth: Use API keys with Authorization: Bearer YOUR_KEY header
• Expiration: Optional expiration dates for keys
• Revocation: Revoke compromised keys instantly

User Management & Authentication

• SSO Integration: Authelia authentication with LLDAP backend
• Role-Based Access: Admin and standard user roles
• User Groups: Groups displayed in settings modal, used for visibility
• 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
• Checkbox Click Area: Click anywhere in the checkbox cell to toggle

Admin Pages

Access all admin pages via the Admin dropdown in the dashboard header.

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

Notifications

• Discord Integration: Webhook notifications for ticket creation and updates
• Rich Embeds: Color-coded priority indicators and ticket links
• Dynamic URLs: Ticket links adapt to the server hostname

Keyboard Shortcuts

Shortcut	Action
Ctrl/Cmd + E	Toggle edit mode (ticket page)
Ctrl/Cmd + S	Save changes (ticket page)
Ctrl/Cmd + K	Focus search box (dashboard)
ESC	Cancel edit / close modal
?	Show keyboard shortcuts help

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 retro terminal styling
• JavaScript: Vanilla JS with Fetch API for AJAX
• Markdown: Custom markdown parser with toolbar
• Terminal UI: Box-drawing characters, monospace fonts, CRT effects
• Mobile Responsive: Touch-friendly controls, responsive layouts

Database Tables

Table	Purpose
tickets	Core ticket data with visibility
ticket_comments	Markdown-supported comments
ticket_attachments	File attachment metadata
ticket_dependencies	Ticket relationships
users	User accounts with groups
user_preferences	User settings
audit_log	Complete audit trail
status_transitions	Workflow configuration
ticket_templates	Reusable templates
recurring_tickets	Scheduled tickets
custom_field_definitions	Custom field schemas
custom_field_values	Custom field data
saved_filters	Saved filter combinations
api_keys	API key storage

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 dependencies
/api/upload_attachment.php	GET/POST	List or upload attachments
/api/export_tickets.php	GET	Export tickets to CSV/JSON
/api/generate_api_key.php	POST	Generate API key (admin)
/api/revoke_api_key.php	POST	Revoke API key (admin)

Setup & Configuration

1. Environment Configuration

Copy the example file and edit with your values:

cp .env.example .env
nano .env

Required environment variables:

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/...
TIMEZONE=America/New_York

2. 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

3. 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

4. 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 admin 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
├── 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