Files

Jared Vititoe 380b0e1adf fix: Sidebar toggle positioning and documentation updates

- Fix collapsible sidebar toggle button positioning (moved outside sidebar)
- Toggle button now stays visible when sidebar is collapsed
- Update cache busting version
- Update Claude.md with new features documentation
- Update README.md with new features documentation
- Remove migrations folder (no longer needed)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-23 10:39:55 -05:00

11 KiB

Raw Blame History

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)

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

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
│   ├── 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_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
├── 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

Session format: $_SESSION['user']['user_id'] (not $_SESSION['user_id'])
API auth: Check $_SESSION['user']['user_id'] exists
Admin check: $_SESSION['user']['is_admin'] ?? false
Config path: config/config.php (not config/db.php)
Comments table: ticket_comments (not comments)
CSRF: Required for POST/DELETE requests via X-CSRF-Token header
Cache busting: Use ?v=YYYYMMDD query params on JS/CSS files
Ticket linking: Use #123456789 in markdown-enabled comments
User groups: Stored in users.groups as comma-separated values

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

11 KiB Raw Blame History