tinker_tickets/Claude.md

Tinker Tickets - Project Documentation for AI Assistants

Project Status (January 2026)

Current Phase: All core features implemented. ANSI Art terminal redesign complete. System is production-ready.

Completed Features:

• ✅ Activity Timeline (Feature 1)
• ✅ Ticket Assignment (Feature 2)
• ✅ Status Transitions with Workflows (Feature 3)
• ✅ Ticket Templates (Feature 4)
• ✅ Bulk Actions - Admin Only (Feature 5)
• ✅ ANSI Art Terminal Redesign
• ✅ File Attachments
• ✅ Ticket Dependencies
• ✅ @Mentions in Comments
• ✅ Recurring Tickets
• ✅ Custom Fields
• ✅ Advanced Search with Saved Filters
• ✅ Export to CSV/JSON
• ✅ Admin Pages (Templates, Workflow, Recurring, Custom Fields, User Activity, Audit Log)

Recent Updates (January 2026):

• Added admin dropdown navigation in dashboard header
• Fixed template/recurring ticket modals (larger size, type/assignee fields)
• Made dashboard stat cards clickable for quick filtering
• Fixed table overflow on dashboard
• Improved error handling for ticket dependencies API

Project Overview

Tinker Tickets is a feature-rich, self-hosted ticket management system built for managing data center infrastructure issues. It features SSO integration with Authelia/LLDAP, workflow management, Discord notifications, and a retro terminal-style web interface.

Tech Stack:

• Backend: PHP 7.4+ with MySQLi
• Frontend: Vanilla JavaScript, CSS3
• Database: MariaDB on separate LXC (10.10.10.50)
• Web Server: Apache on production (10.10.10.45)
• Authentication: Authelia SSO with LLDAP backend
• External Libraries: marked.js (Markdown rendering)

Production Environment:

• Primary URL: http://t.lotusguild.org
• Web Server: Apache at 10.10.10.45 (/root/code/tinker_tickets)
• Database: MariaDB at 10.10.10.50 (ticketing_system database)
• Authentication: Authelia provides SSO via headers

Architecture

MVC Pattern

Controllers → Models → Database
     ↓
   Views

Project Structure

/tinker_tickets/
├── api/                                  # API endpoints
│   ├── add_comment.php                   # POST: Add comment
│   ├── assign_ticket.php                 # POST: Assign ticket to user
│   ├── bulk_operation.php                # POST: Bulk operations - admin only
│   ├── check_duplicates.php              # GET: Check for duplicate tickets
│   ├── delete_attachment.php             # POST/DELETE: Delete attachment
│   ├── export_tickets.php                # GET: Export tickets to CSV/JSON
│   ├── get_template.php                  # GET: Fetch ticket template
│   ├── get_users.php                     # GET: Get user list
│   ├── manage_recurring.php              # CRUD: Recurring tickets (admin)
│   ├── manage_templates.php              # CRUD: Templates (admin)
│   ├── manage_workflows.php              # CRUD: Workflow rules (admin)
│   ├── ticket_dependencies.php           # GET/POST/DELETE: Ticket dependencies
│   ├── update_ticket.php                 # POST: Update ticket (workflow validation)
│   └── upload_attachment.php             # GET/POST: List or upload attachments
├── assets/
│   ├── css/
│   │   ├── dashboard.css                 # Dashboard + terminal styling
│   │   └── ticket.css                    # Ticket view styling
│   ├── js/
│   │   ├── advanced-search.js            # Advanced search modal
│   │   ├── ascii-banner.js               # ASCII art banner
│   │   ├── dashboard.js                  # Dashboard + bulk actions + templates
│   │   ├── keyboard-shortcuts.js         # Keyboard shortcuts
│   │   ├── markdown.js                   # Markdown rendering
│   │   ├── settings.js                   # User preferences
│   │   ├── ticket.js                     # Ticket + comments + assignment
│   │   └── toast.js                      # Toast notifications
│   └── images/
│       └── favicon.png
├── config/
│   └── config.php                        # Config + .env loading
├── controllers/
│   ├── DashboardController.php           # Dashboard with stats + filters
│   └── TicketController.php              # Ticket CRUD + timeline + templates
├── cron/
│   └── create_recurring_tickets.php      # Process recurring ticket schedules
├── helpers/
│   └── ResponseHelper.php                # Standardized JSON responses
├── middleware/
│   ├── AuthMiddleware.php                # Authelia SSO integration
│   ├── CsrfMiddleware.php                # CSRF protection
│   ├── RateLimitMiddleware.php           # API rate limiting
│   └── SecurityHeadersMiddleware.php     # Security headers
├── models/
│   ├── AuditLogModel.php                 # Audit logging + timeline
│   ├── BulkOperationsModel.php           # Bulk operations tracking
│   ├── CommentModel.php                  # Comment data access
│   ├── CustomFieldModel.php              # Custom field definitions/values
│   ├── DependencyModel.php               # Ticket dependencies
│   ├── RecurringTicketModel.php          # Recurring ticket schedules
│   ├── StatsModel.php                    # Dashboard statistics
│   ├── TemplateModel.php                 # Ticket templates
│   ├── TicketModel.php                   # Ticket CRUD + assignment
│   ├── UserModel.php                     # User management
│   ├── UserPreferencesModel.php          # User preferences
│   └── WorkflowModel.php                 # Status transition workflows
├── scripts/
│   └── cleanup_orphan_uploads.php        # Clean orphaned uploads
├── uploads/                              # File attachment storage
├── views/
│   ├── admin/
│   │   ├── AuditLogView.php              # Audit log browser
│   │   ├── CustomFieldsView.php          # Custom field management
│   │   ├── RecurringTicketsView.php      # Recurring ticket management
│   │   ├── TemplatesView.php             # Template management
│   │   ├── UserActivityView.php          # User activity report
│   │   └── WorkflowDesignerView.php      # Workflow transition designer
│   ├── CreateTicketView.php              # Ticket creation with templates
│   ├── DashboardView.php                 # Dashboard with stats + bulk actions
│   └── TicketView.php                    # Ticket view with timeline + assignment
├── .env                                  # Environment variables (GITIGNORED)
├── Claude.md                             # This file
├── README.md                             # User documentation
└── index.php                             # Main router

