Bughound: Comprehensive Bug Tracking System

Bughound is a sophisticated, full-stack web application designed for efficient bug recording, tracking, and management. Built with a modern technology stack, it offers a seamless user experience for developers, QA teams, and project managers to collaborate on resolving software issues. This project demonstrates a robust architecture, a feature-rich frontend, and a secure, scalable backend.

Core Features

Bughound provides a comprehensive suite of tools for effective bug lifecycle management:

• Intuitive Bug Reporting: Easily create detailed bug reports with fields for program, version, severity, problem summary, description, reproducibility, and suggested fixes.
• Advanced Bug Tracking & Updates: Update existing bug reports with comments, status changes, priority adjustments, resolution details, and test results.
• Powerful Search Capabilities: Quickly find specific bug reports using a multi-field search form, including program, report type, severity, status, and more.
• User Roles & Permissions: Supports different user levels (e.g., Level 1, 2, 3) to manage access to features like database maintenance.
• Program & Area Management: Organize bugs by programs, releases, versions, and functional areas. Includes capabilities to add, edit, and delete programs and their associated areas.
• Employee Management: Manage user accounts with functionalities for adding, editing, and deleting employees, including password management.
• Database Maintenance: Provides administrative tools for maintaining core application data like programs, areas, and employees (typically for privileged users).
• Data Export: Export critical data such as Programs and Employees in user-friendly formats like ASCII (CSV-like) and XML for external analysis or backup.
• File Attachments: Attach relevant files (images, logs, documents) to bug reports to provide more context.
• User-Friendly Interface: A clean, responsive interface built with Tailwind CSS and DaisyUI, featuring theme customization and real-time notifications.

Application Showcase

Click to view screenshots of Bughound in action!

Login & Dashboard

Login Page Users are greeted with a clean and simple login page to access the bug tracking system.

Main Dashboard The main dashboard provides quick access to core functionalities like creating new bug reports, updating existing ones, and accessing database maintenance tools.

---

Bug Lifecycle Management

Submit a Bug Report A comprehensive form allows users to submit detailed bug reports, including program details, severity, description, and file attachments.

Search for Bugs The powerful search functionality enables users to filter and find specific bug reports based on various criteria like program, report type, and status.

Search Results Search results are displayed in a clear, tabular format, allowing users to quickly navigate to the bug report they need.

Edit a Bug Report Users can easily edit and update existing bug reports, modifying details, changing status, or adding comments and attachments.

---

Administrative Tools

Database Maintenance Menu The database maintenance section (for privileged users) provides tools for managing programs, employees, and exporting data.

Program & Area Management Administrators can manage programs and their associated functional areas, with options to view, add, edit, and delete records.

Add, Edit, and Delete Programs The UI supports seamless CRUD operations with intuitive modals for adding, inline editing for updating, and a dedicated delete mode with confirmation to prevent accidental data loss.

Employee Management The employee management page allows for viewing user accounts and managing user-level permissions and credentials.

Data Export The data export feature allows users to download system data, such as program lists, in formats like XML for backup or external analysis.

Tech Stack

Bughound leverages a modern and powerful technology stack:

• Frontend:
  • Framework/Library: React 19, TypeScript
  • Build Tool: Vite
  • Routing: TanStack Router
  • State Management/Data Fetching: TanStack Query
  • Tables: TanStack Table
  • Styling: Tailwind CSS, DaisyUI
  • Schema Validation: Zod
• Backend:
  • Runtime: Bun
  • Framework: Hono (a fast, lightweight, web framework)
  • ORM: Drizzle ORM
  • Language: TypeScript
  • Schema Validation: Zod
• Database:
  • PostgreSQL
• File Storage:
  • Supabase Storage (for bug report attachments)
• Testing:
  • Bun Test (for backend service testing)
• Containerization:
  • Docker

Bughound System Architecture Diagram

Architecture Overview

Bughound is designed with a classic client-server architecture:

• Frontend: A Single Page Application (SPA) built with React and Vite. It communicates with the backend via a RESTful API. TanStack Router handles client-side navigation, while TanStack Query manages server state, caching, and background data synchronization. Interactive data tables are implemented using TanStack Table for a rich user experience.
• Backend: A Hono-based API server running on Bun. It exposes RESTful endpoints for all CRUD operations and business logic. Drizzle ORM is used for type-safe database interactions with the PostgreSQL database. Authentication is managed through secure session tokens. File uploads are handled by the backend and stored securely using Supabase Storage.
• Database: PostgreSQL serves as the relational database, with its schema managed and versioned using Drizzle ORM migrations.
• CI/CD: A GitHub Actions workflow is configured for continuous integration, running tests and type checks on push and pull requests to ensure code quality.

Entity Relationship Diagram

The following diagram illustrates the relationships between the core entities in the Bughound system:

---
config:
 theme: natural
