# AGENTS.md

## Project Overview

This project is a **Service Desk Application** built with:

- **Frontend:** React + Vite + Tailwind CSS
- **Backend:** Node.js + Express
- **Database:** MySQL

The application is intended to support a help desk / ticketing workflow for organizations that need to manage service requests, incidents, and internal support operations.

Primary user roles:

- **Admin** — manages users, roles, categories, priorities, and system-level configuration
- **Agent** — handles assigned tickets, updates status, adds comments/notes, resolves issues
- **Requester** — creates tickets, views ticket progress, and replies to requests

---

## Product Goals

The core goal is to deliver an MVP that allows:

1. Secure authentication and role-based authorization
2. Ticket creation, tracking, assignment, and resolution
3. Conversation/history on each ticket
4. Administrative user management
5. Dashboard metrics for ticket workload and status visibility

---

## Technical Direction

### Frontend

Use:

- React
- Vite
- Tailwind CSS
- React Router
- Axios or Fetch wrapper for API calls
- React Hook Form for forms
- Zod or Yup for validation
- TanStack Query if async state management is needed

Suggested frontend structure:

```text
frontend/
  src/
    api/
    assets/
    components/
    features/
      auth/
      dashboard/
      tickets/
      users/
    hooks/
    layouts/
    pages/
    routes/
    utils/
    App.jsx
    main.jsx
```

### Backend

Use:

- Node.js
- Express.js
- MySQL
- JWT for authentication
- bcrypt for password hashing
- express-validator or Zod for request validation

Suggested backend structure:

```text
backend/
  src/
    config/
    controllers/
    middleware/
    routes/
    services/
    models/
    validators/
    utils/
    app.js
    server.js
```

---

## Database Direction

Core tables expected in MVP:

- `users`
- `roles`
- `tickets`
- `ticket_comments`
- `ticket_history`
- `categories`
- `priorities`

Optional later tables:

- `attachments`
- `notifications`
- `departments`
- `sla_policies`

### Ticket Lifecycle

Use this initial status workflow:

- `Open`
- `In Progress`
- `Pending`
- `Resolved`
- `Closed`

---

## Coding Expectations for Agents

When working in this repository:

1. Keep changes focused and minimal.
2. Prefer scalable but simple solutions.
3. Reuse existing patterns once the codebase has been established.
4. Do not introduce unnecessary dependencies.
5. Keep auth, role checks, and validation explicit.
6. Favor readable folder structure over premature abstraction.
7. Update related documentation when major features or architecture changes.

---

## MVP Feature Scope

### Authentication
- Login/logout
- Current user endpoint
- Role-based route protection

### Ticket Management
- Create ticket
- View ticket list
- View ticket details
- Update ticket status
- Assign ticket to agent
- Filter tickets

### Communication
- Add public replies
- Add internal notes
- Persist ticket history

### Administration
- User management
- Category management
- Priority management
- Dashboard metrics

---

## API Expectations

Planned route groups:

### Auth
- `POST /api/auth/login`
- `POST /api/auth/logout`
- `GET /api/auth/me`

### Users
- `GET /api/users`
- `POST /api/users`
- `PUT /api/users/:id`
- `DELETE /api/users/:id`

### Tickets
- `GET /api/tickets`
- `POST /api/tickets`
- `GET /api/tickets/:id`
- `PUT /api/tickets/:id`
- `PATCH /api/tickets/:id/status`
- `PATCH /api/tickets/:id/assign`

### Comments
- `GET /api/tickets/:id/comments`
- `POST /api/tickets/:id/comments`

### Metadata
- `GET /api/categories`
- `POST /api/categories`
- `GET /api/priorities`

### Dashboard
- `GET /api/dashboard/stats`

---

## UI Direction

Target screens for MVP:

- Login page
- Dashboard page
- Ticket list page
- Ticket details page
- Create ticket page
- User management page
- Settings / metadata management page

UI should be:

- Responsive
- Clean and admin-dashboard oriented
- Tailwind-first
- Componentized where reuse is obvious

---

## Security & Validation Rules

Agents should preserve and enforce:

- Password hashing for stored passwords
- JWT auth with protected backend routes
- Role checks on sensitive operations
- Server-side validation for all write endpoints
- Sanitized database interactions via parameterized queries or ORM support

---

## Suggested Milestones

1. Project scaffolding
2. Auth and role system
3. Ticket CRUD
4. Assignment and comments
5. Admin management
6. Dashboard and reporting
7. Testing and deployment

---

## Documentation Rules

Whenever implementing a significant change, update documentation if it affects:

- setup steps
- folder structure
- API contracts
- database schema
- environment variables
- feature scope

---

## Notes for Future Agents

If the repository is still early-stage, prioritize:

1. structure
2. conventions
3. authentication foundation
4. database schema stability
5. basic ticket workflow

Avoid gold-plating advanced features before MVP is complete.