Files

300 lines
18 KiB
Markdown

# 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.
```mermaid
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`**<br>`/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`**<br>`/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`**<br>`/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:
```mermaid
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`](file:///home/creserver/Desktop/Vaishno_workspace/Unified_Dashboard_Suite_Go/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.