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