From 27d74ffbe1c7c554719ca122732ef2876c089c37 Mon Sep 17 00:00:00 2001 From: Sonny May <102835434+sonnymay@users.noreply.github.com> Date: Sun, 24 May 2026 15:50:59 -0500 Subject: [PATCH] docs: polish README with badges, TOC, contributing, license --- README.md | 109 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 66 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index e0f8433..5ea7ec5 100644 --- a/README.md +++ b/README.md @@ -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) --- @@ -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. @@ -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 @@ -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 - -_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