cygnusnetworks/tiqora repository overview

⁠Tiqora

Tiqora is a modern, self-hosted ticket / helpdesk system that is database-compatible with OTRS 6.0.x and Znuny 6.0–7.3 (MariaDB/MySQL and PostgreSQL). It is a clean-room reimplementation (Python FastAPI + React), not a fork of Znuny — no Znuny source code is included or redistributed.

⁠Try it

In the browser, nothing to install: the interactive demo⁠ runs the full agent, admin and portal UI against mock data.

On your machine, one command (Docker with Compose v2):

curl -fsSLO https://raw.githubusercontent.com/CygnusNetworks/tiqora/main/docker-compose.quickstart.yml
docker compose -f docker-compose.quickstart.yml up -d

Open http://localhost:8000/⁠ and sign in as root@localhost / tiqora-demo. The first start creates the database and seeds 40 fake tickets; docker compose -f docker-compose.quickstart.yml down -v removes everything again. The quickstart is for evaluation only (fixed passwords, plain HTTP). For a real installation see Getting started⁠.

Running OTRS or Znuny already? Tiqora can work on your existing database, next to Znuny — read Moving off OTRS/Znuny without a big-bang migration⁠ or the comparison with Znuny, OTRS, Zammad and others⁠.

Questions, ideas, war stories from your OTRS migration: GitHub Discussions⁠.

⁠Why Tiqora

