tentix

Tentix = Ten (10x Efficiency) Tix (Ticketing System)

English | 中文

An AI-native customer service platform that delivers 10x accelerated resolution.

• 🚀 10x faster response time
• 🤖 10x less human intervention
• 😊 10x higher customer satisfaction

🖥 Try on Sealos

One-click deployment in the App Market. Configure one AI agent and one staff member to try it out.

Table of Contents

• Architecture
• Features
• Requirements
• Deployment
• Developer Guide
• Roadmap
• Contributing
• Support

Architecture

graph TD
    A[Ticket data sources] --> B[Knowledge base builder]
    C[General docs] --> B
    D[Starred conversations] --> B

    B --> E[Unified Vector KB<br/>PostgreSQL + pgvector]

    E --> F[LangGraph AI Agent]

    G[User messages] --> H[Query refinement]
    I[Ticket info] --> H

    H --> J[Knowledge retrieval]
    E --> J

    J --> F
    F --> K[Generate reply]

    subgraph "Knowledge priority"
        L[1. Starred conversations<br/>Weight: 1.0]
        M[2. Historical tickets<br/>Weight: 0.8]
        N[3. General knowledge<br/>Weight: 0.6]
    end

graph TD
    A[Start build] --> B{Select knowledge type}

    B -->|Starred| C[Extract starred tickets/messages]
    B -->|Historical| D[Filter solved, high-quality tickets]
    B -->|General| E[Load document files]

    C --> F[AI-enhanced processing<br/>Summaries and retrievers]
    D --> G[Ticket doc building<br/>Key dialog extraction]
    E --> H[Document chunking]

    F --> I[Embedding]
    G --> I
    H --> I

    I --> J[Store into unified KB]
    J --> K[Done]

Features

• Customer service chat system
• AI workflow (LangGraph: Analyze → Generate query → Retrieve → Generate answer)
• Multi-channel notifications; Feishu supported; other IM/forms via modular integration
• Extensible architecture: Modular design for pluggable extensions
• Unified authentication design: Pluggable third-party integrations
• Vector backend: PostgreSQL + pgvector or external vector service (FastGPT)
• Agent model config: Model/temperature/TopP/max tokens, etc., configurable in admin

Requirements

• Bun ≥ 1.2.16
• PostgreSQL (with pgvector extension)
• MinIO (or S3-compatible object storage)
• OpenAI/FastGPT credentials

Deployment

1) Build Docker image

docker build -t tentix:latest .

2) Configure PostgreSQL and run migrations

Note: Migration reads .env.local in the project root. Set DATABASE_URL first.

cd server
bun run migrate

3) Configure required environment variables

• Required:

DATABASE_URL="postgres://USER:PASSWORD@HOST:PORT/DB"

# Generate Base64 encryption key (run in server/):
#   cd server && bun run script/getCryptoKey.ts
ENCRYPTION_KEY="<Base64 key generated above>"

# Object storage for images and other media in conversations
MINIO_ACCESS_KEY="<minio-access-key>"
MINIO_SECRET_KEY="<minio-secret-key>"
MINIO_BUCKET="<bucket-name>"
MINIO_ENDPOINT="<http(s)://host:port>"  # e.g., http://minio:9000

• AI-related (optional, when enabling AI replies):

OPENAI_BASE_URL="<https://api.openai.com/v1>"
OPENAI_API_KEY="<openai-api-key>"
SUMMARY_MODEL="<model for summarization>"
EMBEDDING_MODEL="<model for embeddings>"
CHAT_MODEL="<model for chat>"
FAST_MODEL="<model for fast responses>"
MAX_AI_RESPONSES_PER_TICKET=3  # default 3

• Optional (Feishu group and staff push):

FEISHU_APP_ID="<feishu-app-id>"
FEISHU_APP_SECRET="<feishu-app-secret>"
FEISHU_CHAT_ID="<feishu-chat-id>"
APP_URL="<public app URL>"

5) Run the container

docker run -d \
  --name tentix \
  -p 3000:3000 \
  --env-file ./.env.local \
  tentix:latest

• Health check: /health
• Default port: 3000

Developer Guide

Developer help: See DEVELOPMENT_GUIDE.md · server/README.md · frontend/README.md

Follow these steps to quickly start the local development environment.

Clone and Install

git clone https://github.com/labring/tentix.git
cd tentix
bun install

Configure Database and Migrate

Note: Migration reads .env.local in the project root; set DATABASE_URL first.

You can provision a PostgreSQL database on the Sealos Console. Sealos provides easy database setup and a built-in management UI.

# Create/edit .env.local in project root with at least:
echo 'DATABASE_URL="postgres://USER:PASSWORD@HOST:PORT/DB"' >> .env.local

# Enter server/ and run migration
cd server
bun run migrate

Migrations completed.

Configure Environment Variables

cp .env.template .env.local
# Complete/override variables in .env.local as needed (e.g., ENCRYPTION_KEY, MINIO_*, OPENAI_*)

Tip: To generate ENCRYPTION_KEY, run bun run script/getCryptoKey.ts under server/ and put the result into .env.local.

Start Development

cd ..  # back to project root if currently under server/
bun run dev

Common Commands

bun run lint
bun run typecheck
bun run format
bun run build
# Dry run build for testing and checking build errors
bun run build --dry
# Force build
bun run build --force

Roadmap

Planned features in priority order, covering Admin and Agent dashboards:

• Admin
  • Staff management panel: modify roles (including agents), manage accounts and bindings (Sealos/Feishu)
  • Knowledge base indexing: add indexing for "General Docs" and "Historical Tickets"
    • Historical ticket indexing: scheduled jobs (e.g., every 7/14 days)
    • General docs: upload, parse, and structure into unified knowledge entries
  • KB hit testing: test retrieval and answer quality without creating tickets
  • KB visualization: view and visualize starred/general/historical KB entries
  • Knowledge graph visualization: entities, relations, and weights
  • Prompt customization: visualize and A/B test the agent workflow prompts
  • Workflow orchestration: evolve the fixed workflow into a composable bot
• Analytics
  • Ticket distribution: by category (pie), feedback tickets ratio (pie)
  • KB hit rate: trend and distribution
  • Ticket volume: time series (line)
  • Feedback: time series (line) and star distribution (pie)
  • Handoff metrics: human-handoff vs. non-handoff vs. total
• Agent dashboard and features
  • KB hit testing entry point
  • Index management and visualization
  • Personal ticket metrics:
    • Assigned/participated/related ticket counts (filters: handed-off/not handed-off/all)
    • Distribution by module and trends

Todo summary:

• Admin: Staff management and account binding (Sealos/Feishu)
• Admin: General docs and historical ticket indexing (with schedules)
• Admin: KB hit testing and visualization
• Admin: Prompt customization and workflow orchestration
• Analytics: Ticket distribution, hit rate, volume, and feedback trends
• Agent: Hit testing and index visualization; personal metrics dashboard

🤝 Contributing

Submit Code

1. Fork the project to your GitHub account
2. Create feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -m 'feat: your change'
4. Push branch: git push origin feature/your-feature
5. Create Pull Request (PR)

Commit Message Standards

Use Conventional Commits standards:

feat: add new feature
fix: fix bug
docs: update documentation
style: format code
refactor: refactor code
test: add tests
chore: update dependencies

Code Review

All code changes must go through Pull Request review:

• Ensure all tests pass
• Follow project code standards
• Add necessary documentation and comments
• Update related test cases

🆘 Support

If you encounter problems or have questions:

1. Check if there are similar issues in Issues
2. Create a new Issue describing your problem
3. Contact project maintainers

---

Happy Coding! 🎉