# Tinker Tickets - Project Documentation for AI Assistants ## Project Status (January 2026) **Current Phase**: All core features implemented. System is production-ready. **Completed Features**: - Activity Timeline, Ticket Assignment, Status Transitions with Workflows - Ticket Templates, Bulk Actions (Admin Only) - File Attachments, Ticket Dependencies, @Mentions in Comments - Recurring Tickets, Custom Fields, Advanced Search with Saved Filters - Export to CSV/JSON, API Key Management - Ticket Visibility Levels (public/internal/confidential) - Collapsible Sidebar, Kanban Card View, Inline Ticket Preview - Mobile Responsive Design, Ticket Linking in Comments - Admin Pages (Templates, Workflow, Recurring, Custom Fields, User Activity, Audit Log, API Keys) - Comment Edit/Delete (owner or admin can modify their comments) - Markdown Tables Support, Auto-linking URLs in Comments ## 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: nginx with PHP-FPM on production (10.10.10.45) - Authentication: Authelia SSO with LLDAP backend **Production Environment:** - **Primary URL**: https://t.lotusguild.org - **Web Server**: nginx at 10.10.10.45 (`/var/www/html/tinkertickets`) - **Database**: MariaDB at 10.10.10.50 (`ticketing_system` database) - **Authentication**: Authelia provides SSO via headers - **Dev Environment**: `/root/code/tinker_tickets` (not production) ## 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 │ ├── delete_comment.php # POST: Delete comment (owner/admin) │ ├── export_tickets.php # GET: Export tickets to CSV/JSON │ ├── generate_api_key.php # POST: Generate API key (admin) │ ├── 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) │ ├── revoke_api_key.php # POST: Revoke API key (admin) │ ├── ticket_dependencies.php # GET/POST/DELETE: Ticket dependencies │ ├── update_comment.php # POST: Update comment (owner/admin) │ ├── 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 + kanban + sidebar │ │ ├── keyboard-shortcuts.js # Keyboard shortcuts │ │ ├── markdown.js # Markdown rendering + ticket linking │ │ ├── settings.js # User preferences │ │ ├── ticket.js # Ticket + comments + visibility │ │ └── 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 + visibility ├── 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/ │ ├── ApiKeyModel.php # API key generation/validation │ ├── 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 + visibility │ ├── UserModel.php # User management + groups │ ├── UserPreferencesModel.php # User preferences │ └── WorkflowModel.php # Status transition workflows ├── scripts/ │ ├── cleanup_orphan_uploads.php # Clean orphaned uploads │ └── create_dependencies_table.php # Create ticket_dependencies table ├── uploads/ # File attachment storage ├── views/ │ ├── admin/ │ │ ├── ApiKeysView.php # API key management │ │ ├── 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 visibility │ ├── DashboardView.php # Dashboard with kanban + sidebar │ └── TicketView.php # Ticket view with visibility editing ├── .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 | | `/admin/api-keys` | Generate and manage API keys | ## Database Schema **Database**: `ticketing_system` at 10.10.10.50 **User**: `tinkertickets` ### Core Tables - `tickets` - Core ticket data with assignment and visibility - `ticket_comments` - Markdown-supported comments - `ticket_attachments` - File attachment metadata - `ticket_dependencies` - Ticket relationships - `users` - User accounts synced from LLDAP (includes groups) - `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_keys` - API key storage with hashes ### Ticket Visibility Columns - `visibility` - ENUM('public', 'internal', 'confidential') - `visibility_groups` - VARCHAR(500) comma-separated group names ## Dashboard Features - **View Toggle**: Switch between Table view and Kanban card view - **Collapsible Sidebar**: Click arrow to collapse/expand filter sidebar - **Stats Widgets**: Clickable cards for quick filtering - **Inline Ticket Preview**: Hover over ticket IDs for 300ms to see preview popup - **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 operations - **Export**: Export selected tickets to CSV or JSON ## Ticket Visibility Levels - **Public**: All authenticated users can view - **Internal**: Only users in specified groups can view - **Confidential**: Only creator, assignee, and admins can view ## Important Notes for AI Assistants 1. **Session format**: `$_SESSION['user']['user_id']` (not `$_SESSION['user_id']`) 2. **API auth**: Check `$_SESSION['user']['user_id']` exists 3. **Admin check**: `$_SESSION['user']['is_admin'] ?? false` 4. **Config path**: `config/config.php` (not `config/db.php`) 5. **Comments table**: `ticket_comments` (not `comments`) 6. **CSRF**: Required for POST/DELETE requests via `X-CSRF-Token` header 7. **Cache busting**: Use `?v=YYYYMMDD` query params on JS/CSS files 8. **Ticket linking**: Use `#123456789` in markdown-enabled comments 9. **User groups**: Stored in `users.groups` as comma-separated values 10. **API routing**: All API endpoints must be added to `index.php` router 11. **Session in APIs**: RateLimitMiddleware starts session; don't call session_start() again 12. **Database collation**: Use `utf8mb4_general_ci` (not unicode_ci) for new tables 13. **Ticket ID extraction**: Use `getTicketIdFromUrl()` helper in JS files ## File Reference Quick Guide | File | Purpose | |------|---------| | `index.php` | Main router for all routes | | `api/update_ticket.php` | Ticket updates with workflow + visibility | | `models/TicketModel.php` | Ticket CRUD, visibility filtering | | `models/ApiKeyModel.php` | API key generation and validation | | `assets/js/dashboard.js` | Dashboard UI, kanban, sidebar, bulk actions | | `assets/js/ticket.js` | Ticket UI, visibility editing | | `assets/js/markdown.js` | Markdown parsing + ticket linking | | `assets/css/dashboard.css` | Terminal styling, kanban, sidebar | ## Repository - **Gitea**: https://code.lotusguild.org/LotusGuild/tinker_tickets - **Production**: http://t.lotusguild.org