ai-ticket-platform/docs/superpowers/specs/2026-06-30-ai-ticket-platform-design.md

AI-native Technical Support Ticket Platform Design

Date: 2026-06-30

1. Product Positioning

This project is a new long-term product, independent from the existing finance-it-support repository.

It is an AI-native technical support ticket system for single-enterprise private deployment. It is not a traditional ticket system with AI bolted on, and it is not a generic Agent platform. The core business assets are tickets, business knowledge, and reusable solutions. AI capabilities exist to improve ticket creation, support analysis, knowledge reuse, and operational review.

The system should be built as an independent Git repository so all design, code, migration scripts, and deployment assets have their own version history.

2. Core Principles

Principle	Decision
Tickets are the business spine	AI capabilities must serve ticket creation, handling, review, and knowledge reuse.
Business knowledge is a first-class asset	Documents, historical tickets, FAQs, and reusable solutions must be searchable, citable, and auditable.
Agents are controlled executors	Agents produce suggestions, drafts, and analysis by default. Business writes require human confirmation.
Skills are reusable capability templates	MVP Skills are configuration-driven, not arbitrary Python code.
MCP is the external tool boundary	Tools are authorized, risk-classified, and audited. Read-only tools come first.
Model gateway isolates providers	The system supports OpenAI-compatible channels and model comparison across chat, vision, multimodal, and embedding models.
Enterprise governance is foundational	Single-enterprise RBAC, menu permissions, button permissions, operation audit, and Agent audit should be implemented early.
Design system comes first	Frontend development starts from product theme tokens and reusable components, not ad hoc page styling.

3. Overall Architecture

The product has four layers:

Layer	Responsibility
Ticket business layer	Ticket lifecycle, comments, attachments, status transitions, reusable solutions, exports, statistics.
Business knowledge layer	Knowledge bases, documents, chunks, structured knowledge items, reusable solutions, citations.
AI platform layer	Model providers, model configs, Agents, Skills, MCP tools, vector retrieval, execution traces.
Enterprise governance layer	Users, groups, roles, menus, button permissions, audit logs, system settings.

Relationship:

Users / permissions / audit
    ↓
Tickets ←→ Business knowledge / reusable solutions
    ↓            ↓
Agents / Skills / MCP / model gateway
    ↓
LLMs / vision models / embedding models / vector retrieval

Tickets and knowledge are business assets. AI is the capability amplifier. Permissions and audit form the trust boundary.

4. MVP Scope

MVP means a complete platform skeleton with minimal but real closed loops in every core module.

Included

Module	MVP Capabilities
Enterprise admin	Users, user groups, roles, menus, button permissions, operation audit.
Tickets	Create, list, detail, edit, status transition, comments, attachments, export.
Ticket events	Status and key field changes recorded as events.
Reusable solutions	Solution library, ticket-solution links, usage count, solution recommendation.
Knowledge base	Document upload, parsing, chunking, embedding, retrieval, structured knowledge items.
Model gateway	OpenAI-compatible providers, model configs, capabilities, model tests, multi-model comparison.
Agents	Ticket creation Agent, support analysis Agent, knowledge distillation Agent.
Skills	Configuration-driven prompt templates with input/output schemas.
MCP tools	Tool server registration, tool sync, risk level, Agent binding, call audit.
Agent audit	Agent runs, steps, model calls, retrieval, tool calls, AI artifact adoption.
Migration	Import historical tickets only, then vectorize and distill useful solutions/knowledge.
Frontend design system	Theme tokens, base components, layout templates, status badges, table/form standards.

Excluded From MVP

Excluded Item	Reason
Multi-tenant SaaS	Current target is single-enterprise private deployment.
Complex BPMN workflow	Status lifecycle is enough for MVP.
Automatic dispatch loop	Requires more operational data and trust.
Automatic ticket closure	Too risky for first version.
Arbitrary Python code Skills	Security and sandboxing should come later.
Autonomous multi-Agent collaboration	Not needed for the first closed loop.
Unattended production remediation	High-risk MCP actions are out of scope.
Full compatibility with old system fields	This is a new product, not a clone of the old schema.

5. Recommended Technology Stack

Area	Choice
Backend	Django + Django Ninja
Database	PostgreSQL + pgvector
Async jobs	Celery + Redis
File storage	MinIO / S3-compatible storage
AI SDK	OpenAI Python SDK-compatible provider adapter
Frontend	React + Vite
UI base	Tailwind CSS + shadcn/ui + Radix UI
Tables	TanStack Table
Forms	React Hook Form + Zod
Icons	lucide-react
Charts	Recharts
Deployment	Docker Compose first

The backend should start as a modular monolith. Code boundaries should be clear enough to split heavy workers later, but runtime should stay simple during MVP.

Recommended Django apps:

apps/accounts
apps/tickets
apps/knowledge
apps/solutions
apps/modelhub
apps/agents
apps/skills
apps/tools
apps/audit
apps/system

6. Data Model Baseline

6.1 Ticket Core

ticket should be a slim main table. It answers: what is this ticket, what state is it in, and who owns it now.

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Ticket primary key	New system ID.
ticket_no	varchar	User-facing ticket number	Example: TK202607010001.
title	varchar	Ticket title	Core list/search field.
description	text	Problem description	User-confirmed description.
category_id	bigint	Ticket category	References ticket_category.
status	varchar	Ticket status	Pending info, pending handling, in progress, pending confirmation, resolved, closed.
priority	varchar	Priority	Low, medium, high, urgent.
impact_scope	varchar	Impact scope	Single user, branch, system-level, etc.
environment	varchar	Environment	Production, test, staging, local.
related_system_id	bigint	Related system	References a system dictionary table.
requester_id	bigint	Requester	References user.
assignee_id	bigint	Current assignee	References user.
created_by	bigint	Creator	Supports creating on behalf of another user.
created_at	datetime	Created time	System field.
updated_at	datetime	Updated time	System field.
resolved_at	datetime	Resolved time	Set when resolved.
closed_at	datetime	Closed time	Set when closed.

Fields intentionally excluded from ticket:

Data	Destination	Reason
Old system ID/source/raw JSON	Temporary migration staging only	Avoid polluting the new long-term model.
Collaborators	ticket_collaborator	Many-to-many relation.
Attachments	ticket_attachment	Large parsed/OCR content grows independently.
Comments	ticket_comment	One-to-many communication history.
Status and field changes	ticket_event	Audit and timeline.
Resolution details	ticket_resolution and solution	Separate instance handling from reusable solutions.
AI output	ticket_ai_artifact and agent_run	AI output has versions, sources, and confidence.

6.2 Ticket Subtables

ticket_comment

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Comment ID
ticket_id	bigint	Ticket ID
content	text	Comment content	Communication or handling note.
comment_type	varchar	Comment type	User supplement, internal note, system event, AI suggestion.
visibility	varchar	Visibility	Internal or requester-visible.
created_by	bigint	Creator	User or system Agent identity.
created_at	datetime	Created time

ticket_attachment

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Attachment ID
ticket_id	bigint	Ticket ID
file_name	varchar	Original file name
file_type	varchar	File type	Image, log, document, archive.
mime_type	varchar	MIME type
file_size	bigint	File size	Bytes.
storage_path	varchar	Storage path	MinIO/S3 key.
ocr_text	text	OCR or image understanding text	Optional.
parsed_text	text	Parsed document/log text	Optional.
created_by	bigint	Uploader
created_at	datetime	Uploaded time

ticket_event

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Event ID
ticket_id	bigint	Ticket ID
event_type	varchar	Event type	Status change, assignment, edit, close, AI analysis.
from_value	jsonb	Previous value	Snapshot or field value.
to_value	jsonb	New value	Snapshot or field value.
operator_id	bigint	Operator	User ID.
remark	text	Remark	Optional.
created_at	datetime	Event time

ticket_category

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Category ID
parent_id	bigint	Parent category	Supports hierarchy.
name	varchar	Category name
code	varchar	Category code	Useful for imports and rules.
description	text	Description	Can be used as AI classification context.
enabled	boolean	Enabled
sort_order	int	Sort order

6.3 Resolution And Reusable Solutions

ticket_resolution records the handling result of one ticket.

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Resolution ID
ticket_id	bigint	Ticket ID
resolution_type	varchar	Resolution type	Resolved, workaround, transferred, cannot reproduce.
root_cause	text	Case-specific root cause	Optional.
solution_text	text	Case-specific handling note	Human-confirmed.
linked_solution_id	bigint	Linked reusable solution	Optional.
confirmed_by	bigint	Confirmer
created_at	datetime	Created time
updated_at	datetime	Updated time

solution records reusable support solutions.

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Solution ID
title	varchar	Solution title
problem_signature	text	Problem signature	Error code, symptom, key log.
related_system_id	bigint	Related system	Optional.
environment_scope	varchar	Environment scope
category_id	bigint	Category
root_cause	text	Common root cause
solution	text	Standard solution steps
risk_note	text	Risk note
status	varchar	Status	Draft, published, disabled.
usage_count	int	Usage count	Incremented when adopted.
created_by	bigint	Creator
updated_at	datetime	Updated time

ticket_solution_link

Field	Type Suggestion	Meaning	Notes
ticket_id	bigint	Ticket ID
solution_id	bigint	Solution ID
link_type	varchar	Link type	Recommended, adopted, referenced.
agent_run_id	bigint	Agent source	Optional.
created_by	bigint	Creator
created_at	datetime	Created time

6.4 Knowledge Base

knowledge_base

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Knowledge base ID
name	varchar	Name	Example: payment system knowledge base.
description	text	Description
scope	varchar	Scope	System, business line, department.
enabled	boolean	Enabled
created_by	bigint	Creator
created_at	datetime	Created time
updated_at	datetime	Updated time

knowledge_document

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Document ID
knowledge_base_id	bigint	Knowledge base ID
file_name	varchar	Original file name
file_type	varchar	File type	PDF, Word, Markdown, log, etc.
storage_path	varchar	Storage path	MinIO/S3 key.
parse_status	varchar	Parse status	Pending, parsing, success, failed.
parse_error	text	Parse error	Optional.
created_by	bigint	Uploader
created_at	datetime	Uploaded time

knowledge_item

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Knowledge item ID
knowledge_base_id	bigint	Knowledge base ID
title	varchar	Title
problem	text	Problem symptom
applicable_scope	text	Applicable scope	System, version, environment, branch.
error_code	varchar	Error code	Optional.
root_cause	text	Possible cause
troubleshooting_steps	text	Troubleshooting steps
solution	text	Solution
risk_note	text	Risk note
status	varchar	Status	Draft, published, disabled.
source_type	varchar	Source type	Manual, document, ticket, AI draft.
source_ticket_id	bigint	Source ticket	Optional.
created_by	bigint	Creator
reviewed_by	bigint	Reviewer	Optional in MVP.
created_at	datetime	Created time
updated_at	datetime	Updated time

knowledge_chunk

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Chunk ID
knowledge_base_id	bigint	Knowledge base ID	Retrieval filter.
document_id	bigint	Source document	Optional.
item_id	bigint	Source item	Optional.
chunk_index	int	Chunk index
content	text	Chunk content	Retrieval context.
embedding	vector	Embedding	pgvector field.
embedding_model_id	bigint	Embedding model	References model config.
metadata	jsonb	Metadata	Page, heading, tags, etc.
created_at	datetime	Created time

6.5 AI Platform Tables

