367 lines
18 KiB
Markdown
367 lines
18 KiB
Markdown
# 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*
|