18 KiB
Khira — Engineering Ticketing, Defect Tracking & Telemetry Suite
Complete System Documentation & Frontend Developer Guide
1. Overview & System Architecture
Khira is a high-performance, enterprise-grade engineering ticketing, issue management, and application runtime error tracking suite designed specifically for cross-functional engineering teams (Frontend Developers, Backend Developers, QA / Testers, and Team Leads).
Khira is built natively into the Unified Dashboard Suite (Go Gateway), serving live from port 10000 under the /khira/ URL path.
flowchart TD
subgraph Client["Browser Clients & Unified Dashboard"]
UD["Unified Dashboard Hub (/dashboard/)"] -->|Shortcut / Card Click| KHIRA_UI["Khira Web SPA (/khira/)"]
FASTAPI_DOCS["FastAPI Docs (/docs/)"] -->|Navbar Link| KHIRA_UI
KHIRA_UI --> TICKET_VIEW["Tickets & Tasks (Kanban / Table)"]
KHIRA_UI --> ERROR_VIEW["Error Telemetry & Crash Tracking"]
end
subgraph Gateway["Go Nexus Gateway (Port 10000)"]
ROUTER["Chi Router (internal/gateway/router.go)"]
KHIRA_SERVER["Khira Server (internal/khira/handlers.go)"]
KHIRA_STORE["Khira In-Memory + JSON Store (internal/khira/store.go)"]
ROUTER -->|/khira/*| KHIRA_SERVER
ROUTER -->|/khira/api/*| KHIRA_SERVER
KHIRA_SERVER --> KHIRA_STORE
end
subgraph Persistence["JSON Persistence (data/khira/)"]
USERS_DB["data/khira/users.json"]
TICKETS_DB["data/khira/tickets.json"]
ERRORS_DB["data/khira/errors.json"]
NOTIFS_DB["data/khira/notifications.json"]
UPLOADS_DIR["data/khira/uploads/"]
KHIRA_STORE <--> USERS_DB
KHIRA_STORE <--> TICKETS_DB
KHIRA_STORE <--> ERRORS_DB
KHIRA_STORE <--> NOTIFS_DB
KHIRA_SERVER <--> UPLOADS_DIR
end
2. Frontend Code Files Breakdown
If you or an external AI coding assistant need to make changes to Khira's frontend UI, layout, styling, interactions, or client-side logic, these are the exact frontend code files:
🎯 Primary Frontend File
| File Path | Description | Lines of Code |
|---|---|---|
web/khira/index.html/home/creserver/Desktop/Vaishno_workspace/Unified_Dashboard_Suite_Go/web/khira/index.html |
The Complete Single-Page Application (SPA) containing all HTML structure, all CSS styling variables and responsive rules, and all client JavaScript logic. | ~5,500 lines |
Important
Why is Khira structured in a single file?
web/khira/index.htmlis an autonomous, self-contained Single-Page Application (SPA) designed to load with zero external build-step overhead (no webpack/vite compile delay). It uses pure vanilla JavaScript (ES6+), modern CSS Custom Properties, Google Fonts (Inter, Plus Jakarta Sans, JetBrains Mono), and FontAwesome 6.5.1 CDN icons. An external AI can modifyweb/khira/index.htmldirectly without needing to runnpm buildor restart frontend bundlers.
🔗 Integration Points in Other Frontends
| File Path | Integration Purpose |
|---|---|
web/dashboard/index.html/home/creserver/Desktop/Vaishno_workspace/Unified_Dashboard_Suite_Go/web/dashboard/index.html |
The main Unified Dashboard portal. Contains the Khira Exclusive Showcase Card (#khiraToolCard), top navigation shortcut button (highlight-khira), search filtering, and click-to-open handlers. |
web/docs/index.html/home/creserver/Desktop/Vaishno_workspace/Unified_Dashboard_Suite_Go/web/docs/index.html |
The FastAPI Documentation UI. Contains the dedicated Khira Hub navigation button (.btn-khira) in the header navbar linking directly to /khira/. |
3. Detailed Anatomy of web/khira/index.html
To direct an external AI agent or developer to specific regions of web/khira/index.html, refer to this internal structure map:
Part 1: CSS Design System (<style> block, lines ~13 to 2095)
- CSS Variables & Color Palette (
:root):- Theme: Modern enterprise light theme (
--bg-canvas: #f8fafc,--bg-surface: #ffffff). - Brand accents: Indigo / Violet (
--brand-primary: #4f46e5,--brand-hover: #4338ca). - Status accents: Open (Indigo), In Progress (Blue), On Hold (Amber), Completed (Emerald).
- Priority accents: Critical P0 (Red
#b91c1c), High P1 (Orange#c2410c), Medium P2 (Sky#0369a1), Low P3 (Slate). - Telemetry Error Accents: Deep rose/crimson tags (
.sev-critical,.sev-high,.occurrences-pill,.stack-trace-box).
- Theme: Modern enterprise light theme (
- Component Styles:
.app-header: Sticky top bar with blur backdrop, logo, primary navigation switcher tabs, and profile dropdown..primary-nav-tabs&.primary-tab-btn: Header tab switcher between Tickets and Errors..profile-context-banner: Role greeting and active workload context..metrics-grid&.metric-card: Stat cards with counter badges and hover elevation..toolbar-deck: Search bar, filter dropdowns, desktop alert toggle, view toggles..kanban-view-container: 4-column responsive Kanban board (Open,In Progress,On Hold,Completed)..ticket-card: Card elevation with status pills, priority pulse, tags, avatars, links/attachments counters..table-view-container&.data-table: Data grid view for tickets and errors..error-cards-grid&.error-card: Grid cards for application telemetry exceptions..stack-trace-box: Dark monospace syntax container for PyTorch, Python, or Node.js tracebacks..detail-drawer: 740px right-hand slide-over drawer for ticket inspection and error inspection..modal-overlay&.modal-card: Centered dialog cards for Ticket Creation, Put on Hold, Resolution Remarks, Error Reporting, Error Escalation, Profile Settings, and Persona Authentication..toast-container: Non-intrusive floating feedback notifications.
Part 2: HTML Layout & Modals (lines ~2096 to 3378)
<header class="app-header">:- Brand logo + API Docs link
- Primary Switcher (
#tabNavTicketsvs#tabNavErrors) - Tickets Scope switcher (
#scopeNav: Assigned to Me / Created by Me / All Team Tickets) - Notifications Bell (
#notifBellBtn&#notifDropdown) - User Profile menu pill (
#headerUserName,#headerUserAvatar) - Action buttons (
#btnHeaderActionTicketvs#btnHeaderActionError)
<main class="main-container">:<div id="sectionTickets">: Contains tickets banner, metrics deck, filter toolbar,#kanbanViewContainer, and#tableViewContainer.<div id="sectionErrors">: Contains error context banner, error metrics deck, error filters toolbar,#errTableViewContainer, and#errCardsViewContainer.
- Slide-Over Drawers:
#detailDrawer: Ticket detail drawer with workflow buttons, hold/done alerts, metadata grid, reference links list, file attachments preview grid, activity timeline, and remark composer.#errorDrawer: Error telemetry drawer with status buttons, Convert to Developer Ticket action, formatted stack trace, request payload JSON viewer, and tags.
- Dialog Modals:
#modalCreateTicket: Form to report and assign a new ticket with file attachments and links.#modalHoldTicket: Form requiring mandatory explanation for putting a ticket on hold.#modalCompleteTicket: Form requiring resolution remarks to close a ticket.#modalReportError: Form for manual runtime error and exception ingestion.#modalEscalateError: Form for converting an error telemetry trace into a developer ticket.#modalUserProfile: Form for editing current persona name, role, avatar, and password.#modalAuth: Login / Register / 1-click Quick Persona switcher (alice,bob,charlie,admin).
Part 3: Client JavaScript Logic (<script> block, lines ~3380 to 5500)
- State Store:
currentUser,allTickets,allUsers,allErrors,errorStatscurrentSection:'tickets'|'errors'currentScope:'assigned'|'reported'|'all'currentView:'kanban'|'table'currentErrView:'table'|'cards'activeTicketId,activeErrorId,currentEscalateErrorId
- Core Functions:
switchSection(section): Switches top-level view between Tickets & Errors.refreshData(): Polls server every 8s for live tickets, stats, error telemetry, and notifications.renderCurrentView(): Routes rendering torenderKanban()orrenderTable().loadErrors()&renderErrors(): RendersrenderErrorTable()orrenderErrorCards().openDrawer(ticketId)&openErrorDrawer(errorId): Populates and opens slide-over inspection drawers.openLinkedErrorFromTicket()&openLinkedTicketFromError(): Bilateral navigation between tickets and errors.handleCreateTicketSubmit(),handleHoldSubmit(),handleCompleteSubmit().handleReportErrorSubmit(),handleEscalateErrorSubmit(),updateErrorStatus().uploadAndAttachToDrawer(),submitDrawerAddLink(),submitDrawerRemark().copyStackTrace(),copyPayload(),copyExceptionName().
4. Key Functional Features
👤 Role-Based Workspaces & User Profiles
Khira supports four engineering roles with profile-scoped access control:
- 👩💻 Frontend Dev (e.g., Alice Sharma)
- 👨💻 Backend Dev (e.g., Bob Anderson)
- 🕵️♂️ Tester / QA (e.g., Charlie Patel)
- ⚡ Team Lead / Admin (e.g., System Administrator)
Profile-Scoped Rules:
- When creating a ticket, the Reporter is automatically locked to the authenticated user.
- Any user can assign tickets to any teammate across roles.
- Users can edit their own profile (name, avatar, role, password), but cannot modify other members' private credentials.
- Workload stats dynamically reflect the authenticated user's assigned active tasks vs on-hold vs completed.
📋 Ticket Management Lifecycle & Dual Ticket Types
Khira provides native support for two distinct ticket classifications, each with its own specialized form and layout:
flowchart TD
CREATE[Create New Ticket] --> TYPE_SELECT{Select Ticket Type}
TYPE_SELECT -->|🚀 Application Ticket| APP_FORM[Application Form]
APP_FORM --> APP_FIELDS["App Name, Version, Feature Name<br>API Key / Endpoint, Issue Type"]
TYPE_SELECT -->|⚙️ General Ticket| GEN_FORM[General Form]
GEN_FORM --> GEN_FIELDS["Domain / Category Dropdown<br>Department / Scope Quick Chips<br>Action Needed & Technical Specs"]
APP_FIELDS --> SUBMIT[Submit & Assign]
GEN_FIELDS --> SUBMIT
-
🚀 Application Tickets:
- Best for application bugs, UI glitches, backend 500/400 errors, schema mismatches, and specific feature performance.
- Form Fields: App Name (dropdown), Version, Feature Name, API Key / Endpoint, Issue Type, Priority, Description, Assistance Required, cURL / Diagnostic Context.
- Display: Marked with the cyan
🚀 Apppill and app name tag.
-
⚙️ General Tickets:
- Best for cross-cutting non-app engineering tasks, including DevOps & Cloud Infrastructure, Database & Storage provisioning, IAM Access & Permissions, Design & UX assets, Internal Tooling, and IT Support.
- Form Fields: General Category / Domain (dropdown), Department / Scope (with 1-click quick chips like Core Infra, Cloud Ops, Security, Design, Data Ops), Priority, Description, Action Needed / Deliverable, Technical Specifications / Instructions.
- Display: Marked with the violet
⚙️ Generalpill and category/department scope tags.
-
On Hold Workflow:
- Work cannot be paused silently. Putting a ticket on hold requires entering a Hold Reason (e.g., Blocked on NVIDIA A100 GPU node provisioning).
- A warning banner is displayed on the ticket card and inside the detail drawer.
-
Completion & Resolution:
- Marking completed requires entering Resolution Remarks (e.g., Reconciled parameter defaults in data.json, verified live).
-
Interactive Timeline & Remarks:
- Team members can append remarks, upload additional screenshots, and attach clickable URLs at any time.
🚨 Application Error Tracking & Telemetry Suite
The Error Tracking section (/khira/ -> Error Tracking) provides complete crash observability and resolution management:
- Fingerprint Deduplication:
- Telemetry reports are fingerprinted using a hash of
AppName + ExceptionType + Message. - Repeated exceptions in high-volume services do not spam the backlog with duplicate rows; instead, the Occurrences count increments (e.g.
🔥 42 events) and theLastSeentimestamp updates automatically.
- Telemetry reports are fingerprinted using a hash of
- Error Severities:
critical(P0) — Blocker / Crash / OOMhigh(P1) — Major Feature Failuremedium(P2) — Non-fatal degradation / Schema mismatchlow(P3) — Minor layout glitch / Warning
- Error Statuses:
unresolved— Newly ingested, awaiting triageinvestigating— Assigned to developer or under active debuggingresolved— Verified fixed with audit notesignored— Muted / Known acceptable behavior
- Diagnostic Inspection:
- Stack Trace Viewer: Monospace dark container with PyTorch, Python, or JavaScript tracebacks.
- Ingress Request Payload: Formatted JSON request parameters causing the exception.
- 1-Click Copy Buttons: Quickly copy stack trace, request body, or exception name to clipboard.
- ⚡ 1-Click Escalation to Developer Ticket:
- Clicking "Convert to Developer Ticket" pre-populates a new ticket with:
- Title:
[AppName] ExceptionType: Message - Priority: Synced from error severity
- Description: Telemetry metadata table
- Additional Info: Full formatted stack trace and ingress JSON payload
- Bilateral link: Sets
linked_error_idon the ticket andlinked_ticket_idon the error. - Automatically updates error status to
investigating. - Delivers an instant notification to the assigned developer.
- Title:
- Clicking "Convert to Developer Ticket" pre-populates a new ticket with:
🔔 Browser Desktop Push & In-App Notifications
- HTML5 Web Notifications API: Integrates with modern desktop browsers (Chrome, Edge, Firefox).
- Desktop Alerts: Triggers notifications for:
- New ticket assignment
- Escalated runtime error assignment
- Ticket placed on hold
- Ticket completed
- In-App Notification Center:
- Bell icon with unread indicator badge.
- Dropdown listing recent activities with timestamps.
- "Mark all read" action.
5. REST API Reference
All Khira endpoints are mounted under http://localhost:10000/khira/api/.
Authentication & Users
| Method | Endpoint | Description | Auth Header |
|---|---|---|---|
POST |
/khira/api/auth/register |
Register new user profile | None |
POST |
/khira/api/auth/login |
Sign in with username & password | None |
POST |
/khira/api/auth/logout |
Sign out and clear session cookie | None |
GET |
/khira/api/auth/me |
Fetch authenticated user profile | Optional X-Khira-User |
PUT |
/khira/api/auth/profile |
Update name, role, avatar, password | X-Khira-User: <username> |
GET |
/khira/api/users |
List all team developers | None |
Tickets & Backlog
| Method | Endpoint | Description | Auth Header |
|---|---|---|---|
GET |
/khira/api/tickets |
List tickets (supports ?type=general|application&status=&priority=&role=&q=) |
X-Khira-User: <username> |
POST |
/khira/api/tickets |
Create a new ticket (supports Application & General ticket payloads) | X-Khira-User: <username> |
GET |
/khira/api/tickets/{id} |
Get ticket details | None |
POST |
/khira/api/tickets/{id}/remarks |
Post a remark/comment | X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/hold |
Put ticket on hold ({ "reason": "..." }) |
X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/resume |
Resume ticket to in progress | X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/complete |
Mark completed ({ "remarks": "..." }) |
X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/priority |
Update ticket priority | X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/reassign |
Reassign ticket to developer | X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/links |
Add reference URL link | X-Khira-User: <username> |
POST |
/khira/api/tickets/{id}/attachments |
Attach an uploaded file metadata | X-Khira-User: <username> |
POST |
/khira/api/upload |
Multipart file upload (images, logs, txt) | None |
Error Telemetry & Ingestion
| Method | Endpoint | Description | Auth Header |
|---|---|---|---|
GET |
/khira/api/errors |
List errors (?status=&severity=&app=&q=) |
Optional X-Khira-User |
POST |
/khira/api/errors |
Ingest runtime error telemetry | Optional X-Khira-User |
GET |
/khira/api/errors/stats |
Aggregate telemetry metric counters | None |
GET |
/khira/api/errors/{id} |
Inspect error telemetry detail | None |
PUT |
/khira/api/errors/{id}/status |
Update status (investigating, resolved, ignored) |
X-Khira-User: <username> |
POST |
/khira/api/errors/{id}/escalate |
Escalate error into a developer ticket | X-Khira-User: <username> |
6. How External AI Agents Should Edit the Frontend
If you want an external AI agent to customize or add features to Khira's frontend, provide it with the following instructions:
- Target File:
Provide the agent directly with
web/khira/index.html. - Adding CSS Styling:
Place new styles inside the
<style>block before line/* Responsive Breakpoints */(~line 2080). Always use CSS variables (var(--bg-surface),var(--brand-primary),var(--border-subtle)) to preserve the light enterprise aesthetic. - Adding HTML Components:
- For ticket views: Insert elements inside
<div id="sectionTickets">. - For error telemetry views: Insert elements inside
<div id="sectionErrors">. - For modals: Add
.modal-overlaycards before the closing</body>tag.
- For ticket views: Insert elements inside
- Modifying Client-Side Logic:
- Access state through
currentUser,allTickets,allErrors,errorStats. - After updating or creating resources via
fetch(), callawait refreshData()to automatically update metric cards, badges, and active views. - Use
showToast(msg, isError)for user feedback.
- Access state through
- No Bundler Step Needed:
Because
web/khira/index.htmlis served statically by the Go gateway, any changes saved toweb/khira/index.htmltake effect immediately upon browser reload (Ctrl+Shift+R or F5). No compile step or daemon restart is required for frontend-only edits.