Files

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.html is 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 modify web/khira/index.html directly without needing to run npm build or 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).
  • 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)

  1. <header class="app-header">:
    • Brand logo + API Docs link
    • Primary Switcher (#tabNavTickets vs #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 (#btnHeaderActionTicket vs #btnHeaderActionError)
  2. <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.
  3. 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.
  4. 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, errorStats
    • currentSection: '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 to renderKanban() or renderTable().
    • loadErrors() & renderErrors(): Renders renderErrorTable() or renderErrorCards().
    • 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
  1. 🚀 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 🚀 App pill and app name tag.
  2. ⚙️ 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 ⚙️ General pill and category/department scope tags.
  3. 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.
  4. Completion & Resolution:

    • Marking completed requires entering Resolution Remarks (e.g., Reconciled parameter defaults in data.json, verified live).
  5. 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:

  1. 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 the LastSeen timestamp updates automatically.
  2. Error Severities:
    • critical (P0) — Blocker / Crash / OOM
    • high (P1) — Major Feature Failure
    • medium (P2) — Non-fatal degradation / Schema mismatch
    • low (P3) — Minor layout glitch / Warning
  3. Error Statuses:
    • unresolved — Newly ingested, awaiting triage
    • investigating — Assigned to developer or under active debugging
    • resolved — Verified fixed with audit notes
    • ignored — Muted / Known acceptable behavior
  4. 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.
  5. ⚡ 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_id on the ticket and linked_ticket_id on the error.
      • Automatically updates error status to investigating.
      • Delivers an instant notification to the assigned developer.

🔔 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:

  1. Target File: Provide the agent directly with web/khira/index.html.
  2. 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.
  3. 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-overlay cards before the closing </body> tag.
  4. Modifying Client-Side Logic:
    • Access state through currentUser, allTickets, allErrors, errorStats.
    • After updating or creating resources via fetch(), call await refreshData() to automatically update metric cards, badges, and active views.
    • Use showToast(msg, isError) for user feedback.
  5. No Bundler Step Needed: Because web/khira/index.html is served statically by the Go gateway, any changes saved to web/khira/index.html take effect immediately upon browser reload (Ctrl+Shift+R or F5). No compile step or daemon restart is required for frontend-only edits.