CtrlX_Error is a full-stack bug tracking application built with React, Node.js, Express, and MongoDB. It provides role-based workflows for administrators, testers, and developers to report, view, assign, update, and track software bugs.
- Project Overview
- Key Features
- Tech Stack
- Repository Structure
- System Architecture
- Frontend Architecture
- Backend Architecture
- Request Lifecycle
- Authentication & Authorization
- Database
- API Overview
- Installation
- Environment Variables
- Configuration
- Error Handling
- Security
- Screenshots
- Future Improvements
- Contributing
- License
- Authors
CtrlX_Error is designed to support software issue management through separate workflows for testers, developers, and administrators.
The application allows testers to report bugs, developers to review assigned bugs and update progress, and administrators to monitor bug activity, manage users, manage bugs, and export reports.
The motivation behind the project is to provide a structured system for tracking bugs across a development workflow, including assignment, status tracking, checklist progress, dashboards, reports, and team communication.
Intended users:
- Administrators who manage users, bugs, dashboards, and exports.
- Testers who report and review bugs they created.
- Developers who work on assigned bugs and update status/checklist progress.
- User registration.
- User login.
- JWT-based authentication.
- Password hashing with bcrypt.
- Authenticated user profile retrieval.
- Authenticated profile update.
- Role selection during signup.
- Admin registration protected by an invite token.
- Admin dashboard and management views.
- Tester dashboard and bug reporting views.
- Developer dashboard and assigned bug views.
- Frontend route protection by role.
- Backend route protection by role.
- Tester-created bug reports.
- Bug listing with role-based visibility.
- Bug detail views.
- Bug update support.
- Admin bug deletion.
- Developer assigned bug list.
- Developer checklist updates.
- Developer bug status updates.
- Bug status summary counts.
- Bug dashboard statistics by role.
- Title.
- Description.
- Priority:
Low,Medium,High. - Severity:
Minor,Major,Critical. - Status:
Open,In Progress,Closed. - Due date.
- Module.
- Created by user.
- Assigned developers.
- Attachments as stored links/paths.
- Checklist items.
- Update history field in the schema.
- Admin dashboard statistics.
- Tester dashboard statistics.
- Developer dashboard statistics.
- Bug status distribution charts.
- Bug priority/severity chart components.
- Recent bug tables.
- Excel export for bug reports.
- Excel export for user/bug summary reports.
- Create chats.
- List chats for the current user.
- View chat details.
- Update chat settings by chat admin.
- Delete chats by chat admin.
- Send messages.
- Paginated message retrieval.
- Message read tracking.
- Chat participants and chat admins.
- Chat attachment upload route.
- Optional AI assistant response support through OpenRouter.
- Landing page.
- Login and signup pages.
- Role-specific dashboards.
- Bug cards and bug tables.
- Reusable modals.
- Reusable form inputs.
- Charts built with Recharts.
- Toast notifications.
- Responsive dashboard navigation.
| Area | Technologies |
|---|---|
| Frontend | React 19, React DOM, React Router DOM, Tailwind CSS |
| Backend | Node.js, Express 5 |
| Database | MongoDB, Mongoose |
| Authentication | JWT, bcryptjs |
| APIs | REST APIs with Express routes and Axios clients |
| State Management | React Context API for user and chat state |
| Build Tools | Vite, ESLint, Nodemon |
| Other Libraries | Recharts, Moment, date-fns, React Icons, React Hot Toast, Multer, ExcelJS, dotenv, cors, Axios, Vercel Speed Insights |
CtrlX_Error/
├── README.md
├── backend/
│ ├── config/
│ │ └── db.js
│ ├── controllers/
│ │ ├── authController.js
│ │ ├── bugController.js
│ │ ├── chatController.js
│ │ ├── reportController.js
│ │ └── userController.js
│ ├── middlewares/
│ │ ├── auth.js
│ │ ├── authmiddleware.js
│ │ └── uploadMiddleware.js
│ ├── models/
│ │ ├── Bug.js
│ │ ├── Chat.js
│ │ ├── Message.js
│ │ └── User.js
│ ├── routes/
│ │ ├── authRoutes.js
│ │ ├── bugRoutes.js
│ │ ├── chatRoutes.js
│ │ ├── reportRoutes.js
│ │ └── userRoutes.js
│ ├── services/
│ │ └── aiService.js
│ ├── uploads/
│ ├── package.json
│ └── server.js
├── docs/
└── frontend/
├── public/
├── src/
│ ├── assets/
│ ├── components/
│ │ ├── Cards/
│ │ ├── Charts/
│ │ ├── Inputs/
│ │ ├── chat/
│ │ └── layouts/
│ ├── context/
│ ├── hooks/
│ ├── pages/
│ │ ├── Admin/
│ │ ├── Auth/
│ │ ├── Developer/
│ │ └── Tester/
│ ├── routes/
│ ├── utils/
│ ├── App.jsx
│ ├── index.css
│ └── main.jsx
├── eslint.config.js
├── index.html
├── package.json
├── vercel.json
└── vite.config.js
| Directory | Purpose |
|---|---|
backend/ |
Express API server, database models, controllers, middleware, routes, services, and uploads. |
backend/config/ |
MongoDB connection setup. |
backend/controllers/ |
Request handling and application business logic. |
backend/middlewares/ |
JWT verification, role authorization, and file upload handling. |
backend/models/ |
Mongoose schemas and models. |
backend/routes/ |
API route definitions grouped by module. |
backend/services/ |
External service integration, currently OpenRouter AI response handling. |
backend/uploads/ |
Uploaded files served through the backend. |
frontend/ |
React/Vite single-page application. |
frontend/public/ |
Public static assets. |
frontend/src/assets/ |
Application images. |
frontend/src/components/ |
Reusable UI, chart, input, layout, and chat components. |
frontend/src/context/ |
React Context providers for user and chat state. |
frontend/src/hooks/ |
Custom React hooks. |
frontend/src/pages/ |
Route-level pages grouped by user role. |
frontend/src/routes/ |
Private route guard. |
frontend/src/utils/ |
API paths, Axios configuration, utility functions, upload helper, and menu data. |
docs/ |
Project documents in PDF and spreadsheet formats. |
CtrlX_Error uses a client-server architecture.
The frontend is a React single-page application. It manages authentication state, chat state, protected routes, UI rendering, form submission, and API communication.
The backend is an Express API server. It handles authentication, authorization, bug operations, user operations, report exports, chat operations, file uploads, and AI assistant integration.
MongoDB stores users, bugs, chats, and messages through Mongoose models.
flowchart LR
User[User Browser] --> Frontend[React + Vite Frontend]
Frontend -->|REST API requests with JWT| Backend[Express API Server]
Backend -->|Mongoose queries| MongoDB[(MongoDB)]
Backend -->|Static files| Uploads[Uploads Directory]
Backend -->|Excel generation| Reports[Excel Reports]
Backend -->|Optional chat AI response| OpenRouter[OpenRouter API]
Frontend --> UserContext[User Context]
Frontend --> ChatContext[Chat Context]
Backend --> AuthRoutes[Auth Routes]
Backend --> UserRoutes[User Routes]
Backend --> BugRoutes[Bug Routes]
Backend --> ReportRoutes[Report Routes]
Backend --> ChatRoutes[Chat Routes]
The frontend is organized as a Vite React application.
src/main.jsxmounts the React application.UserProvidersupplies authenticated user state.ChatProvidersupplies chat state.SpeedInsightsis included for Vercel Speed Insights.
Routes are defined in src/App.jsx with react-router-dom.
Public routes:
/landing/login/signup/
Admin routes:
/admin/dashboard/admin/bugs/admin/bugs/:id/admin/users/admin/create-bug/admin/chats
Tester routes:
/tester/dashboard/tester/report-bug/tester/bug/:id/tester/my-bugs/tester/all-bugs/tester/chats
Developer routes:
/developer/dashboard/developer/assigned-bugs/developer/update-bugs/developer/assigned-bugs/:id/developer/chats
Pages are grouped by role under src/pages/:
Auth/: Login and signup.Admin/: Admin dashboard, bug management, user management, admin bug view.Tester/: Tester dashboard, bug creation, bug lists, bug details.Developer/: Developer dashboard, assigned bugs, status updates, assigned bug details.ChatPage.jsx: Shared chat page used by all roles.LandingPage.jsx: Public landing page.
Reusable components are grouped by responsibility:
Cards/: Bug, info, and user cards.Charts/: Recharts-based bar and pie charts.Inputs/: Form inputs, selectors, user assignment, checklist, and attachment inputs.layouts/: Auth layout, dashboard layout, navbar, side menu.chat/: Chat sidebar, messages, input, create modal, settings modal.
The frontend uses React Context:
UserContextmanages authenticated user, token loading, user updates, and logout cleanup.ChatContextmanages chat list, active chat, messages, chat loading states, errors, pagination, creation, updates, deletion, and sending messages.
utils/axiosInstance.jsdefines a shared Axios client usinghttp://localhost:8000.- The Axios request interceptor attaches
Authorization: Bearer <token>fromlocalStorage. - The Axios response interceptor handles
401responses by clearing the token and redirecting to/login. utils/apiPaths.jscentralizes most API paths.ChatContextuses a separate Axios client withimport.meta.env.VITE_API_URL || "http://localhost:8000/api".
The backend is an Express application using ES modules.
Routes are grouped by feature:
authRoutes.js: Registration, login, profile, image upload.userRoutes.js: User listing, developer listing, user lookup.bugRoutes.js: Bug dashboards, bug CRUD, assigned bugs, status updates, checklist updates.reportRoutes.js: Excel report exports.chatRoutes.js: Chat and message operations.
Controllers contain request handling logic:
authController.js: User registration, login, token generation, profile retrieval, profile update.userController.js: User lists, user lookup, developer lookup.bugController.js: Bug lifecycle, dashboards, role-filtered queries, status/checklist updates.reportController.js: Excel workbook generation for bugs and users.chatController.js: Chat CRUD, message CRUD, pagination, read tracking, AI assistant response handling.
authmiddleware.js: Main JWT protection and role-based middleware.auth.js: JWT verification middleware used by chat routes.uploadMiddleware.js: Image upload middleware for profile images.
User: User account and role data.Bug: Bug details, assignment, checklist, attachments, status, and update history.Chat: Chat metadata, participants, admins, AI assistant settings.Message: Chat messages, attachments, mentions, replies, reactions, read tracking.
aiService.js: Formats chat messages and calls OpenRouter for optional AI assistant responses.
- Backend utility logic is contained in route/controller/service files.
- MongoDB connection is handled by
config/db.js. - Static file serving is configured in
server.jsfor/uploads.
flowchart TB
Server[server.js]
Server --> Routes[Routes]
Server --> DB[config/db.js]
Server --> StaticUploads[/uploads static serving]
Routes --> AuthRoutes[authRoutes]
Routes --> UserRoutes[userRoutes]
Routes --> BugRoutes[bugRoutes]
Routes --> ReportRoutes[reportRoutes]
Routes --> ChatRoutes[chatRoutes]
AuthRoutes --> AuthController[authController]
UserRoutes --> UserController[userController]
BugRoutes --> BugController[bugController]
ReportRoutes --> ReportController[reportController]
ChatRoutes --> ChatController[chatController]
Routes --> Middleware[Auth and Role Middleware]
AuthRoutes --> UploadMiddleware[uploadMiddleware]
ChatRoutes --> ChatUpload[Multer chat uploads]
AuthController --> UserModel[User Model]
UserController --> UserModel
UserController --> BugModel[Bug Model]
BugController --> BugModel
ReportController --> BugModel
ReportController --> UserModel
ChatController --> ChatModel[Chat Model]
ChatController --> MessageModel[Message Model]
ChatController --> UserModel
ChatController --> AIService[aiService]
An authenticated API request follows this flow:
- The user interacts with a React page or component.
- The frontend sends an Axios request to the backend.
- The JWT token is attached as a
Bearertoken. - Backend authentication middleware verifies the token.
- Role middleware checks access where configured.
- The route calls the appropriate controller.
- The controller performs validation and business logic.
- Mongoose reads or writes MongoDB documents.
- The backend returns JSON or a file response.
- The frontend updates state and renders the result.
sequenceDiagram
participant U as User
participant F as React Frontend
participant A as Axios Client
participant M as Auth/Role Middleware
participant C as Controller
participant D as MongoDB
U->>F: Interacts with page
F->>A: Sends API request
A->>M: Request with Authorization header
M->>M: Verify JWT and role
M->>C: Forward authorized request
C->>D: Query or update data
D-->>C: Return result
C-->>A: JSON or file response
A-->>F: Response data
F-->>U: Updated UI
Authentication uses JWT.
During login or registration, the backend returns a signed JWT with a 7d expiry. The frontend stores the token in localStorage. Authenticated API requests include the token in the Authorization header.
Passwords are hashed with bcrypt before storage.
Authorization is role-based. Supported roles are:
admintesterdeveloper
Backend authorization middleware includes:
adminOnlytesterOnlydeveloperOnlyauthorizeRoles(...roles)
Frontend authorization is handled through PrivateRoute, which checks the current user and allowed roles before rendering protected routes.
flowchart TD
Start[User submits login or registration] --> Backend[Auth Controller]
Backend --> Validate[Validate user data or credentials]
Validate --> Password[Hash or compare password with bcrypt]
Password --> Token[Generate JWT]
Token --> Client[Return user data and token]
Client --> Store[Store token in localStorage]
Store --> Request[Send protected API request]
Request --> Verify[Verify JWT middleware]
Verify --> RoleCheck[Check route role middleware]
RoleCheck --> Allowed[Run controller]
RoleCheck --> Denied[Return 403 if role is not allowed]
The application uses MongoDB with Mongoose.
| Model | Purpose |
|---|---|
User |
Stores user account details, hashed password, profile image URL, and role. |
Bug |
Stores bug information, assigned developers, creator, checklist, status, attachments, and update history. |
Chat |
Stores chat metadata, participants, admins, last message, and AI assistant configuration. |
Message |
Stores chat messages, sender, attachments, mentions, replies, reactions, deletion state, AI flag, and read tracking. |
- A
Bugreferences aUserthroughcreatedBy. - A
Bugreferences one or more assignedUserdocuments throughassignedTo. - A
Chatreferences users throughparticipantsandadmins. - A
Chatreferences aMessagethroughlastMessage. - A
Messagereferences aChat. - A
Messagereferences aUserthroughsender,mentions,reactions.user, andreadBy.user. - A
Messagecan reference anotherMessagethroughreplyTo.
Data is persisted by controllers using Mongoose models. The backend connects to MongoDB during server startup through connectDB() in backend/config/db.js.
erDiagram
USER ||--o{ BUG : creates
USER ||--o{ BUG : assigned_to
USER ||--o{ CHAT : participates_in
USER ||--o{ CHAT : administers
CHAT ||--o{ MESSAGE : contains
MESSAGE ||--o{ MESSAGE : replies_to
USER ||--o{ MESSAGE : sends
USER ||--o{ MESSAGE : reads
USER {
string name
string email
string password
string profileImageURL
string role
}
BUG {
string title
string description
string priority
string severity
string status
date dueDate
string module
array attachments
array checklist
}
CHAT {
string name
string type
array participants
array admins
object aiAssistant
}
MESSAGE {
string content
array attachments
array mentions
array reactions
boolean isDeleted
boolean isAIMessage
}
| Method | Endpoint | Access | Purpose |
|---|---|---|---|
POST |
/api/auth/register |
Public | Register a user. |
POST |
/api/auth/login |
Public | Authenticate a user and return a token. |
GET |
/api/auth/profile |
Private | Get current user profile. |
PUT |
/api/auth/profile |
Private | Update current user profile. |
POST |
/api/auth/upload-image |
Public in route definition | Upload a profile image. |
| Method | Endpoint | Access | Purpose |
|---|---|---|---|
GET |
/api/users |
Admin | Get all users with bug stats. |
GET |
/api/users/developers |
Admin, Tester | Get all developers. |
GET |
/api/users/:id |
Private | Get user by ID. |
| Method | Endpoint | Access | Purpose |
|---|---|---|---|
GET |
/api/bugs/admin-dashboard |
Admin | Get admin dashboard data. |
GET |
/api/bugs/tester-dashboard |
Tester | Get tester dashboard data. |
GET |
/api/bugs/developer-dashboard |
Developer | Get developer dashboard data. |
GET |
/api/bugs |
Private | Get role-filtered bugs. |
GET |
/api/bugs/all-viewable |
Private | Get bugs visible to current user. |
GET |
/api/bugs/user/:userId |
Private | Get bugs created by a user. |
GET |
/api/bugs/assigned |
Developer | Get bugs assigned to current developer. |
GET |
/api/bugs/:id |
Private | Get bug by ID. |
POST |
/api/bugs |
Tester | Create a bug. |
PUT |
/api/bugs/:id |
Private | Update a bug. |
DELETE |
/api/bugs/:id |
Admin | Delete a bug. |
PUT |
/api/bugs/:id/status |
Developer | Update bug status. |
PUT |
/api/bugs/:id/checklist |
Developer | Update bug checklist. |
| Method | Endpoint | Access | Purpose |
|---|---|---|---|
GET |
/api/reports/export/bugs |
Admin | Export bug report as Excel. |
GET |
/api/reports/export/users |
Admin | Export user report as Excel. |
All chat routes require JWT verification.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/api/chats |
Create a chat. |
GET |
/api/chats |
Get chats for current user. |
GET |
/api/chats/:id |
Get chat by ID. |
PUT |
/api/chats/:id |
Update chat settings. |
DELETE |
/api/chats/:id |
Delete a chat. |
POST |
/api/chats/:id/messages |
Send a message. |
GET |
/api/chats/:id/messages |
Get paginated messages. |
- Node.js
- npm
- MongoDB database connection string
git clone <repository-url>
cd CtrlX_Errorcd backend
npm installcd ../frontend
npm installCreate a .env file in the backend/ directory.
PORT=8000
MONGO_URI=mongodb://localhost:27017/bugtracker
JWT_SECRET=your_jwt_secret
ADMIN_INVITE_TOKEN=your_admin_invite_token
OPENROUTER_API_KEY=your_openrouter_api_key
APPLICATION_URL=http://localhost:5000If using the chat frontend with a non-default backend URL, configure the frontend environment with:
VITE_API_URL=http://localhost:8000/apiDevelopment mode:
cd backend
npm run devProduction start command:
cd backend
npm startDevelopment mode:
cd frontend
npm run devProduction build:
cd frontend
npm run buildPreview production build locally:
cd frontend
npm run preview| Variable | Used By | Required For | Purpose |
|---|---|---|---|
PORT |
Backend | Server startup | Defines the backend server port. |
MONGO_URI |
Backend | Database connection | MongoDB connection string. |
JWT_SECRET |
Backend | Authentication | Secret used to sign and verify JWTs. |
ADMIN_INVITE_TOKEN |
Backend | Admin registration | Token required to register an admin user. |
OPENROUTER_API_KEY |
Backend | Chat AI assistant | API key for OpenRouter integration. |
APPLICATION_URL |
Backend | OpenRouter request headers | Referer value sent to OpenRouter; defaults in code if not set. |
VITE_API_URL |
Frontend | Chat API client | Base API URL used by ChatContext; defaults to http://localhost:8000/api. |
| File | Purpose |
|---|---|
backend/package.json |
Backend scripts and dependencies. |
backend/server.js |
Express app setup, CORS, JSON parsing, route mounting, uploads static serving, server start. |
backend/config/db.js |
MongoDB connection setup. |
frontend/package.json |
Frontend scripts and dependencies. |
frontend/vite.config.js |
Vite, React, Tailwind plugin setup, build output, source map, and dev server settings. |
frontend/eslint.config.js |
ESLint configuration for JavaScript and JSX files. |
frontend/vercel.json |
Vercel SPA rewrite configuration to route all paths to index.html. |
frontend/src/utils/axiosInstance.js |
Shared Axios base URL, timeout, request interceptor, and response interceptor. |
frontend/src/utils/apiPaths.js |
Centralized frontend API path definitions. |
Backend controllers use try/catch blocks and return JSON error responses with HTTP status codes such as 400, 401, 403, 404, and 500.
Examples of handled errors include:
- Duplicate user registration.
- Invalid login credentials.
- Missing or invalid JWT token.
- Unauthorized role access.
- Missing bug fields.
- Invalid priority or severity values.
- Missing bug or chat records.
- Invalid chat IDs.
- Failed report exports.
- Failed AI assistant responses.
Frontend error handling includes:
- Axios response interception for
401responses. - Console logging for API errors.
- Toast notifications in multiple bug, dashboard, report, and chat flows.
- Local form validation in login, signup, and bug creation pages.
- Loading states in dashboards, bug views, and chat views.
No centralized backend error-handling middleware was found in the repository analysis.
Implemented security mechanisms:
- Password hashing with bcrypt before user storage.
- JWT-based authentication.
- Auth middleware for protected backend routes.
- Role-based authorization middleware.
- Frontend private route protection by role.
- Admin registration requires
ADMIN_INVITE_TOKEN. - MongoDB user queries exclude passwords in profile/user-fetch paths.
- Image upload middleware for profile images restricts MIME types to JPEG/JPG/PNG.
Security considerations found during repository analysis:
- CORS is configured with
origin: "*". - Tokens are stored in
localStorage. /api/auth/upload-imageis not protected in the route definition.- Chat attachment uploads do not define file type or size restrictions in the route.
- No rate limiting middleware was found.
- No centralized input sanitization middleware was found.
Placeholder for tester bug reporting and bug list screenshots.
Placeholder for assigned bugs and status update screenshots.
Placeholder for chat interface screenshot.
These improvements are based on the current repository architecture and observed gaps:
- Add automated backend tests.
- Add automated frontend tests.
- Add centralized backend error-handling middleware.
- Add request validation middleware for API boundaries.
- Align frontend status names with backend status values.
- Consolidate duplicate authentication middleware files.
- Protect the profile image upload route.
- Add file size and type validation for chat attachments.
- Make frontend API base URLs consistently configurable.
- Add pagination for bug list endpoints.
- Add backend deployment configuration.
- Add API documentation generated from actual backend routes.
- Add seed or setup instructions for creating initial users.
Contributions are welcome through issues and pull requests.
Recommended workflow:
- Fork the repository.
- Create a feature branch.
- Install backend and frontend dependencies.
- Make changes in the relevant package.
- Run available lint/build commands.
- Verify role-based flows affected by the change.
- Open a pull request with a clear description of the change.
Contribution guidelines:
- Keep backend routes, controllers, models, and middleware separated by responsibility.
- Keep frontend pages role-specific and shared UI in
components/. - Do not document features that are not implemented.
- Keep API paths synchronized between backend routes and
frontend/src/utils/apiPaths.js. - Avoid introducing new status values unless backend schema and frontend views are updated together.
This project is licensed under the GNU General Public License v3.0.
See the LICENSE file for details.
Project contributors preserved from the repository documentation:
| Contributor | Role | Contributions |
|---|---|---|
| Soumya Jain | Frontend Developer | UI design, React pages, Figma design. |
| Smriti Walia | QA & Research | Bug testing, UI layout, documentation. |
| Amulya Jain | Integration & DevOps | Frontend-backend integration, fixes, middleware, versioning. |
| Naman Chanana | Backend & Full-Stack Lead | Auth, email, database design, API testing. |
Additional contributors can be added here as the project evolves.