• Modern web UI — agent workspace, admin console, and customer portal that feel like a current product, not a 2000s helpdesk skin.
• Znuny / OTRS 6.0–7.3 database compatibility — same core ticket tables; a runtime schema profile detects the peer (see docs/support-matrix.md⁠). Parallel operation on one shared database is a first-class path (additive tiqora_* tables only until you explicitly take schema ownership). Preferred peers: Znuny 6.5 (LTS) or 7.3.
• AI-ready ticket search — Meilisearch indexing plus an MCP server so AI agents act with the same ACLs as humans.
• AI agent assistance — per-queue policies drive draft replies, state-only ticket summaries (document- and attachment-aware), AI triage (queue routing for new tickets), text refine with a word-level diff to review (and a call-note mode for phone notes), and an optional autonomous auto-reply worker. Attachments get text extraction plus a vision pre-pass for images; sensitive data is PII-masked (spaCy NER) before any LLM call; every request lands in an audit log with per-subject ACLs, token/request limits and per-provider cost budgets (day/week/month). Every AI-written article is marked 🤖 in the ticket and carries the tool trace behind it — each call with the arguments it was made with. The agent can hand off to a human, which really stops the auto-reply until someone takes over, and agents can pause all automatic AI actions per ticket. Bring your own OpenAI-compatible endpoints: a model catalog with fallback profiles and per-task routing (research, answer, triage, summary, refine, vision — globally or per queue). Gated by the operation mode so nothing autonomous runs during parallel operation (except auto-replies on Tiqora-only channels such as Telegram).
• PGP and S/MIME — Znuny-compatible key stores shared with a running Znuny; inbound mail verified and decrypted (security badge per article), outbound replies, forwards, new email tickets and event notifications signed and/or encrypted, with per-queue defaults (sign by default; encryption off / when possible / required), customer keys, and settings editable in the admin UI (Znuny's SysConfig still wins where it is set).
• Telegram chat & phone/CTI — a messenger-style chat composer for Telegram tickets (attachments, quote replies, answer buttons that resolve the ticket, edit/retract, chat snippets), and Znuny phone parity with an incoming-call popup fed by a PBX webhook, caller lookup, click-to-call and a compact phone ticket form.
• GDPR tooling — anonymization, retention jobs, and audit trails in admin.
• Modern design — light, dark and system themes, compact cobalt design system.
• 49 UI languages — full Znuny language catalogue (48 Znuny .po codes + English source), RTL included; agent preference syncs with Znuny UserLanguage (see docs/i18n.md⁠).
• No Perl application stack — Python FastAPI + React throughout Tiqora itself (optional small Znuny OPM addon only if you co-run Znuny for cache coherence).
• Customer portal & knowledge base — self-service tickets (opt-in via TIQORA_PORTAL_ENABLED) and Markdown KB.
• Integration-friendly — REST /api/v1, GenericInterface REST/SOAP compatibility, webhooks, channel plugins (email, SMS, WhatsApp, Telegram, phone/CTI).
• Modern auth — legacy password hashes, OIDC, LDAP/AD, Kerberos/SPNEGO (with seamless re-auth when a session expires), enforceable TOTP, and passkeys.

⁠Live product site & demo

Product site⁠ — overview, features, screenshots.

Interactive demo⁠ — full agent, admin, and portal UI in the browser against mock data (nothing is saved). Built from frontend/ with Mock Service Worker⁠; local build:

VITE_BASE=/tiqora/demo/ pnpm --filter tiqora-frontend build:demo

⁠Screenshots

_{Inbox sorted by last activity, with e-mail / Telegram / phone filters — and a CTI popup for the call that is ringing through.}

Grouped by topic; click a section to expand it, click a picture for full size. The product site⁠ shows the same set as a gallery with a light/dark switch.

AI assistance — summaries, drafts with MCP tools, auto-replies, refine, model routing (12)

Ticket summary	Draft grounded in MCP tools	Auto-reply with its tool trace
Refine, reviewed as a diff	Model catalog	Task → profile routing
Per-queue policies	AI settings	Providers
Cost budget & tool rounds	MCP tool sources	LLM request audit

Agent workspace — inbox, ticket view, dashboard, search, reports, calendar, KB (7)

Inbox	Ticket view	Dashboard
Search	Reporting & SLA	Calendar
Knowledge base

Chat & phone — Telegram chat, CTI call popup, compact phone ticket (3)

Telegram chat	CTI call popup	Phone ticket with caller lookup

PGP & S/MIME — verified mail, signed & encrypted replies, queue defaults, key admin (5)

Verified signature on arrival	Sign & encrypt in the composer	Per-queue security defaults
PGP keys	S/MIME certificates

Administration — queues & escalation, agents, groups, customers, fields, GDPR, 2FA (10)

Queues	Escalation matrix	Agents
Groups	Roles ↔ groups	Customer users
Customer user groups	Dynamic fields	Privacy / GDPR
Two-factor

Sign-in & portal — login, account security, account menu, customer portal (4)

Login	Account security	Account menu	Customer portal

_{Generated with SCREENSHOTS=1 pnpm exec playwright test screenshots (e2e/fixtures/rich-mock.ts) — no backend required. Use THEME=dark / LANG_UI=de for variants.}

⁠Also included

⁠Architecture overview

                    ┌──────────────────────────────────────────┐
                    │              Clients                      │
                    │  Agent UI · Portal · Admin · AI agents    │
                    └───────────┬──────────────┬────────────────┘
                                │              │
                     /api/v1    │              │  MCP (streamable HTTP)
              /znuny-compat/*   │              │
                                ▼              ▼
                    ┌────────────────┐  ┌─────────────┐
                    │  tiqora-api    │  │ tiqora-mcp  │
                    │  (FastAPI)     │  │ (FastMCP)   │
                    └───────┬────────┘  └──────┬──────┘
                            │                  │
                            │   domain/*       │
                            │   permissions/*  │
                            ▼                  ▼
              ┌─────────────────────────────────────────────┐
              │              Shared domain layer             │
              │  TicketService · ACL · sessions · outbox     │
              └───────────┬───────────────────┬─────────────┘
                          │                   │
           ┌──────────────▼──────┐   ┌────────▼────────┐
           │  OTRS/Znuny tables  │   │  tiqora_* tables│
           │  (6.0–7.3; R/W, no  │   │  (Alembic chain │
           │   schema changes)   │   │   versions_tiqora)│
           └──────────┬──────────┘   └────────┬────────┘
                      │                       │
         ┌────────────▼──────────┐            │
         │  Peer instance        │            │
         │  (optional parallel)  │◄── cache invalidation via TiqoraSync OPM
         └───────────────────────┘
                      │
         ┌────────────▼────────────────────────────────────┐
         │  tiqora-worker · ai-worker · Redis · Meili      │
         └─────────────────────────────────────────────────┘

flowchart TB
  subgraph clients [Clients]
    AgentUI[Agent UI]
    Portal[Customer Portal]
    Admin[Admin]
    AI[AI Agents via MCP]
  end

  subgraph tiqora [Tiqora]
    API[tiqora-api FastAPI]
    MCP[tiqora-mcp FastMCP]
    Worker[tiqora-worker + ai-worker]
    Domain[domain + permissions]
  end

  subgraph data [Shared data plane]
    ZTables[(Znuny tables)]
    TTables[(tiqora_* tables)]
    Redis[(Redis)]
    Meili[(Meilisearch)]
  end

  Znuny[OTRS/Znuny 6.0–7.3 peer]

  AgentUI --> API
  Portal --> API
  Admin --> API
  AI --> MCP
  API --> Domain
  MCP --> Domain
  Domain --> ZTables
  Domain --> TTables
  Worker --> ZTables
  Worker --> TTables
  Worker --> Redis
  Worker --> Meili
  Znuny --> ZTables
  Domain -.->|tiqora_cache_invalidation| Znuny

Package layout (backend):

backend/src/tiqora/
  db/legacy/        # Hand-written models for Znuny tables + conformance tests
  db/tiqora/        # tiqora_* models (Alembic: versions_tiqora / versions_owned)
  znuny/            # Invariants: ticket numbers, history, escalation, follow-up, …
  domain/           # Services — sole write paths, bundling invariants
  permissions/      # Groups/roles + ACL for UI, REST, MCP
  events/           # Async bus + transactional outbox
  channels/         # Channel plugins (email, SMS, WhatsApp, Telegram, phone)
  storage/          # StorageBackend interface (DB MIME in V1)
  api/              # v1 routers + GenericInterface compat layer
  mcp_server/       # FastMCP process
  worker/           # asyncio worker loops (daemon takeover, outbox, pollers)
  kb/               # Knowledge base

⁠Parallel operation with Znuny

Tiqora and Znuny can share one PostgreSQL or MariaDB/MySQL database:

See docs/parallel-operation.md⁠ for the full invariant list.

⁠Getting started — three ways to run

⁠Quick start (development)

⁠Prerequisites

• Docker / Docker Compose
• uv⁠ (Python)
• Node 20+ and pnpm⁠ (frontend)
• Optional: just⁠

⁠1. Start infrastructure

docker compose -f docker-compose.dev.yml up -d
# MariaDB :3306, Postgres :5432, Redis :6379, Meilisearch :7700, Mailpit :8025/:1025

⁠2. Backend

cd backend
uv sync
export DATABASE_URL=postgresql+asyncpg://tiqora:tiqora@localhost:5432/tiqora
# or: mysql+aiomysql://tiqora:tiqora@localhost:3306/tiqora
export REDIS_URL=redis://localhost:6379/0
export MEILI_URL=http://localhost:7700
uv run uvicorn tiqora.api.app:create_app --factory --reload --host 0.0.0.0 --port 8000

Health checks:

curl -s http://localhost:8000/health
curl -s http://localhost:8000/ready
curl -s http://localhost:8000/metrics | head

⁠3. Frontend

cd frontend
pnpm install
pnpm dev
# http://localhost:5173  — agent, portal, and admin UI

⁠Makefile / just shortcuts