Buggo

A real-time issue tracker for small teams.

View Live · Report Bug · Request Feature

Table of Contents

1. About
2. Features
3. Built With
4. Getting Started
   • Prerequisites
   • Installation
   • Environment Variables
   • Running Locally
5. Testing
6. Project Structure
7. Contributing
8. License
9. Acknowledgments

About

Buggo is a full-stack issue tracker. Teams create projects, invite members, and track tickets from open to closed in one place. Invites, assignments, comments and notifications are delivered live over WebSockets, so everyone sees changes without refreshing.

(back to top)

Features

• Projects: create, rename and delete projects, and invite members by name or email
• Tickets: track status, priority, type and time estimate, and assign tickets to project members
• Comments: discuss tickets with comments that appear live for every member
• Notifications: get notified of project invites and ticket assignments in real time
• My tickets: see your open, closed, weekly and monthly ticket stats across all projects
• Admin dashboard: search users and remove accounts, with changes shown live to every admin
• Cookie-based auth: sessions use HTTP-only cookies sent through the Next.js API proxy

(back to top)

Built With

Client

Server

Testing and CI

(back to top)

Getting Started

Prerequisites

• Node.js (LTS)
• Yarn for the client and npm for the server
• A MongoDB database

Installation

git clone https://github.com/okoyecharles/buggo.git
cd buggo

# Client
cd client
yarn install

# Server
cd ../server
npm install

Environment Variables

Create client/.env:

Variable	Description	Example
API_ORIGIN	Server origin that /api requests proxy to	http://localhost:4000
NEXT_PUBLIC_SERVER_URL	Base path for API requests from the browser	/api
NEXT_PUBLIC_API_ORIGIN	Server origin for the WebSocket connection	http://localhost:4000

Create server/.env:

Variable	Description	Example
MONGO_URI	MongoDB connection string
JWT_SECRET	Secret used to sign auth tokens
PORT	Port the server listens on	4000
ALLOWED_ORIGINS	Comma-separated origins allowed by CORS	http://localhost:3000
NODE_ENV	development or production	development

Running Locally

Start the server and the client in separate terminals:

# Server, on http://localhost:4000
cd server
npm run server

# Client, on http://localhost:3000
cd client
yarn dev

(back to top)

Testing

End-to-end tests are written with Playwright and live in client/tests. They cover projects, tickets, live comments and invites, profile editing, ticket stats and the admin dashboard. Playwright starts the client and server automatically.

The tests sign in with existing accounts. Create a regular user and an admin user in your test database, then add their credentials to client/.env.e2e.local:

PW_SETUP_USER_EMAIL=
PW_SETUP_USER_PASSWORD=
PW_SETUP_ADMIN_EMAIL=
PW_SETUP_ADMIN_PASSWORD=

Run the suite:

cd client
yarn playwright test          # headless
yarn playwright test --ui     # interactive UI mode
yarn playwright show-report   # open the last HTML report

The suite runs on GitHub Actions for every pull request into main and dev, and can be started manually from the Actions tab.

(back to top)

Project Structure

buggo/
├── client/              Next.js app
│   ├── components/      UI components
│   ├── pages/           Routes
│   ├── redux/           Store, actions and reducers
│   └── tests/           Playwright fixtures and specs
├── server/              Express API and Socket.IO server
│   ├── controllers/
│   ├── models/          Mongoose schemas (see server/README.md)
│   └── routes/
└── .github/workflows/   CI

(back to top)

Contributing

Contributions are welcome. To propose a change:

1. Fork the repository
2. Create a branch from dev (git checkout -b feat/my-feature)
3. Commit using Conventional Commits (git commit -m "feat: add my feature")
4. Push the branch (git push origin feat/my-feature)
5. Open a pull request into dev

Pull requests must pass the Playwright suite before they can be merged. For larger changes, please open an issue first to discuss the idea.

(back to top)

License

Distributed under the MIT License. See LICENSE for details.

(back to top)

Acknowledgments

• Discord for the UI design inspiration

(back to top)