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 "Assigned To" column
• 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

🔄 Workflow Management

• Status Transitions: Enforced workflow rules (Open → In Progress → Resolved → Closed)
• 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
• Activity Timeline: Complete audit trail of all ticket changes

💬 Collaboration Features

• Markdown Comments: Full Markdown support with live preview
• User Tracking: Tracks who created, updated, and assigned tickets
• Activity Timeline: Shows all ticket events (creates, updates, assignments, comments)
• Real-time Updates: AJAX-powered updates without page refreshes

🎫 Ticket Templates

• Quick Creation: Pre-configured templates for common issues
• Default Templates: Hardware Failure, Software Installation, Network Issue, Maintenance
• Auto-fill: Templates populate title, description, category, type, and priority

👥 User Management & Authentication

• SSO Integration: Authelia authentication with LLDAP backend
• Role-Based Access: Admin and standard user roles
• User Display Names: Support for display names and usernames
• Session Management: Secure PHP session handling

⚡ 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
• Operation Tracking: All bulk operations logged in audit trail

🔔 Notifications

• Discord Integration: Webhook notifications for ticket creation and updates
• Rich Embeds: Color-coded priority indicators and ticket links
• Change Tracking: Detailed notification of what changed

🎨 User Interface

• Dark Mode: Full dark mode support with proper contrast
• Responsive Design: Works on desktop and mobile devices
• Clean Layout: Modern, intuitive interface
• Hamburger Menu: Quick access to ticket actions (priority, category, type)

🏗️ Technical Architecture

Backend

• Language: PHP 7.4+
• Database: MariaDB/MySQL
• Architecture: MVC pattern with models, views, controllers
• ORM: Custom database abstraction layer

Frontend

• HTML5/CSS3: Semantic markup with modern CSS
• JavaScript: Vanilla JS with Fetch API for AJAX
• Markdown: marked.js for Markdown rendering
• Icons: Unicode emoji icons

Database Schema

• tickets: Core ticket data with user tracking
• comments: Markdown-supported comments
• users: User accounts synced from LLDAP
• audit_log: Complete audit trail with JSON details
• status_transitions: Workflow configuration
• ticket_templates: Reusable ticket templates
• bulk_operations: Tracking for bulk admin operations

API Endpoints

• /api/update_ticket.php - Update ticket with workflow validation
• /api/assign_ticket.php - Assign ticket to user
• /api/add_comment.php - Add comment to ticket
• /api/get_template.php - Fetch ticket template
• /api/get_users.php - Get user list for assignments
• /api/bulk_operation.php - Perform bulk operations (admin only)

🚀 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

Run migrations in order:

# Navigate to project directory
cd /root/code/tinker_tickets

# Run each migration
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/001_initial_schema.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/007_add_ticket_assignment.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/008_add_status_workflows.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/009_add_ticket_templates.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/010_add_bulk_operations.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/011_remove_view_tracking.sql

3. Web Server Configuration

Apache Configuration (recommended):

<VirtualHost *:80>
    ServerName t.lotusguild.org
    DocumentRoot /root/code/tinker_tickets

    <Directory /root/code/tinker_tickets>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted

        # Enable mod_rewrite for clean URLs
        RewriteEngine On
        RewriteBase /

        # Route ticket URLs
        RewriteRule ^ticket/([0-9]+)$ ticket.php?id=$1 [L,QSA]

        # Route ticket create
        RewriteRule ^ticket/create$ ticket.php?action=create [L,QSA]
    </Directory>
</VirtualHost>

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 admins group in LLDAP.

📁 Project Structure

tinker_tickets/
├── api/                    # API endpoints
│   ├── add_comment.php
│   ├── assign_ticket.php
│   ├── bulk_operation.php
│   ├── get_template.php
│   ├── get_users.php
│   └── update_ticket.php
├── assets/                 # Static assets
│   ├── css/
│   │   ├── dashboard.css
│   │   └── ticket.css
│   └── js/
│       ├── dashboard.js
│       └── ticket.js
├── config/                 # Configuration
│   └── config.php
├── controllers/            # MVC Controllers
│   ├── DashboardController.php
│   └── TicketController.php
├── models/                 # Data models
│   ├── AuditLogModel.php
│   ├── BulkOperationsModel.php
│   ├── CommentModel.php
│   ├── TemplateModel.php
│   ├── TicketModel.php
│   ├── UserModel.php
│   └── WorkflowModel.php
├── views/                  # View templates
│   ├── CreateTicketView.php
│   ├── DashboardView.php
│   └── TicketView.php
├── migrations/             # Database migrations
│   ├── 001_initial_schema.sql
│   ├── 007_add_ticket_assignment.sql
│   ├── 008_add_status_workflows.sql
│   ├── 009_add_ticket_templates.sql
│   ├── 010_add_bulk_operations.sql
│   └── 011_remove_view_tracking.sql
├── index.php              # Dashboard entry point
├── ticket.php             # Ticket view/create entry point
└── .env                   # Environment configuration

🔐 Security Features

• SQL Injection Prevention: All queries use prepared statements
• XSS Protection: All output is properly escaped with htmlspecialchars()
• Session Security: Secure PHP session handling
• Admin Validation: Server-side admin checks for privileged operations
• Workflow Enforcement: Status transitions validated server-side
• Audit Logging: Complete audit trail of all actions

🎯 Workflow States

Default Workflow

Open → In Progress → Resolved → Closed
  ↓         ↓          ↓
  └─────────┴──────────┘
        (can reopen)

Workflow Configuration

Status transitions are defined in the status_transitions table:

• from_status: Current status
• to_status: Target status
• requires_comment: Whether transition requires a comment
• requires_admin: Whether transition requires admin privileges
• is_active: Whether transition is enabled

📝 Usage Examples

Creating a Ticket

1. Click "New Ticket" button
2. Select template (optional) - auto-fills common fields
3. Fill in title, description, category, type, priority
4. Click "Create Ticket"

Updating Ticket Status

1. Open ticket
2. Click status dropdown (next to priority badge)
3. Select allowed status (workflow-validated)
4. Confirm if comment is required

Assigning Tickets

1. Open ticket or use dashboard bulk actions
2. Select user from "Assigned to" dropdown
3. Changes are auto-saved

Bulk Operations (Admin Only)

1. Check multiple tickets on dashboard
2. Select bulk action (Close, Assign, Change Priority)
3. Complete operation
4. All actions are logged in audit trail

🔮 Roadmap

• ✅ Activity Timeline
• ✅ Ticket Assignment
• ✅ Status Transitions with Workflows
• ✅ Ticket Templates
• ✅ Bulk Actions (Admin Only)
• 🎨 ANSI Art Redesign (Next Priority)
• 🔗 Ticket Dependencies (blocks/blocked by)
• 📊 Custom Dashboard Widgets
• 🔧 Custom Fields per Category

🤝 Contributing

This is an internal tool for LotusGuild infrastructure management. For feature requests or bug reports, contact the infrastructure team.

📄 License

Internal use only - LotusGuild Infrastructure

🙏 Credits

Built with ❤️ for the LotusGuild community Powered by PHP, MariaDB, and lots of coffee ☕