{"id":51007700,"url":"https://github.com/rafael-acerqueira/support-ops","last_synced_at":"2026-06-20T22:30:24.488Z","repository":{"id":363928468,"uuid":"1265543677","full_name":"rafael-acerqueira/support-ops","owner":"rafael-acerqueira","description":"Support operations platform for B2B SaaS teams, featuring ticket triage, versioned knowledge base, grounded response drafts, human review, and evaluation metrics.","archived":false,"fork":false,"pushed_at":"2026-06-10T23:26:58.000Z","size":259,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T01:14:50.958Z","etag":null,"topics":["docker","fastapi","llm","pydantic","pytest","python","rag","sqlalchemy","vector-database"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rafael-acerqueira.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-10T21:45:17.000Z","updated_at":"2026-06-10T23:27:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rafael-acerqueira/support-ops","commit_stats":null,"previous_names":["rafael-acerqueira/support-ops"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rafael-acerqueira/support-ops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-acerqueira%2Fsupport-ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-acerqueira%2Fsupport-ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-acerqueira%2Fsupport-ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-acerqueira%2Fsupport-ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rafael-acerqueira","download_url":"https://codeload.github.com/rafael-acerqueira/support-ops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafael-acerqueira%2Fsupport-ops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34587988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","llm","pydantic","pytest","python","rag","sqlalchemy","vector-database"],"created_at":"2026-06-20T22:30:21.659Z","updated_at":"2026-06-20T22:30:24.482Z","avatar_url":"https://github.com/rafael-acerqueira.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SupportOps\n\nSupportOps is a customer support operations platform for B2B SaaS teams.\n\nIt helps support agents triage tickets, retrieve trusted internal knowledge, generate policy-aware response drafts, review AI-assisted suggestions, and measure response quality through evaluation datasets and observability.\n\n## 🎯 Overview\n\n**Problem**: Support teams spend time searching for answers across multiple sources and risk inconsistent, unreliable responses.\n\n**Solution**: A RAG (Retrieval-Augmented Generation) platform that:\n\n- Ingests versioned documents (PDFs, Markdown, CSVs, HTML)\n- Chunks and indexes with embeddings\n- Retrieves relevant context for each support ticket\n- Generates cited responses (no hallucinations)\n- Requires human approval before sending\n- Tracks feedback for continuous improvement\n\n## 🏗️ Architecture\n\n**Hexagonal architecture** with three layers:\n\n- **Domain** (pure business logic) - independent of frameworks\n- **Application** (use-cases) - orchestrates domain services and ports\n- **Infrastructure** (adapters) - Postgres, S3, LLM APIs, Redis, etc.\n\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed design.\n\n## 🛠️ Tech Stack\n\n### Frontend\n\n- Next.js 14 (App Router)\n- Tailwind CSS + Shadcn/ui\n- Theme: Dark-first, Roxo/Cyan/Laranja\n- Deployed to Vercel (optional)\n\n### Backend\n\n- FastAPI (REST API)\n- PostgreSQL + pgvector (vector storage)\n- Redis (task queue)\n- MinIO/S3 (document storage)\n\n### Async Workers\n\n- Celery + Redis (task processing)\n- Document parsing, chunking, embeddings\n\n### Monorepo\n\n- Turbo (build orchestration)\n- pnpm (Node dependencies)\n- UV (Python dependencies)\n\n## 📁 Project Structure\n\n```\nsupportops/\n├── apps/\n│   ├── web/              # Next.js frontend\n│   ├── api/              # FastAPI backend\n│   └── workers/          # Celery workers\n├── packages/             # Shared code (future)\n├── infra/                # Docker, K8s configs\n├── scripts/              # Dev scripts\n├── docs/                 # Documentation\n├── docker-compose.yml    # Local dev environment\n├── turbo.json           # Monorepo config\n└── package.json         # Root scripts\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- Python 3.11+\n- Docker \u0026 Docker Compose plugin (`docker compose`)\n- pnpm (install: `npm i -g pnpm`)\n- UV (install: `curl -LsSf https://astral.sh/uv/install.sh | sh`)\n\n### Setup\n\n1. **Clone and enter directory**\n\n```bash\ncd supportops\n```\n\n2. **Create .env file**\n\n```bash\ncp .env.example .env\n```\n\n3. **Start infrastructure** (Postgres + pgvector, Redis, MinIO, pgAdmin)\n\n```bash\nnpm run docker:up\n```\n\nVerify services:\n\n- Postgres: `localhost:${DB_PORT}` (default in `.env.example`: `5432`)\n- Redis: `localhost:${REDIS_PORT}` (default in `.env.example`: `6379`)\n- pgAdmin: `http://localhost:5050` (admin@example.com / admin)\n- MinIO: `http://localhost:9001` (minioadmin / minioadmin)\n\n4. **Install Node dependencies** (monorepo root)\n\n```bash\npnpm install\n```\n\n5. **Install Python dependencies** (each app)\n\n```bash\ncd apps/api \u0026\u0026 uv sync\ncd ../workers \u0026\u0026 uv sync\n```\n\n6. **Start the local scaffold**\n\n```bash\nnpm run dev\n```\n\nThis runs the frontend, API, and workers in parallel. No database tables or migrations are required for the current scaffold.\n\n### Optional: Start services individually\n\nFrontend:\n\n```bash\nnpm run dev:web\n```\n\n→ http://localhost:3000\n\nBackend API:\n\n```bash\nnpm run dev:api\n```\n\n→ http://localhost:8000 (docs at /docs)\n\nWorkers:\n\n```bash\nnpm run dev:workers\n```\n\nMonitor (optional):\n\n```bash\ncd apps/workers \u0026\u0026 uv run celery -A src.celery_app flower --port=5555\n```\n\n→ http://localhost:5555\n\n## 🔌 API Endpoints (MVP)\n\n### Documents\n\n- `POST /api/documents` - Upload document\n- `GET /api/documents` - List documents\n- `GET /api/documents/{id}` - Get document\n- `GET /api/documents/{id}/versions` - Version history\n- `POST /api/documents/{id}/reindex` - Reindex embeddings\n\n### Tickets\n\n- `GET /api/tickets` - List tickets\n- `POST /api/tickets` - Create ticket\n- `GET /api/tickets/{id}` - Get ticket detail\n- `PATCH /api/tickets/{id}` - Update ticket\n- `POST /api/tickets/{id}/generate-response` - Generate AI response\n\n### Evaluations\n\n- `GET /api/evaluations/summary` - Metrics overview\n- `GET /api/evaluations/experiments` - RAG experiments\n- `GET /api/evaluations/gaps` - Knowledge gaps\n\n## 📊 Screens (MVP)\n\n1. **Documents** - Upload and manage knowledge base\n2. **Tickets** - List and filter support requests\n3. **Ticket Detail** - View customer issue and AI-suggested response\n4. **Evaluations** - Dashboard with metrics and analysis\n\n## 🎨 Design System\n\n- **Theme**: Dark-first, professional, tech-forward\n- **Primary Color**: Roxo (#7C3AED)\n- **Secondary**: Cyan (#0EA5E9)\n- **Accent**: Laranja (#F97316)\n- **UI Library**: Shadcn/ui (Tailwind + Radix)\n- **Icons**: Lucide React\n\nSee [docs/DESIGN.md](docs/DESIGN.md) for component library details.\n\n## 📝 Development\n\n### Common Commands\n\n```bash\n# From monorepo root\nnpm run docker:up        # Start local infrastructure\nnpm run dev              # Start all services in parallel\nnpm run build            # Build all apps\nnpm run lint             # Lint all code\nnpm run test             # Run all tests\nnpm run format           # Format code with Prettier\nnpm run clean            # Clean all artifacts\n\n# Docker\nnpm run docker:down      # Stop infrastructure\nnpm run docker:logs      # View infrastructure logs\n```\n\n### Code Organization\n\n**Each app follows hexagonal architecture:**\n\n- Controllers (HTTP adapters)\n- Routes (API definitions)\n- Serializers (DTOs)\n- Adapters (Infrastructure)\n- Mappers (ORM → Domain → DTO)\n\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.\n\n## 🧪 Testing\n\n```bash\n# Backend tests\ncd apps/api\nuv run pytest                    # All tests\nuv run pytest --cov             # With coverage\n\n# Frontend tests\ncd ../web\nnpm run test                         # Jest/Vitest\n\n# Workers tests\ncd ../workers\nuv run pytest\n```\n\n## 📦 Deployment\n\n### Docker Build\n\n```bash\n# Build all images\ndocker build -t supportops-web:latest apps/web -f apps/web/Dockerfile\ndocker build -t supportops-api:latest apps/api -f apps/api/Dockerfile\ndocker build -t supportops-workers:latest apps/workers -f apps/workers/Dockerfile\n```\n\n### Production Checklist\n\n- [ ] Environment variables configured\n- [ ] Database migrations run\n- [ ] Redis password set\n- [ ] S3/storage configured\n- [ ] LLM API keys set\n- [ ] CORS origins configured\n- [ ] SSL/TLS enabled\n- [ ] Logging centralized\n- [ ] Monitoring/alerting set up\n\n## 🔗 Resources\n\n- [Architecture Deep Dive](docs/ARCHITECTURE.md)\n- [Design System](docs/DESIGN.md)\n- [API Documentation](http://localhost:8000/docs)\n- [Database Schema](docs/DATABASE.md) (coming soon)\n\n## 📖 Phase Roadmap\n\n### Phase 1 - MVP (Weeks 1-2)\n\n- ✅ Scaffold monorepo\n- Document upload \u0026 versioning\n- Basic RAG pipeline\n- Frontend for documents \u0026 tickets\n- Human review workflow\n\n### Phase 2 - Production Ready (Weeks 3-4)\n\n- Reranking\n- Confidence scoring\n- Metrics \u0026 evaluation\n- Langsmith integration\n- Hardening \u0026 testing\n\n### Phase 3 - Advanced (Weeks 5+)\n\n- RAGAS evaluation\n- Fine-tuning pipelines\n- Multi-language support\n- Integrations (Zendesk, Intercom)\n\n## 🤝 Contributing\n\n1. Create a feature branch\n2. Make changes following hexagonal architecture principles\n3. Add tests\n4. Format code with `npm run format`\n5. Submit PR\n\n## 📄 License\n\nMIT\n\n## 👤 Author\n\nCreated as a portfolio project demonstrating:\n\n- Full-stack AI systems design\n- Hexagonal architecture\n- RAG implementation\n- Production-grade Python/TypeScript\n- Infrastructure as code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafael-acerqueira%2Fsupport-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frafael-acerqueira%2Fsupport-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafael-acerqueira%2Fsupport-ops/lists"}