model_provider

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Provider ID
name	varchar	Provider name	OpenAI, Azure, private model, etc.
provider_type	varchar	Provider type	openai-compatible, custom.
base_url	varchar	API base URL	Supports custom channels.
api_key_encrypted	text	Encrypted API key	Never store plaintext.
enabled	boolean	Enabled
created_at	datetime	Created time
updated_at	datetime	Updated time

model_config

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Model config ID
provider_id	bigint	Provider ID
name	varchar	Display name
model_name	varchar	API model name
capabilities	jsonb	Capability tags	chat, vision, embedding, multimodal.
default_parameters	jsonb	Default params	temperature, max_tokens, etc.
is_default_chat	boolean	Default chat model
is_default_embedding	boolean	Default embedding model
enabled	boolean	Enabled

agent_definition

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Agent ID
name	varchar	Agent name	Ticket creation Agent, support analysis Agent.
agent_type	varchar	Agent type	ticket_create, ticket_analysis, knowledge_draft.
description	text	Description
model_config_id	bigint	Model config	Can override default.
system_prompt	text	System prompt	Behavior constraints.
output_schema	jsonb	Output schema	Structured output.
allowed_knowledge_base_ids	jsonb	Allowed knowledge bases	MVP can store JSON IDs.
allowed_skill_ids	jsonb	Allowed Skills
allowed_tool_ids	jsonb	Allowed MCP tools
requires_human_confirm	boolean	Requires confirmation	Default true.
enabled	boolean	Enabled
created_at	datetime	Created time
updated_at	datetime	Updated time

agent_run

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Run ID
agent_id	bigint	Agent ID
ticket_id	bigint	Ticket ID	Nullable for tests.
run_type	varchar	Run type	Creation, analysis, knowledge draft, test.
input_snapshot	jsonb	Input snapshot	Ticket, attachment summary, user input.
output	jsonb	Output result	Structured suggestion.
status	varchar	Status	running, success, failed, cancelled.
error_message	text	Error message	Optional.
created_by	bigint	Triggering user
started_at	datetime	Started time
finished_at	datetime	Finished time

agent_step

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Step ID
run_id	bigint	Agent run ID
step_type	varchar	Step type	model_call, retrieval, tool_call, skill, human_confirm.
step_name	varchar	Step name
input	jsonb	Step input	Sensitive data should be masked.
output	jsonb	Step output
latency_ms	int	Latency	Milliseconds.
status	varchar	Status	success, failed, skipped.
error_message	text	Error message	Optional.
created_at	datetime	Created time

ticket_ai_artifact

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Artifact ID
ticket_id	bigint	Ticket ID
agent_run_id	bigint	Agent run ID
artifact_type	varchar	Artifact type	Summary, field suggestion, analysis, reply draft.
content	jsonb	Artifact content	Structured AI output.
confidence	decimal	Confidence	Optional.
accepted_by	bigint	Adopting user	Nullable.
accepted_at	datetime	Adopted time	Nullable.

6.6 Skills And MCP Tools

skill_definition

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Skill ID
name	varchar	Skill name
description	text	Description
scenario	varchar	Scenario	Creation, analysis, reply, knowledge distillation.
prompt_template	text	Prompt template	Supports variables.
input_schema	jsonb	Input schema
output_schema	jsonb	Output schema
allowed_tool_ids	jsonb	Allowed tools	Optional in MVP.
enabled	boolean	Enabled
created_at	datetime	Created time
updated_at	datetime	Updated time

tool_server

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	MCP server ID
name	varchar	Server name	Example: log platform MCP.
server_url	varchar	Server URL
auth_type	varchar	Auth type	none, token, basic, custom.
auth_config_encrypted	text	Encrypted auth config
enabled	boolean	Enabled
created_at	datetime	Created time

tool_definition

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Tool ID
server_id	bigint	MCP server ID
name	varchar	Tool name
description	text	Description
input_schema	jsonb	Input schema	Synced from MCP.
risk_level	varchar	Risk level	low, medium, high.
requires_human_confirm	boolean	Requires confirmation	High risk defaults true.
enabled	boolean	Enabled

