Skip to content

docs: polish README with badges, TOC, contributing, license #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sonnymay merged 1 commit into from
May 24, 2026
Merged

docs: polish README with badges, TOC, contributing, license #14

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 66 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,29 @@
# SupportOps

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688.svg)](https://fastapi.tiangolo.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Live Demo](https://img.shields.io/badge/demo-supportops.vercel.app-brightgreen)](https://supportops.vercel.app)

> A lightweight ticketing and RMA workflow tool built by a tech support engineer, for tech support engineers.

**Live demo:** [supportops.vercel.app](https://supportops.vercel.app)
**🔗 Live demo:** [supportops.vercel.app](https://supportops.vercel.app)
**📸 Screenshots:** see [below](#screenshots)

---

## Table of contents

- [Why this exists](#why-this-exists)
- [Features](#features)
- [Stack](#stack)
- [Architecture](#architecture)
- [Local development](#local-development)
- [API surface](#api-surface)
- [Screenshots](#screenshots)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

Expand All @@ -12,7 +33,7 @@ After 9 years on the front lines of technical support, I kept hitting the same w

- Tickets, customers, and devices lived in three different systems that didn't talk to each other.
- RMA tracking was a spreadsheet someone forgot to update.
- Status changes had no audit trail when a customer asked "who closed my ticket and why?"
- Status changes had no audit trail when a customer asked *"who closed my ticket and why?"*
- The "enterprise" platforms were slow, bloated, and built for managers — not the agent actually working the queue.

SupportOps is the tool I wished I had. Tickets, devices, customers, RMAs, and a full status history — in one place, fast, and built around how support actually works.
Expand All @@ -21,53 +42,58 @@ SupportOps is the tool I wished I had. Tickets, devices, customers, RMAs, and a

## Features

- **Tickets** with status, priority, assignee, and linked customer + device
- **Customers** directory (name, email, phone, company)
- **Devices** tied to customers by serial number and product type
- **Ticket notes** for agent-side context and handoffs
- **Automatic status history** — every status change is logged with who and when
- **RMA tracking** — RMA number, serial, shipping status, resolution status, linked to the originating ticket
- 🎫 **Tickets** with status, priority, assignee, and linked customer + device
- 👥 **Customers** directory (name, email, phone, company)
- 💻 **Devices** tied to customers by serial number and product type
- 📝 **Ticket notes** for agent-side context and handoffs
- 🕓 **Automatic status history** — every status change is logged with who and when
- 📦 **RMA tracking** — RMA number, serial, shipping status, resolution status, linked to the originating ticket

---

## Stack

| Layer | Tech |
|----------|-----------------------------------------|
| Layer | Tech |
|----------|-----------------------------------------------|
| Frontend | React 19, Vite, Tailwind CSS v4, React Router |
| Backend | FastAPI (Python), Pydantic |
| Database | Supabase (PostgREST) |
| Hosting | Vercel (frontend) + Render (backend) |
| Backend | FastAPI (Python 3.11+), Pydantic |
| Database | Supabase (Postgres + PostgREST) |
| Hosting | Vercel (frontend) · Render (backend) |

---

## Architecture

```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ React + Vite │ ───▶ │ FastAPI │ ───▶ │ Supabase │
┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│ React + Vite │ ───▶ │ FastAPI │ ───▶ │ Supabase │
│ (Vercel) │ │ (Render) │ │ (PostgREST) │
└──────────────┘ └──────────────┘ └──────────────┘
└───────────────┘ └──────────────┘ └──────────────┘
```

The FastAPI layer is intentionally thin — it validates with Pydantic, applies business rules (e.g. writing to `ticket_history` on status change), and proxies to Supabase's REST API.
The FastAPI layer is intentionally thin — it validates with Pydantic, applies business rules (e.g. writing to `ticket_history` on every status change), and proxies to Supabase's REST API.

---

## Local development

### Prerequisites

- Python 3.11+
- Node.js 20+
- A Supabase project (free tier is fine) — grab your `SUPABASE_URL` and `SUPABASE_KEY`

### Backend

```bash
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
echo "SUPABASE_URL=your-url" > .env
echo "SUPABASE_KEY=your-key" >> .env
cp .env.example .env # then fill in SUPABASE_URL and SUPABASE_KEY
uvicorn main:app --reload
```

API runs at `http://localhost:8000`.
API runs at `http://localhost:8000`. Interactive docs at `/docs`.

### Frontend

Expand All @@ -83,46 +109,43 @@ App runs at `http://localhost:5173`.

## API surface

| Resource | Endpoints |
|-------------|-------------------------------------------|
| Customers | `GET/POST/PUT/DELETE /customers` |
| Devices | `GET/POST/PUT /devices` |
| Tickets | `GET/POST/PUT /tickets`, `GET /tickets/{id}` |
| Ticket Notes| `GET/POST /ticket-notes` |
| RMAs | `GET/POST/PUT /rmas` |
| Resource | Endpoints |
|---------------|----------------------------------------------|
| Customers | `GET/POST/PUT/DELETE /customers` |
| Devices | `GET/POST/PUT /devices` |
| Tickets | `GET/POST/PUT /tickets`, `GET /tickets/{id}` |
| Ticket Notes | `GET/POST /ticket-notes` |
| RMAs | `GET/POST/PUT /rmas` |

Status changes on tickets automatically append a row to `ticket_history`.

Full OpenAPI spec available at `http://localhost:8000/docs` when the backend is running.

---

## Screenshots

![Dashboard](public/screenshots/dashboard.png)
![Ticket Detail](public/screenshots/ticket-detail.png)
![AI Suggestions](public/screenshots/ai-suggestions.png)
![Ticket Detail](public/screenshots/ticket-detail.png)

---

## Roadmap

- [ ] Full-text ticket search
- [ ] SLA timers + breach alerts
- [ ] CSV export for reporting
- [ ] Role-based auth (agent / manager / admin)
- [ ] Email-to-ticket intake
- [ ] Full-text search across tickets and notes
- [ ] SLA timers with breach alerts
- [ ] Saved views / filters per agent
- [ ] CSV export of tickets and RMAs
- [ ] Role-based permissions (agent / lead / admin)

---

## Screenshots
## Contributing

<!-- Add screenshots of the dashboard, ticket detail (with AI Suggestions), and RMA views here. -->
_Coming soon._
Issues and PRs are welcome — especially from anyone who's worked a support queue and has opinions on what's missing. Please open an issue describing the change before sending a large PR.

---

## About

Built by [Sonny May](https://github.com/sonnymay) — tech support engineer, 9 years in the trenches.

Built and used internally at Baicells Technologies to manage real support tickets, RMAs, and device history.
## License

If you've worked support and recognize the pain this is solving, I'd love to hear from you.
[MIT](LICENSE) © Sonny May
Loading