Admin Pages

All admin pages are accessible via the Admin dropdown in the dashboard header (for admin users only).

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

Database Schema

Database: ticketing_system at 10.10.10.50 User: tinkertickets Connection: All APIs create their own connections via config.php

Core Tables

• tickets - Core ticket data with assignment
• ticket_comments - Markdown-supported comments
• ticket_attachments - File attachment metadata
• ticket_dependencies - Ticket relationships (blocks/blocked_by/relates_to/duplicates)
• 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
• bulk_operations - Bulk operation tracking

API Endpoints

Authentication

All API endpoints check: $_SESSION['user']['user_id'] for authentication. Admin-only endpoints check: $_SESSION['user']['is_admin'].

Core 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 (admin)
/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

Dashboard Features

• Stats Widgets: Clickable cards for quick filtering (Open, Critical, Unassigned, Created Today, Closed Today)
• Admin Dropdown: Quick access to all admin pages
• Sortable Columns: Click headers to sort
• Advanced Search: Date ranges, priority ranges, user filters
• Saved Filters: Save and load custom filter combinations
• Bulk Actions (admin): Select multiple tickets for bulk close/assign/priority/status
• Export: Export selected tickets to CSV or JSON
• Left Sidebar: Status, Category, Type filters

Terminal UI Design

The application uses a retro terminal aesthetic with:

• Box-drawing characters: ╔═╗║╚═╝┌─┐│└─┘
• Monospace fonts: Courier New, Consolas, Monaco
• Terminal colors: Green (#00ff41), Amber (#ffb000), Cyan (#00ffff)
• CRT effects: Scanlines, subtle flicker
• Glow effects: Text shadows for terminal phosphor look
• ASCII art: Boot sequence, empty states, headers

Configuration

Environment Variables (.env)

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

CRITICAL: .env is gitignored! Never commit this file.

Deployment

Git Auto-Deploy

Repository: https://code.lotusguild.org/LotusGuild/tinker_tickets

Flow:

1. Push to main branch
2. Auto-deploys to /root/code/tinker_tickets on 10.10.10.45
3. .env is preserved

Development Guidelines

Code Style

• PHP: Tabs for indentation, prepared statements, htmlspecialchars() for output
• JavaScript: Vanilla JS, fetch() for AJAX, clear function names
• CSS: CSS variables for theming, mobile-responsive
• Security: No SQL injection, XSS prevention, session validation

Error Handling

• APIs return JSON with {success: bool, error: string}
• Debug logging to /tmp/api_debug.log
• User-friendly error messages

Adding New Features

1. Model: Add methods to relevant Model class
2. API: Create API endpoint in api/ (with auth check)
3. Controller: Update controller to load data
4. View: Add UI elements
5. JavaScript: Add interactivity
6. CSS: Style with terminal aesthetic
7. Test: Test thoroughly before pushing

Important Notes for AI Assistants

1. All features are complete and deployed
2. Terminal UI redesign is complete - maintain the aesthetic
3. Database at 10.10.10.50, can't access directly from dev machine
4. Auto-deploy is active, test carefully before pushing
5. Session format: $_SESSION['user']['user_id'] (not $_SESSION['user_id'])
6. API auth: Check $_SESSION['user']['user_id'] exists
7. Admin check: $_SESSION['user']['is_admin'] ?? false
8. Config path: config/config.php (not config/db.php)
9. Comments table: ticket_comments (not comments)
10. CSRF: Required for POST/DELETE requests via X-CSRF-Token header

File Reference Quick Guide

File	Purpose
index.php	Main router for all routes
api/update_ticket.php	Ticket updates with workflow validation
api/ticket_dependencies.php	Manage ticket dependencies
models/TicketModel.php	Ticket CRUD, assignment, filtering
models/WorkflowModel.php	Status transition validation
models/DependencyModel.php	Ticket dependency management
controllers/DashboardController.php	Dashboard logic, stats, filters
assets/js/dashboard.js	Dashboard UI, bulk actions, templates
assets/js/ticket.js	Ticket UI, comments, assignment
assets/css/dashboard.css	Terminal styling, layout, components

Repository & Contact

• Gitea: https://code.lotusguild.org/LotusGuild/tinker_tickets
• Production: http://t.lotusguild.org
• Infrastructure: LotusGuild data center management