---
erDiagram
    EMPLOYEES {
        int EmployeeID PK
        string Name
        string UserName
        varchar(255) Password
        int UserLevel
    }
    PROGRAMS {
        int ProgramID PK
        string ProgramName
        int Release
        int Version
    }
    AREAS {
        int AreaID PK
        int ProgramID FK
        string AreaDescription
    }
    BUGREPORTS {
        int BugID PK
        int ProgramID FK
        string ReportType
        string Severity
        string Summary
        string Reproducible
        string Description
        string SuggestedFix
        int ReportedBy FK
        date ReportDate
        int FunctionalArea FK
        int AssignedTo FK
        string Comments
        boolean Status
        string Priority
        string Resolution
        int ResolutionVersion
        int ResolvedBy FK
        date ResolveDate
        int TestedBy FK
        date TesteDate
        boolean TreatAsDeferred
        boolean hasAttachments
        int AttachmentID FK
    }
    ATTACHMENTS {
        int AttachmentID PK
        string FileName
        string FileType
        blob FileContent
    }
    PROGRAMS ||--o{ AREAS : contains
    PROGRAMS ||--o{ BUGREPORTS : has
    AREAS |o..o{ BUGREPORTS : "is associated with"
    EMPLOYEES ||--o{ BUGREPORTS : reports
    EMPLOYEES |o..o{ BUGREPORTS : "is assigned to"
    EMPLOYEES |o..o{ BUGREPORTS : resolves
    EMPLOYEES |o..o{ BUGREPORTS : tests
    BUGREPORTS ||--o| ATTACHMENTS : contains

Loading

Project Setup & Running

This project was initialized using bun init. Bun is a fast, all-in-one JavaScript runtime.

Prerequisites

• Bun: (Latest version recommended) - Installation guide: https://bun.sh/docs/installation
• Node.js & npm/yarn: Required by some node-gyp dependencies if you need to rebuild native modules (though Bun aims to handle most cases).
• Docker: (Optional, for running in a container)

Environment Variables

Before running the application, you'll need to set up your environment variables. Copy the example files to .env (for the backend) and frontend/.env (for the frontend) and populate them with your specific configurations:

• cp .env.example .env
• cp frontend/.env.example frontend/.env

Key variables include:

• DATABASE_URL: Connection string for your PostgreSQL database.
• VITE_API_BASE_URL: The base URL for the backend API (e.g., http://localhost:3000).
• SUPABASE_URL & SUPABASE_SERVICE_KEY: Credentials for Supabase if using file attachments.

Installation

Install all project dependencies (both backend and frontend) using Bun:

# Install backend dependencies
bun install

# Navigate to the frontend directory and install its dependencies
cd frontend
bun install

Database Migrations

Apply Drizzle ORM migrations to set up your database schema:

bun run drizzle

This command first generates migration files based on schema changes and then applies them to the database specified in your DATABASE_URL.

Running the Application

• Development Mode (with hot-reloading for the backend):

  bun run dev

  The frontend should be run separately in its own terminal:

  cd frontend
  bun run dev

• Production Mode (backend only, frontend needs to be built first): To build the frontend for production:

  cd frontend
  bun run build

  Then, to start the backend server which will serve the built frontend:

  bun run dev

The application will typically be available at http://localhost:5173 (frontend Vite server) or the port specified for the backend (default 3000, serving the built frontend).

Running Tests

To run the backend tests (ensure .env.test is configured):

bun test

Key Skills & Technologies Applied

The development of Bughound provided extensive hands-on experience with a range of modern technologies and software engineering practices. Key areas of application and learning include:

• Full-Stack System Design & Integration: Architecting and implementing a cohesive full-stack application, ensuring seamless communication and data flow between a dynamic React frontend and a high-performance Bun/Hono backend.
• End-to-End Type Safety Implementation: Mastering the use of TypeScript throughout the client and server to build a robust, maintainable codebase. This involved leveraging Drizzle ORM for type-safe database queries and Zod for rigorous data validation at API boundaries and in forms.
• Modern JavaScript Ecosystem Proficiency: Gaining in-depth experience with the Bun runtime for its efficient package management, testing capabilities, and backend server performance. Vite was utilized for its rapid frontend development server and optimized build processes.
• Advanced Client-Side State & Data Management: Implementing sophisticated client-side data handling with TanStack Query for managing server state, caching, and optimistic updates. TanStack Table was employed to build feature-rich, interactive data tables for programs, employees, and bug reports.
• Secure Authentication & Session Management: Designing and implementing a secure session-based authentication flow, including secure cookie handling and backend validation to protect user data and application access.
• Relational Database Design & ORM Mastery: Developing a well-structured PostgreSQL database schema (detailed in the ER Diagram) and utilizing Drizzle ORM for type-safe CRUD operations, complex queries, and managing schema migrations effectively.
• Cloud Storage & File Management: Integrating with Supabase Storage for secure and scalable handling of file attachments for bug reports, including upload, retrieval, and deletion logic.
• Component-Driven Frontend Development: Building a modular and reusable frontend using React's component-based architecture, adhering to best practices for state management, props drilling, and UI composition.
• Effective Use of Custom React Hooks: Creating and applying custom React hooks to encapsulate complex UI logic, stateful interactions (like inline editing, modal management, and multi-selection in tables), and improve code organization.
• Backend API Development & Testing: Constructing RESTful APIs with Hono, ensuring service reliability and correctness through a suite of unit and integration tests written with Bun Test.
• Containerization for Reproducible Deployments: Developing a multi-stage Dockerfile to create optimized and portable Docker images, preparing the application for consistent deployments across different environments.
• Continuous Integration (CI) Implementation: Setting up and configuring a GitHub Actions workflow to automate builds, run type checks, and execute tests on every code change, ensuring a high standard of code quality.

---