Traq

Traq is a self‑hosted PHP application designed for project and issue tracking across multiple projects and milestones. From a developer standpoint, it functions as a modular web service that exposes RESTful endpoints for CRUD operations on projects, tickets, users, and custom fields. The core logic is written in PHP 8.3+, leveraging Composer for dependency management and a modern JavaScript build pipeline (PNPM + Vite) to deliver a reactive single‑page UI. The application expects a relational database (MariaDB or MySQL) for persistence, and it relies on Apache’s mod_rewrite to route all requests through a front controller (index.php). Traq’s data model is normalized, with tables for projects, milestones, tickets, users, groups, and custom field definitions, allowing fine‑grained permission checks via a role‑based access control system.

Architecture

• Backend: PHP 8.3+, organized in an MVC‑like structure with a lightweight routing layer. Core services are split into domain entities (Project, Ticket, User) and repository classes that abstract database access. Dependency injection is handled manually via a simple service container, keeping the framework footprint minimal.
• Frontend: Built with modern JavaScript (ES2020) and bundled using Vite. The UI communicates with the backend through JSON‑based REST APIs, following conventional HTTP verbs and status codes. State management is handled client‑side with a lightweight store; no heavy frameworks like React or Vue are required.
• Database: MariaDB/MySQL 10+. The schema includes foreign key constraints, indexes on frequently queried columns (e.g., project_id, status), and triggers for audit logging. The application ships with SQL migration scripts that can be applied via Composer’s vendor/bin/phinx or a custom CLI.
• Web Server: Apache with mod_rewrite. The .htaccess file rewrites all non‑static requests to index.php, enabling clean URLs. Traq can also run under Nginx using a similar rewrite rule set.

Core Capabilities

• Project & Milestone Management: Create, update, delete projects and milestones; associate tickets to specific sprints.
• Issue Tracking: Full CRUD for tickets, including status transitions, priority levels, and assignee management.
• Custom Fields: Define arbitrary fields per project; stored in a key‑value table linked to tickets, enabling extensible data capture.
• Permission System: Role‑based access control with per‑project and per‑group scopes. Permissions are stored in a JSON column, parsed at runtime.
• API & Webhooks: Exposes a REST API with token‑based authentication. Supports webhooks for ticket events (created, updated, closed) that can trigger external CI/CD pipelines or Slack notifications.
• Search & Filtering: Full‑text search on ticket titles and descriptions; filter by status, assignee, or custom field values.

Deployment & Infrastructure

Traq is designed for lightweight hosting environments. A single PHP worker can serve the application, and it scales horizontally by adding more workers behind a load balancer. Docker support is available via the provided Dockerfile and optional docker-compose.yml, which configure PHP-FPM, Apache, and MariaDB. For larger deployments, database replication or clustering can be set up using standard MySQL/MariaDB tooling. Traq’s statelessness (aside from the database) makes it ideal for container orchestration platforms like Kubernetes, where pods can be scaled based on CPU or request load.

Integration & Extensibility

• Plugin Architecture: Traq includes a plugin system that allows developers to hook into lifecycle events (e.g., onTicketCreate). Plugins are PHP classes placed in a designated directory and discovered via Composer autoloading.
• Extensible APIs: The REST API is versioned (/api/v1/*) and documented with OpenAPI annotations. Developers can consume these endpoints or extend them by adding custom controllers.
• Webhooks: Configurable webhook URLs per project, with payload templates that include ticket data and custom fields.
• CLI Tools: A set of Artisan‑like commands (traq migrate, traq seed) facilitate database migrations, seeding, and cache clearing.

Developer Experience

Traq ships with comprehensive inline documentation in PHPDoc format and a docs/ directory that explains installation, configuration, and API usage. The community is active on GitHub, with contributors providing regular updates and security patches. Licensing under GPLv3 ensures that any derived work must remain open source, which is attractive for organizations that prefer transparent codebases. The build process—Composer for PHP dependencies and PNPM for JavaScript assets—is straightforward, allowing developers familiar with either ecosystem to get started quickly.

Use Cases

• Open‑Source Project Management: Teams that require a self‑hosted, open‑source alternative to commercial tools like Jira or GitLab Issues.
• Enterprise Agile Environments: Organizations that need granular permission controls and custom field support for compliance.
• DevOps Pipelines: Integration with CI/CD tools via webhooks to automatically close tickets upon successful deployments.
• Educational Platforms: Instructors can use Traq to track student projects, assign milestones, and enforce deadlines.

Advantages

• Performance: Lightweight PHP codebase with minimal dependencies results in low memory usage and fast response times.
• Flexibility: Custom fields, plugin hooks, and a fully documented API allow developers to tailor the system to niche workflows.
• Licensing: GPLv3 guarantees that any improvements remain open source, fostering community contributions.
• Scalability