tool_call

Field	Type Suggestion	Meaning	Notes
id	bigint / uuid	Tool call ID
run_id	bigint	Agent run ID
tool_id	bigint	Tool ID
input	jsonb	Call input
output	jsonb	Call output
status	varchar	Status	success, failed, blocked, waiting_confirm.
confirmed_by	bigint	Confirmer	Nullable.
created_at	datetime	Call time

7. Agent, Skill, MCP Boundaries

Concept	Responsibility
Agent	Owns the task goal and execution flow.
Skill	Provides reusable professional capability templates.
MCP	Provides authorized external tool access.

MVP built-in Agents:

Agent	Goal	Input	Output	Auto-write business data
Ticket creation Agent	Help users create complete tickets	Description, images, attachment summaries	Field drafts, missing-info questions, category suggestions, similar tickets	No
Support analysis Agent	Help support engineers analyze tickets	Ticket detail, comments, attachments, knowledge retrieval	Possible causes, steps, solution recommendations, reply draft	No
Knowledge distillation Agent	Turn resolved tickets into knowledge	Ticket, comments, adopted solution	Solution draft, knowledge item draft	No

MVP Skill examples:

Skill	Purpose
Field extraction	Extract ticket fields from natural language.
Missing-info question generation	Identify missing key information and ask concise questions.
Similar ticket summary	Summarize historical similar tickets.
Solution recommendation	Recommend reusable solutions from the solution library.
Customer reply generation	Draft user-facing replies.
Screenshot understanding	Extract errors and system clues from screenshots.
Knowledge draft generation	Create knowledge drafts from resolved tickets.

MCP rules:

Risk Level	Examples	MVP Strategy
low	Search docs, search historical tickets	Auto-call allowed if Agent is authorized.
medium	Query logs, monitoring, read-only business status	Auto-call allowed with full audit.
high	Modify config, run commands, restart services	Not available in MVP or requires human confirmation.

8. Frontend Product Shape

The frontend should feel like a minimal, designed enterprise AI workbench.

Navigation groups:

Workspace
Tickets
Knowledge Base
Solutions
Agents
Models & Tools
System Management

Core pages:

Module	Page	Goal
Workspace	My tasks	Pending tickets and confirmations.
Workspace	Support overview	Trends, high-frequency issues, Agent usage.
Tickets	Ticket list	Search, filter, export, batch operations.
Tickets	Create ticket	Form plus ticket creation Agent.
Tickets	Ticket detail	Handling, comments, attachments, AI analysis, solution links.
Knowledge	Knowledge bases	Manage business knowledge scopes.
Knowledge	Documents	Upload, parse, chunk, vectorize.
Knowledge	Knowledge items	Maintain structured knowledge.
Solutions	Solution library	Manage reusable solutions.
Agents	Agent config	Configure models, Skills, knowledge, tools, safety.
Agents	Agent runs	Inspect runs and steps.
Models & Tools	Model providers	Configure channels and model capabilities.
Models & Tools	Model testing	Compare model outputs.
Models & Tools	MCP tools	Register services, sync tools, configure risk.
System	Users and groups	User/group/role management.
System	Permissions	Menu and button permissions.
System	Audit logs	Operation and login logs.

9. Frontend Design System Requirement

Frontend development must start with a design system.

Dependency structure:

shadcn/ui / Radix UI / Tailwind
        ↓
Product Design System
        ↓
Business Components
        ↓
Pages

Business pages should use project-level components instead of direct ad hoc styles.

Required first-phase design tokens and standards:

