# 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`) ```ini 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