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