Type	Content
Color	Primary, background, surface, border, text, status, risk, priority.
Typography	Font sizes, line heights, weights.
Spacing	Page padding, section gaps, form/table density.
Radius	Buttons, inputs, dialogs, cards.
Shadow	Only for popovers, dialogs, dropdowns.
Icons	Unified lucide-react icons.
Tables	Filter bar, toolbar, density, pagination, empty state.
Forms	Label alignment, validation, required fields, grouping.
Badges	Ticket status, priority, Agent state, tool risk level.
Layouts	List page, detail page, config page, workbench templates.
AI UI	Running, success, failed, references, adoption buttons, trace display.

Suggested product components:

AppButton
AppInput
AppSelect
AppTable
AppForm
AppDialog
AppDrawer
AppStatusBadge
AppPriorityBadge
AppPageHeader
AppFilterBar
AppDetailLayout
AppAuditTimeline
AgentRunPanel
KnowledgeReferenceList
SolutionRecommendationCard

Rules:

• Do not write raw color values in business pages.
• Do not define one-off status badges in pages.
• Do not build complex tables from scratch per page.
• Use unified components for Agent traces, knowledge references, and solution recommendations.
• AI accent color should be restrained. AI is a capability, not the whole visual identity.

10. Development Milestones

Stage	Goal	Key Deliverables
0. Product skeleton and design system	Establish project foundation	Backend init, frontend init, Docker Compose, auth, RBAC, audit, design tokens, base components.
1. Ticket workflow	Replace traditional ticket minimum loop	Ticket CRUD, status flow, comments, attachments, events, export, reusable solutions.
2. Knowledge and vector retrieval	Make knowledge a core asset	Knowledge base, document parsing, chunks, embeddings, retrieval, knowledge drafts.
3. Model gateway and Agent/Skill	Establish AI platform capability	Providers, model configs, model comparison, Skills, built-in Agents, Agent runs/steps.
4. MCP tools and trust boundary	Add controlled tool access	MCP registration, tool sync, risk level, Agent binding, tool calls, confirmation.
5. Historical migration and polish	Prepare trial replacement	Import historical tickets, vectorize, distill solutions, dashboards, UI polish.

11. Historical Ticket Migration

Only historical tickets should be migrated. Old users, roles, menus, and organization structures should not be migrated.

Stage	Goal	Approach	Output
Raw import	Make historical tickets searchable	Map old records into the new ticket structure via migration staging.	Historical ticket list/detail.
Standardization	Improve retrieval quality	Use rules/AI to extract title, category, system, environment, error codes.	Standard fields and summaries.
Vectorization	Support similar ticket search	Embed description, handling notes, and solution text.	Historical tickets available to retrieval.
Knowledge distillation	Convert valuable tickets into knowledge	Generate drafts, then manually publish.	solution, knowledge_item, knowledge_chunk.
User mapping	Avoid legacy org lock-in	Keep old people names as text where needed; optionally bind to new users later.	Migration remains lightweight.

12. Acceptance Criteria For The First Architecture Slice

The first usable architecture slice is complete when:

• The system can run locally with Docker Compose.
• Admin users can log in and manage users/groups/permissions.
• The design system has a preview page and business pages use shared components.
• Users can create and process tickets end to end.
• Tickets can link to reusable solutions.
• Documents and knowledge items can be vectorized and retrieved.
• At least one OpenAI-compatible model provider can be configured and tested.
• Built-in Agents can create auditable runs and steps.
• AI artifacts can be accepted, edited, or ignored by users.
• MCP tools can be registered and audited, with high-risk calls blocked or requiring confirmation.

13. Open Questions

Topic	Current Decision	Later Decision Needed
Primary key style	bigint or uuid both acceptable	Decide during implementation setup.
Next.js vs Vite	Vite React is preferred for private admin MVP	Revisit only if SSR/BFF becomes necessary.
Code-type Skills	Excluded from MVP	Revisit with sandbox design.
High-risk MCP tools	Excluded or confirmation-only	Revisit after audit and trust model matures.
Workflow engine	Simple status flow for MVP	Revisit if SLA/escalation complexity grows.