docs: Add Developer Guide, User Guide, and Architecture documentation
DOCS: - DEVELOPER_GUIDE.md - Setup, structure, and development workflow - USER_GUIDE.md - End user documentation - ARCHITECTURE.md - System design and components
This commit is contained in:
Ricel Leite
parent
02407a31fb
commit
af710a7620
|
|
@ -0,0 +1,366 @@
|
||||||
|
# TicketHub - Architecture Document
|
||||||
|
|
||||||
|
## System Overview
|
||||||
|
|
||||||
|
TicketHub is a lightweight issue tracking system designed for simplicity and extensibility. It follows a traditional client-server architecture with a React SPA frontend and FastAPI backend.
|
||||||
|
|
||||||
|
## High-Level Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Client │
|
||||||
|
├─────────────────────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ React Application │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
||||||
|
│ │ │Dashboard │ │ Tickets │ │ Board │ │ Projects │ ... │ │
|
||||||
|
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ React Query (Cache) │ │ │
|
||||||
|
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ Axios HTTP Client │ │ │
|
||||||
|
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└────────────────────────────────────────┬────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
HTTPS/REST
|
||||||
|
│
|
||||||
|
┌────────────────────────────────────────┼────────────────────────────────────────┐
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ FastAPI Application │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ API Router Layer │ │ │
|
||||||
|
│ │ │ /api/projects /api/tickets /api/comments /api/webhooks │ │ │
|
||||||
|
│ │ └────────────────────────────┬────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ │ ┌────────────────────────────▼────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ Business Logic Layer │ │ │
|
||||||
|
│ │ │ ProjectService TicketService CommentService WebhookService │ │ │
|
||||||
|
│ │ └────────────────────────────┬────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ │ ┌────────────────────────────▼────────────────────────────────────┐ │ │
|
||||||
|
│ │ │ Data Access Layer │ │ │
|
||||||
|
│ │ │ SQLite (dev) / PostgreSQL (prod) │ │ │
|
||||||
|
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ └─────────────────────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ TicketHub Server │
|
||||||
|
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Component Details
|
||||||
|
|
||||||
|
### Frontend Components
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── components/
|
||||||
|
│ ├── ui/ # Reusable UI primitives
|
||||||
|
│ │ ├── Button.tsx # Button variants
|
||||||
|
│ │ ├── Card.tsx # Card container
|
||||||
|
│ │ ├── Input.tsx # Form inputs
|
||||||
|
│ │ ├── Select.tsx # Dropdowns
|
||||||
|
│ │ ├── Badge.tsx # Status/priority badges
|
||||||
|
│ │ ├── Modal.tsx # Dialog modals
|
||||||
|
│ │ ├── Table.tsx # Data tables
|
||||||
|
│ │ ├── Tabs.tsx # Tab navigation
|
||||||
|
│ │ └── Avatar.tsx # User avatars
|
||||||
|
│ └── Layout.tsx # Shell with sidebar
|
||||||
|
├── pages/
|
||||||
|
│ ├── Dashboard.tsx # Overview page
|
||||||
|
│ ├── Tickets.tsx # Ticket list
|
||||||
|
│ ├── TicketDetail.tsx # Single ticket view
|
||||||
|
│ ├── Board.tsx # Kanban board
|
||||||
|
│ ├── Projects.tsx # Project management
|
||||||
|
│ ├── Team.tsx # Team management
|
||||||
|
│ ├── Reports.tsx # Analytics
|
||||||
|
│ ├── Integrations.tsx # External integrations
|
||||||
|
│ ├── Automation.tsx # Workflow rules
|
||||||
|
│ └── Settings.tsx # Configuration
|
||||||
|
└── services/
|
||||||
|
└── api.ts # API client
|
||||||
|
```
|
||||||
|
|
||||||
|
### Backend Structure
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Main Application (main.py)
|
||||||
|
|
||||||
|
# Models
|
||||||
|
class Project:
|
||||||
|
id: int
|
||||||
|
name: str
|
||||||
|
key: str (unique, uppercase)
|
||||||
|
description: str
|
||||||
|
webhook_url: str
|
||||||
|
created_at: datetime
|
||||||
|
|
||||||
|
class Ticket:
|
||||||
|
id: int
|
||||||
|
key: str (auto-generated: PROJECT_KEY-N)
|
||||||
|
project_id: int (FK)
|
||||||
|
title: str
|
||||||
|
description: str
|
||||||
|
status: enum('open', 'in_progress', 'resolved', 'closed')
|
||||||
|
priority: enum('low', 'medium', 'high', 'critical')
|
||||||
|
assignee: str
|
||||||
|
reporter: str
|
||||||
|
created_at: datetime
|
||||||
|
updated_at: datetime
|
||||||
|
|
||||||
|
class Comment:
|
||||||
|
id: int
|
||||||
|
ticket_id: int (FK)
|
||||||
|
author: str
|
||||||
|
content: str
|
||||||
|
created_at: datetime
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE projects (
|
||||||
|
id INTEGER PRIMARY KEY,
|
||||||
|
name TEXT NOT NULL,
|
||||||
|
key TEXT UNIQUE NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
webhook_url TEXT,
|
||||||
|
ticket_count INTEGER DEFAULT 0,
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE tickets (
|
||||||
|
id INTEGER PRIMARY KEY,
|
||||||
|
key TEXT UNIQUE NOT NULL,
|
||||||
|
project_id INTEGER REFERENCES projects(id),
|
||||||
|
title TEXT NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
status TEXT DEFAULT 'open',
|
||||||
|
priority TEXT DEFAULT 'medium',
|
||||||
|
assignee TEXT,
|
||||||
|
reporter TEXT,
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE comments (
|
||||||
|
id INTEGER PRIMARY KEY,
|
||||||
|
ticket_id INTEGER REFERENCES tickets(id),
|
||||||
|
author TEXT NOT NULL,
|
||||||
|
content TEXT NOT NULL,
|
||||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||||
|
);
|
||||||
|
|
||||||
|
-- Indexes
|
||||||
|
CREATE INDEX idx_tickets_project ON tickets(project_id);
|
||||||
|
CREATE INDEX idx_tickets_status ON tickets(status);
|
||||||
|
CREATE INDEX idx_comments_ticket ON comments(ticket_id);
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Design
|
||||||
|
|
||||||
|
### RESTful Endpoints
|
||||||
|
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | /api/projects | List all projects |
|
||||||
|
| POST | /api/projects | Create project |
|
||||||
|
| GET | /api/projects/{id} | Get project |
|
||||||
|
| PATCH | /api/projects/{id} | Update project |
|
||||||
|
| DELETE | /api/projects/{id} | Delete project |
|
||||||
|
| GET | /api/tickets | List tickets (with filters) |
|
||||||
|
| POST | /api/tickets | Create ticket |
|
||||||
|
| GET | /api/tickets/{id} | Get ticket |
|
||||||
|
| PATCH | /api/tickets/{id} | Update ticket |
|
||||||
|
| DELETE | /api/tickets/{id} | Delete ticket |
|
||||||
|
| GET | /api/tickets/{id}/comments | List comments |
|
||||||
|
| POST | /api/tickets/{id}/comments | Add comment |
|
||||||
|
|
||||||
|
### Webhook System
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐ Event ┌─────────────┐ HTTP POST ┌──────────────┐
|
||||||
|
│ Ticket │ ──────────────►│ Webhook │ ─────────────────►│ External │
|
||||||
|
│ Created │ │ Handler │ │ System │
|
||||||
|
└─────────────┘ └─────────────┘ └──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
Events: `ticket.created`, `ticket.updated`, `ticket.resolved`, `comment.added`
|
||||||
|
|
||||||
|
## Deployment Architecture
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
```
|
||||||
|
┌───────────────┐ ┌───────────────┐
|
||||||
|
│ Frontend │ ──────► │ Backend │
|
||||||
|
│ Vite Dev │ proxy │ Uvicorn │
|
||||||
|
│ :5173 │ /api │ :8001 │
|
||||||
|
└───────────────┘ └───────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌───────────────┐
|
||||||
|
│ SQLite │
|
||||||
|
│ (file) │
|
||||||
|
└───────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Production
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ Docker Swarm │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────┐ │
|
||||||
|
│ │ Traefik Proxy │ ◄── tickethub.startdata.com.br │
|
||||||
|
│ └────────┬────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ├────────► /api/* ────► ┌─────────────────┐ │
|
||||||
|
│ │ │ API Service │ │
|
||||||
|
│ │ │ FastAPI │ │
|
||||||
|
│ │ └────────┬────────┘ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ ▼ │
|
||||||
|
│ │ ┌─────────────────┐ │
|
||||||
|
│ │ │ PostgreSQL │ │
|
||||||
|
│ │ └─────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ └────────► /* ──────► ┌─────────────────┐ │
|
||||||
|
│ │ NGINX Static │ │
|
||||||
|
│ │ (React Build) │ │
|
||||||
|
│ └─────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Creating a Ticket
|
||||||
|
|
||||||
|
```
|
||||||
|
1. User fills form
|
||||||
|
└─► React state
|
||||||
|
|
||||||
|
2. Submit
|
||||||
|
└─► POST /api/tickets
|
||||||
|
└─► Validate
|
||||||
|
└─► Generate key (PROJECT-N)
|
||||||
|
└─► Insert to DB
|
||||||
|
└─► Return ticket
|
||||||
|
|
||||||
|
3. Webhook (async)
|
||||||
|
└─► If project.webhook_url
|
||||||
|
└─► POST to external URL
|
||||||
|
└─► Payload: {event, timestamp, data}
|
||||||
|
|
||||||
|
4. Update UI
|
||||||
|
└─► React Query invalidate
|
||||||
|
└─► Refetch tickets
|
||||||
|
└─► Display new ticket
|
||||||
|
```
|
||||||
|
|
||||||
|
### Kanban Drag & Drop
|
||||||
|
|
||||||
|
```
|
||||||
|
1. User drags ticket
|
||||||
|
└─► onDragStart(ticketId)
|
||||||
|
|
||||||
|
2. Drop on column
|
||||||
|
└─► onDrop(status)
|
||||||
|
└─► PATCH /api/tickets/{id}
|
||||||
|
└─► {status: newStatus}
|
||||||
|
|
||||||
|
3. Optimistic update
|
||||||
|
└─► React Query mutation
|
||||||
|
└─► Update local cache
|
||||||
|
└─► Rerender board
|
||||||
|
|
||||||
|
4. Server confirms
|
||||||
|
└─► Persist change
|
||||||
|
└─► Trigger webhook
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
### Current Implementation
|
||||||
|
- No authentication (open access)
|
||||||
|
- Input validation via Pydantic
|
||||||
|
- SQL injection prevention via parameterized queries
|
||||||
|
|
||||||
|
### Recommended Additions
|
||||||
|
1. JWT authentication
|
||||||
|
2. Role-based access control
|
||||||
|
3. API rate limiting
|
||||||
|
4. Audit logging
|
||||||
|
5. CSRF protection
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- React Query caching (5 min stale time)
|
||||||
|
- Lazy loading for routes
|
||||||
|
- Optimistic updates for mutations
|
||||||
|
- Virtualized lists for large datasets
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- Async endpoints (non-blocking I/O)
|
||||||
|
- Database connection pooling
|
||||||
|
- Pagination for list endpoints
|
||||||
|
- Indexed queries
|
||||||
|
|
||||||
|
## Extensibility
|
||||||
|
|
||||||
|
### Adding New Features
|
||||||
|
|
||||||
|
1. **New ticket fields**: Add to model, migration, API, and UI
|
||||||
|
2. **New integrations**: Add to Integrations page and webhook handler
|
||||||
|
3. **New automation**: Add to rules engine and trigger points
|
||||||
|
|
||||||
|
### Plugin System (Future)
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐
|
||||||
|
│ TicketHub │
|
||||||
|
│ Core │
|
||||||
|
├─────────────────┤
|
||||||
|
│ Plugin API │
|
||||||
|
├─────────────────┤
|
||||||
|
│ ┌─────┐ ┌─────┐ │
|
||||||
|
│ │Slack│ │Email│ │
|
||||||
|
│ └─────┘ └─────┘ │
|
||||||
|
│ ┌─────┐ ┌─────┐ │
|
||||||
|
│ │Jira │ │Git │ │
|
||||||
|
│ └─────┘ └─────┘ │
|
||||||
|
└─────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Monitoring
|
||||||
|
|
||||||
|
### Health Check
|
||||||
|
```
|
||||||
|
GET /api/health
|
||||||
|
→ {"status": "healthy", "version": "1.0.0"}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Metrics (Future)
|
||||||
|
- Request count
|
||||||
|
- Response times
|
||||||
|
- Error rates
|
||||||
|
- Active users
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Document Version: 1.0*
|
||||||
|
*Last Updated: February 2026*
|
||||||
|
*StartData Engineering*
|
||||||
|
|
@ -0,0 +1,310 @@
|
||||||
|
# TicketHub - Developer Guide
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
TicketHub is a lightweight, enterprise-grade open-source ticket and issue tracking system. Built with a modern React frontend and Python FastAPI backend.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ TicketHub │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌───────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ Frontend (React) │ │
|
||||||
|
│ │ Dashboard │ Tickets │ Board │ Projects │ Settings │ │
|
||||||
|
│ └─────────────────────────┬─────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ REST API │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────────────────────▼─────────────────────────────┐ │
|
||||||
|
│ │ Backend (FastAPI) │ │
|
||||||
|
│ │ /api/projects │ /api/tickets │ /api/webhooks │ │
|
||||||
|
│ └─────────────────────────┬─────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌─────────────────────────▼─────────────────────────────┐ │
|
||||||
|
│ │ SQLite Database │ │
|
||||||
|
│ └───────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- **React 18** - UI library
|
||||||
|
- **TypeScript** - Type safety
|
||||||
|
- **TailwindCSS** - Styling
|
||||||
|
- **React Router** - Navigation
|
||||||
|
- **React Query** - Data fetching
|
||||||
|
- **Vite** - Build tool
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- **Python 3.11** - Language
|
||||||
|
- **FastAPI** - Web framework
|
||||||
|
- **SQLite** - Database (dev)
|
||||||
|
- **PostgreSQL** - Database (prod)
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
tickethub/
|
||||||
|
├── backend/
|
||||||
|
│ └── app/
|
||||||
|
│ └── main.py # FastAPI application
|
||||||
|
├── frontend/
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── components/
|
||||||
|
│ │ │ ├── ui/ # Reusable UI components
|
||||||
|
│ │ │ └── Layout.tsx # Main layout
|
||||||
|
│ │ ├── pages/ # Route pages
|
||||||
|
│ │ ├── services/
|
||||||
|
│ │ │ └── api.ts # API client
|
||||||
|
│ │ ├── App.tsx # Router setup
|
||||||
|
│ │ └── main.tsx # Entry point
|
||||||
|
│ ├── index.html
|
||||||
|
│ ├── package.json
|
||||||
|
│ ├── tailwind.config.js
|
||||||
|
│ └── vite.config.ts
|
||||||
|
├── docs/
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Frontend Development
|
||||||
|
|
||||||
|
### Component Library
|
||||||
|
|
||||||
|
TicketHub includes a custom component library:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Available components
|
||||||
|
import {
|
||||||
|
Card,
|
||||||
|
Button,
|
||||||
|
Input,
|
||||||
|
Select,
|
||||||
|
Badge,
|
||||||
|
Modal,
|
||||||
|
Tabs, TabsList, TabsTrigger, TabsContent,
|
||||||
|
Table, TableHeader, TableHead, TableBody, TableRow, TableCell,
|
||||||
|
Avatar
|
||||||
|
} from '../components/ui'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding a New Page
|
||||||
|
|
||||||
|
1. Create component in `src/pages/`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/pages/MyPage.tsx
|
||||||
|
import { Card, Button } from '../components/ui'
|
||||||
|
|
||||||
|
export default function MyPage() {
|
||||||
|
return (
|
||||||
|
<div className="p-6">
|
||||||
|
<h1 className="text-2xl font-bold">My Page</h1>
|
||||||
|
<Card>
|
||||||
|
<p>Content here</p>
|
||||||
|
</Card>
|
||||||
|
</div>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Add route in `App.tsx`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MyPage from './pages/MyPage'
|
||||||
|
|
||||||
|
// Inside Routes
|
||||||
|
<Route path="mypage" element={<MyPage />} />
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Add to sidebar in `Layout.tsx`
|
||||||
|
|
||||||
|
### API Integration
|
||||||
|
|
||||||
|
Use React Query for data fetching:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useQuery, useMutation } from '@tanstack/react-query'
|
||||||
|
import { ticketsApi } from '../services/api'
|
||||||
|
|
||||||
|
function MyComponent() {
|
||||||
|
// Fetch data
|
||||||
|
const { data: tickets, isLoading } = useQuery({
|
||||||
|
queryKey: ['tickets'],
|
||||||
|
queryFn: () => ticketsApi.list()
|
||||||
|
})
|
||||||
|
|
||||||
|
// Mutate data
|
||||||
|
const createMutation = useMutation({
|
||||||
|
mutationFn: ticketsApi.create,
|
||||||
|
onSuccess: () => queryClient.invalidateQueries(['tickets'])
|
||||||
|
})
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Backend Development
|
||||||
|
|
||||||
|
### API Structure
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Models
|
||||||
|
class Ticket(BaseModel):
|
||||||
|
id: int
|
||||||
|
key: str
|
||||||
|
project_id: int
|
||||||
|
title: str
|
||||||
|
description: str
|
||||||
|
status: Literal['open', 'in_progress', 'resolved', 'closed']
|
||||||
|
priority: Literal['low', 'medium', 'high', 'critical']
|
||||||
|
assignee: Optional[str]
|
||||||
|
reporter: Optional[str]
|
||||||
|
created_at: datetime
|
||||||
|
updated_at: datetime
|
||||||
|
|
||||||
|
# Endpoints
|
||||||
|
GET /api/projects
|
||||||
|
POST /api/projects
|
||||||
|
GET /api/projects/{id}
|
||||||
|
PATCH /api/projects/{id}
|
||||||
|
DELETE /api/projects/{id}
|
||||||
|
|
||||||
|
GET /api/tickets
|
||||||
|
POST /api/tickets
|
||||||
|
GET /api/tickets/{id}
|
||||||
|
PATCH /api/tickets/{id}
|
||||||
|
DELETE /api/tickets/{id}
|
||||||
|
|
||||||
|
GET /api/tickets/{id}/comments
|
||||||
|
POST /api/tickets/{id}/comments
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding a New Endpoint
|
||||||
|
|
||||||
|
```python
|
||||||
|
@app.post("/api/myresource")
|
||||||
|
async def create_myresource(data: MyModel):
|
||||||
|
# Validate
|
||||||
|
# Save to database
|
||||||
|
# Return response
|
||||||
|
return {"id": new_id, **data.dict()}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Webhook System
|
||||||
|
|
||||||
|
TicketHub sends webhooks on ticket events:
|
||||||
|
|
||||||
|
```python
|
||||||
|
async def send_webhook(project_id: int, event: str, data: dict):
|
||||||
|
project = await get_project(project_id)
|
||||||
|
if project.webhook_url:
|
||||||
|
payload = {
|
||||||
|
"event": event, # ticket.created, ticket.updated, etc.
|
||||||
|
"timestamp": datetime.utcnow().isoformat(),
|
||||||
|
"data": data
|
||||||
|
}
|
||||||
|
await httpx.post(project.webhook_url, json=payload)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Running Locally
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
pip install -r requirements.txt
|
||||||
|
uvicorn app.main:app --reload --port 8001
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Full Stack (Development)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Terminal 1: Backend
|
||||||
|
cd backend && uvicorn app.main:app --reload --port 8001
|
||||||
|
|
||||||
|
# Terminal 2: Frontend (proxies /api to backend)
|
||||||
|
cd frontend && npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building for Production
|
||||||
|
|
||||||
|
### Frontend Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm run build
|
||||||
|
# Output: dist/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Deploy
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: '3.8'
|
||||||
|
services:
|
||||||
|
api:
|
||||||
|
image: python:3.11-slim
|
||||||
|
command: uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||||
|
|
||||||
|
web:
|
||||||
|
image: nginx:alpine
|
||||||
|
volumes:
|
||||||
|
- ./frontend/dist:/usr/share/nginx/html
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Backend Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
pytest tests/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontend Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Testing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create project
|
||||||
|
curl -X POST http://localhost:8001/api/projects \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"name": "Test Project", "key": "TEST"}'
|
||||||
|
|
||||||
|
# Create ticket
|
||||||
|
curl -X POST http://localhost:8001/api/tickets \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"project_id": 1,
|
||||||
|
"title": "Test ticket",
|
||||||
|
"description": "Test description",
|
||||||
|
"priority": "medium"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create feature branch: `git checkout -b feature/my-feature`
|
||||||
|
3. Make changes
|
||||||
|
4. Run tests
|
||||||
|
5. Submit pull request
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT License - StartData 2026
|
||||||
|
|
@ -0,0 +1,256 @@
|
||||||
|
# TicketHub - User Guide
|
||||||
|
|
||||||
|
## What is TicketHub?
|
||||||
|
|
||||||
|
TicketHub is a modern, open-source ticket tracking system designed for teams of all sizes. Track issues, manage projects, and collaborate with your team.
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
### Access
|
||||||
|
|
||||||
|
Open TicketHub in your browser: **https://tickethub.startdata.com.br**
|
||||||
|
|
||||||
|
### Dashboard
|
||||||
|
|
||||||
|
The dashboard gives you a quick overview:
|
||||||
|
- **Total Tickets**: All tickets across projects
|
||||||
|
- **Open**: Tickets needing attention
|
||||||
|
- **In Progress**: Tickets being worked on
|
||||||
|
- **Resolved**: Completed tickets
|
||||||
|
- **Critical**: High-priority items
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### 📁 Projects
|
||||||
|
|
||||||
|
Projects organize your tickets. Each project has:
|
||||||
|
- **Name**: Human-readable name
|
||||||
|
- **Key**: Short code (e.g., "PROJ") used in ticket IDs
|
||||||
|
- **Description**: What the project is about
|
||||||
|
- **Webhook URL**: Optional integration endpoint
|
||||||
|
|
||||||
|
**Creating a Project:**
|
||||||
|
1. Go to **Projects** page
|
||||||
|
2. Click **New Project**
|
||||||
|
3. Enter name and key
|
||||||
|
4. Optionally add webhook URL
|
||||||
|
5. Click **Create**
|
||||||
|
|
||||||
|
### 🎫 Tickets
|
||||||
|
|
||||||
|
Tickets are individual issues, tasks, or requests.
|
||||||
|
|
||||||
|
**Creating a Ticket:**
|
||||||
|
1. Click **New Ticket** (top right or dashboard)
|
||||||
|
2. Select a project
|
||||||
|
3. Enter title and description
|
||||||
|
4. Set priority
|
||||||
|
5. Click **Create**
|
||||||
|
|
||||||
|
**Ticket Fields:**
|
||||||
|
- **Key**: Auto-generated (e.g., PROJ-1)
|
||||||
|
- **Title**: Brief summary
|
||||||
|
- **Description**: Full details
|
||||||
|
- **Status**: Open → In Progress → Resolved → Closed
|
||||||
|
- **Priority**: Low, Medium, High, Critical
|
||||||
|
- **Assignee**: Who's working on it
|
||||||
|
- **Reporter**: Who created it
|
||||||
|
|
||||||
|
### 📋 Kanban Board
|
||||||
|
|
||||||
|
Visual board for tracking ticket progress:
|
||||||
|
- **Drag & Drop**: Move tickets between columns
|
||||||
|
- **Filter**: Show only one project
|
||||||
|
- **Priority Colors**: Visual indicators
|
||||||
|
|
||||||
|
### 👥 Team
|
||||||
|
|
||||||
|
Manage who has access:
|
||||||
|
- **Admin**: Full access, can manage settings
|
||||||
|
- **Member**: Create and edit tickets
|
||||||
|
- **Viewer**: Read-only access
|
||||||
|
|
||||||
|
### 📈 Reports
|
||||||
|
|
||||||
|
Analytics and insights:
|
||||||
|
- Tickets created over time
|
||||||
|
- Status distribution
|
||||||
|
- Priority breakdown
|
||||||
|
- Team performance
|
||||||
|
|
||||||
|
### 🔌 Integrations
|
||||||
|
|
||||||
|
Connect TicketHub with other tools:
|
||||||
|
- **JIRA AI Fixer**: Automatic issue analysis
|
||||||
|
- **Slack**: Notifications
|
||||||
|
- **GitHub/GitLab**: Link to PRs
|
||||||
|
|
||||||
|
### ⚡ Automation
|
||||||
|
|
||||||
|
Create rules to automate tasks:
|
||||||
|
- Auto-assign critical tickets
|
||||||
|
- Close stale tickets
|
||||||
|
- Send notifications
|
||||||
|
|
||||||
|
## Working with Tickets
|
||||||
|
|
||||||
|
### Changing Status
|
||||||
|
|
||||||
|
1. Open the ticket
|
||||||
|
2. Use the **Status** dropdown
|
||||||
|
3. Select new status:
|
||||||
|
- **Open**: New ticket, not started
|
||||||
|
- **In Progress**: Being worked on
|
||||||
|
- **Resolved**: Fix applied, awaiting verification
|
||||||
|
- **Closed**: Complete, no further action
|
||||||
|
|
||||||
|
Or use the **Board** and drag tickets between columns.
|
||||||
|
|
||||||
|
### Adding Comments
|
||||||
|
|
||||||
|
1. Open ticket detail page
|
||||||
|
2. Scroll to **Activity** section
|
||||||
|
3. Type your comment
|
||||||
|
4. Click **Add Comment**
|
||||||
|
|
||||||
|
### Assigning Tickets
|
||||||
|
|
||||||
|
1. Open ticket
|
||||||
|
2. Click **+ Assign** in sidebar
|
||||||
|
3. Select team member
|
||||||
|
4. Assignment is saved automatically
|
||||||
|
|
||||||
|
### Filtering Tickets
|
||||||
|
|
||||||
|
On the **Tickets** page:
|
||||||
|
- **Project**: Show only one project
|
||||||
|
- **Status**: Filter by status
|
||||||
|
- **Priority**: Filter by priority
|
||||||
|
- **Clear Filters**: Reset all
|
||||||
|
|
||||||
|
## Webhooks
|
||||||
|
|
||||||
|
TicketHub can notify external systems when events occur.
|
||||||
|
|
||||||
|
### Setting Up
|
||||||
|
|
||||||
|
1. Go to **Projects**
|
||||||
|
2. Edit your project
|
||||||
|
3. Add **Webhook URL**
|
||||||
|
4. Save
|
||||||
|
|
||||||
|
### Events
|
||||||
|
|
||||||
|
| Event | Trigger |
|
||||||
|
|-------|---------|
|
||||||
|
| `ticket.created` | New ticket created |
|
||||||
|
| `ticket.updated` | Ticket modified |
|
||||||
|
| `ticket.resolved` | Status changed to resolved |
|
||||||
|
| `comment.added` | New comment added |
|
||||||
|
|
||||||
|
### Payload Format
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "ticket.created",
|
||||||
|
"timestamp": "2026-02-18T18:00:00Z",
|
||||||
|
"data": {
|
||||||
|
"id": 1,
|
||||||
|
"key": "PROJ-1",
|
||||||
|
"title": "Example ticket",
|
||||||
|
"description": "...",
|
||||||
|
"status": "open",
|
||||||
|
"priority": "high",
|
||||||
|
"project_id": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Keyboard Shortcuts
|
||||||
|
|
||||||
|
| Shortcut | Action |
|
||||||
|
|----------|--------|
|
||||||
|
| `C` | Create new ticket |
|
||||||
|
| `/` | Focus search |
|
||||||
|
| `G D` | Go to Dashboard |
|
||||||
|
| `G T` | Go to Tickets |
|
||||||
|
| `G B` | Go to Board |
|
||||||
|
| `G P` | Go to Projects |
|
||||||
|
|
||||||
|
## Settings
|
||||||
|
|
||||||
|
### General
|
||||||
|
- Workspace name
|
||||||
|
- Timezone
|
||||||
|
- Language
|
||||||
|
- Date format
|
||||||
|
|
||||||
|
### Notifications
|
||||||
|
- Email alerts
|
||||||
|
- Slack integration
|
||||||
|
- Notification levels
|
||||||
|
|
||||||
|
### Security
|
||||||
|
- SSO configuration
|
||||||
|
- 2FA settings
|
||||||
|
- Session timeout
|
||||||
|
|
||||||
|
### API
|
||||||
|
- Generate API keys
|
||||||
|
- View documentation
|
||||||
|
|
||||||
|
## Tips & Best Practices
|
||||||
|
|
||||||
|
### Writing Good Tickets
|
||||||
|
|
||||||
|
**Good ticket:**
|
||||||
|
```
|
||||||
|
Title: Login fails with special characters in password
|
||||||
|
|
||||||
|
Steps to reproduce:
|
||||||
|
1. Go to login page
|
||||||
|
2. Enter email: test@example.com
|
||||||
|
3. Enter password containing: @#$%
|
||||||
|
4. Click Login
|
||||||
|
5. See error: "Invalid credentials"
|
||||||
|
|
||||||
|
Expected: Should log in successfully
|
||||||
|
Actual: Shows error message
|
||||||
|
|
||||||
|
Browser: Chrome 120
|
||||||
|
OS: Windows 11
|
||||||
|
```
|
||||||
|
|
||||||
|
**Poor ticket:**
|
||||||
|
```
|
||||||
|
Title: login broken
|
||||||
|
Description: doesn't work
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using Priorities
|
||||||
|
|
||||||
|
| Priority | Use When |
|
||||||
|
|----------|----------|
|
||||||
|
| **Critical** | System down, security issue, data loss |
|
||||||
|
| **High** | Major feature broken, blocking work |
|
||||||
|
| **Medium** | Normal bugs and features |
|
||||||
|
| **Low** | Nice to have, cosmetic issues |
|
||||||
|
|
||||||
|
### Staying Organized
|
||||||
|
|
||||||
|
1. Use consistent project keys
|
||||||
|
2. Write clear titles
|
||||||
|
3. Add relevant labels
|
||||||
|
4. Keep descriptions updated
|
||||||
|
5. Close resolved tickets
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
- **Documentation**: This guide
|
||||||
|
- **Support**: support@startdata.com.br
|
||||||
|
- **GitHub**: Report bugs or request features
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*TicketHub - Simple, Powerful Issue Tracking*
|
||||||
|
*Open Source by StartData*
|
||||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue