Heliconia - Helpdesk Platform

Status: ✅ Initial Setup Complete

Location: Service & Support Management/react-heliconia/

Port: 9295 (Vite dev server)

🎯 Platform Objective

Build a Helpdesk Platform (Heliconia) for Service & Support Management. This platform enables IT support teams to manage support tickets, track SLAs, manage agent assignments, and generate reports.

Tier: Pro / Enterprise
Target Market: IT Support Teams
Key Capabilities:

🎫 Ticket Management - Create, view, update, and close support tickets
📋 Queue Management - Manage ticket queues and assignments
⏱️ SLA Tracking - Monitor Service Level Agreements and compliance
📚 Service Catalog - Browse available services and service categories
👥 Agent Management - Manage support staff and their workload
📊 Reports & Analytics - Generate helpdesk analytics and KPI reports
⚙️ Platform Settings - Configure system settings and integrations

📐 Architecture Alignment

Federated Capability Model

Heliconia operates under the Federated Capability Charter, ensuring:

✅ Read Everywhere, Write at Source - Integrates with other platforms via APIs
✅ API-first Integration - All cross-platform communication through documented contracts
✅ Single System of Record - Respects ownership boundaries from other platforms
✅ Auditability - All changes are traceable and auditable

Key Integrations

🔔 Notification Service (python-notification-service-fastapi, port 8700) - For alerts and notifications
✓ Todo Service (python-todo-service-fastapi, port 8650) - For task tracking
🔍 Knowledge Platform (Salvia, port 5177) - For knowledge base lookup (read-only)
📊 Observability (Salix, port 5180) - For logging and monitoring

🏗️ Project Structure

react-heliconia/
├── src/
│   ├── modules/
│   │   ├── core-shell/                 # App layout, navigation, settings
│   │   │   ├── components/
│   │   │   │   ├── AppLayout.tsx       # Main app container
│   │   │   │   ├── Sidebar.tsx         # Navigation (8 modules)
│   │   │   │   ├── Topbar.tsx          # Header with notifications & user menu
│   │   │   │   ├── AppLauncher.tsx     # App switcher  
│   │   │   │   └── TodoListPanel.tsx   # Todo widget
│   │   │   └── pages/
│   │   │       └── PlatformSettingsPage.tsx  # Settings UI
│   │   │
│   │   ├── dashboard/                  # Landing page (read-only overview)
│   │   │   ├── pages/
│   │   │   │   └── DashboardPage.tsx   # Helpdesk metrics & SLA tracking
│   │   │   └── store/
│   │   │       └── dashboardStore.ts
│   │   │
│   │   ├── tickets/                    # Placeholder: Ticket management (coming soon)
│   │   ├── queue/                      # Placeholder: Queue management (coming soon)
│   │   ├── sla/                        # Placeholder: SLA policies (coming soon)
│   │   ├── catalog/                    # Placeholder: Service catalog (coming soon)
│   │   ├── agents/                     # Placeholder: Agent management (coming soon)
│   │   └── reports/                    # Placeholder: Analytics (coming soon)
│   │
│   ├── pages/
│   │   ├── Login.tsx                   # Public login page
│   │   └── Profile.tsx                 # User profile page
│   │
│   ├── auth/
│   │   ├── authService.ts              # Demo auth (3 users)
│   │   └── ProtectedRoute.tsx           # Route protection
│   │
│   ├── lib/
│   │   ├── api/
│   │   │   ├── notificationApi.ts      # Notification service client
│   │   │   └── todoApi.ts               # Todo service client
│   │   ├── utils.ts                    # Common utilities
│   │   ├── rum.ts                      # RUM configuration
│   │   └── tracing.ts                  # OTEL tracing setup
│   │
│   ├── components/
│   │   ├── layout/                     # Layout components
│   │   ├── settings/                   # Theme settings UI
│   │   └── ui/                         # Reusable UI components (card, button, input, etc.)
│   │
│   ├── stores/
│   │   ├── theme-store.ts              # Theme preferences
│   │   ├── preferences-store.ts        # User preferences
│   │   └── settings-panel-store.ts     # Settings panel state
│   │
│   ├── hooks/                          # Custom React hooks
│   ├── assets/                         # Images, icons
│   │
│   ├── App.tsx                         # Main app routing
│   ├── main.tsx                        # Entry point
│   └── index.css                       # Global styles (Tailwind)
│
├── public/
│   └── images/                        # Logo, icons
│
├── vite.config.ts                     # Vite configuration (port 9295)
├── tsconfig.json                      # TypeScript config
├── tailwind.config.js                 # Tailwind CSS config
├── package.json                       # Dependencies
├── package-lock.json
└── README.md                          # This file

🚀 Getting Started

Prerequisites

Node.js 18+ (with npm)
Running services:
- Notification Service (port 8700)
- Todo Service (port 8650)

Installation

cd 'Service & Support Management/react-heliconia'
npm install --legacy-peer-deps

Development Server

npm run dev
# App runs at http://localhost:9295

Demo Credentials

Use any of these test accounts:

Email	Password	Role
`admin@heliconia.local`	`admin`	Admin
`reviewer@heliconia.local`	`reviewer`	Reviewer
`member@heliconia.local`	`member`	Member

Build for Production

npm run build
npm run preview

📋 Navigation Structure

Main Navigation (Sidebar)

Dashboard (/) - Landing page overview
Tickets (/tickets) - Support ticket management
Queue (/queue) - Queue & inbox management
SLA (/sla) - SLA policies and monitoring
Catalog (/catalog) - Service catalog
Agents (/agents) - Support agent management
Reports (/reports) - Analytics & reporting
Settings (/settings) - Platform settings

Secondary Routes

/login - Public login page
/profile - User account settings

🎨 UI/UX Foundation

Heliconia uses the same design system as Sequoia:

Design Language: Modern, clean "glass" design with frosted glass cards
Color System: Accent color presets (gradient, cosmic, indigo, steel, granite)
Components Library: Shadcn/ui + Lucide icons
Theme Support: Light/Dark modes
Responsive: Mobile-first, works on all screen sizes

Customization

Accent color selection in Settings → Environment
Theme toggle (light/dark) in Topbar
Density options for compact viewing

🔐 Authentication & Security

Current: Demo authentication (localStorage-based)

User sessions stored locally
3 demo accounts for development
Protected routes via <ProtectedRoute> wrapper

Future: Integrate with enterprise IAM

OAuth 2.0 / SAML 2.0
Multi-factor authentication
RBAC (Role-Based Access Control)

📦 Key Dependencies

Package	Version	Purpose
react	^19.2.0	UI framework
react-router-dom	^7.12.0	Routing
@tanstack/react-query	^5.90.17	Data fetching & caching
zustand	^5.0.10	State management
tailwindcss	^3.4.0	Styling
shadcn/ui	Latest	Component library
lucide-react	^0.562.0	Icons
recharts	^3.6.0	Charts & graphs
vite	^7.2.4	Build tool
typescript	~5.9.3	Type safety

🔧 Development Guidelines

Module Structure

Each module has its own folder under src/modules/
Modules contain:
- index.ts - Public exports
- pages/ - Page-level components
- components/ - Module-specific components
- store/ - Zustand store for module state (optional)
- README.md - Module documentation

Styling

Tailwind CSS for all styling
CSS Variables for themes (in index.css)
Utility classes over custom CSS

State Management

Zustand stores for global & module state
URL params for navigation state
React Query for server state

API Integration

Services in lib/api/
One hook per API resource
Error handling with toast notifications

🧪 Testing & Quality

npm run lint        # ESLint
npm run build       # TypeScript check + Vite build
npm run preview     # Preview production build

📚 Documentation Standards

Code comments for non-obvious logic
JSDoc for functions and exports
README.md in each module
Inline documentation for complex integrations

🔄 Integration Checklist

When implementing helpdesk modules, ensure:

Notifications integrated (app_id: 00000000-0000-0000-0000-000000000013)
Todo service connected (app_id: 00000000-0000-0000-0000-000000000013)
API contracts documented
Error handling implemented
Loading states visible
Toast notifications working
Accessible (WCAG baseline)
Mobile responsive

🚢 Deployment

Docker

FROM node:20-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --legacy-peer-deps
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

Environment Variables

VITE_NOTIFICATION_API_URL - Default: http://localhost:8700
VITE_TODO_API_URL - Default: http://localhost:8650
VITE_OTEL_SERVICE_NAME - Default: frontend-heliconia
VITE_REGISTRY_API_URL - Default: http://localhost:8405

📖 References

See the documentation directory for more details:

docs/architecture/ - Federated architecture, capability matrix
docs/mappings/ - API contracts and data models
docs/standards/ - Coding standards and conventions
docs/platforms/ - Platform-specific setup guides

✨ Next Steps

Implement Tickets Module - Core helpdesk functionality
- List view with filters and sorting
- Detail view with conversation history
- Create/edit forms with validation
- Status workflow (Open → In Progress → Resolved → Closed)
Implement Queue Management - Ticket assignment
- Queue list by priority/category
- Drag-drop assignment to agents
- Auto-assignment based on skills/capacity
Implement SLA Tracking - Compliance monitoring
- SLA policy definitions
- Real-time compliance dashboard
- SLA breach alerts
Implement Service Catalog - Self-service interface
- Category browser
- Service request templates
- Linked helpdesk category selection
Implement Agent Management - Staff administration
- Agent list with skills/availability
- Workload balancing
- Performance metrics
Implement Reports - Analytics & KPIs
- Dashboard with key metrics
- Report builder
- Export functionality

🐛 Troubleshooting

Port Already in Use

# Change port in vite.config.ts if 9295 is in use
# DEV ONLY: set strictPort to false temporarily

Build Errors

# Clear cache and reinstall
rm -rf node_modules dist
npm install --legacy-peer-deps
npm run build

Import Errors

# Ensure all aliases are configured in vite.config.ts
# Check @/ path mapping points to src/

📝 License

Part of Adira Platform suite.

Last Updated: April 1, 2026
Maintained By: Platform Engineering Team
Related Platforms: Sequoia, Laurus, Salvia, Salix, Tilia

Name		Name	Last commit message	Last commit date
public		public
src		src
.gitignore		.gitignore
README.md		README.md
build.bat		build.bat
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation