Kulcare Connect - Product Documentation

OverviewCopy Anchor Link

Kulcare Connect is a FREE professional hub for healthcare practitioners to manage their digital identity, stay connected, and grow professionally. It serves all types of healthcare professionals including doctors, nurses, therapists, physiotherapists, dentists, dietitians, and more.

Core PurposeCopy Anchor Link

"A unified professional hub for healthcare practitioners to manage their digital identity, stay connected, and grow professionally"

Key FeaturesCopy Anchor Link

1. Multi-Clinic SupportCopy Anchor Link

• Aggregate View: See combined data across all clinics (default)
• Clinic-Specific View: Filter to individual clinic data
• Smart Clinic Selection: Automatic selection for single-clinic practitioners
• Clinic Context Management: Remember last selected clinic per feature

2. Professional Profile ManagementCopy Anchor Link

• Multi-practitioner type support with icon-based differentiation
• Verification badges by regulatory body
• Public profile for patient discovery
• SEO-optimized profiles
• Multi-language support
• Multiple clinic affiliations

3. Unified Communication CenterCopy Anchor Link

• Unified Inbox: All messages across all clinics
• Clinic Indicators: See which clinic each message relates to
• Notification Management: Aggregate and clinic-specific notifications
• CMS Integration: Appointment notifications and patient messages
• Referral Communications: Professional network messages

4. Discovery & VisibilityCopy Anchor Link

• Patient-facing search with comprehensive filters
• Profile analytics (views, searches, bookings)
• SEO optimization for better discoverability
• Aggregate statistics across all clinics

5. Professional Development HubCopy Anchor Link

• CME Integration: Course discovery and tracking from external sources
• Medical News Feed: Personalized by specialty and interests
• Alumni Network: Connect with colleagues from training programs
• Certificate Management: Store and track professional certifications

6. Schedule ViewerCopy Anchor Link

• Multi-Clinic Calendar: Combined view of all appointments
• Color-Coded Display: Visual differentiation by clinic
• Read-Only Access: View schedules from CMS
• Quick Actions: Deep links to CMS for management
• Availability Display: Show open slots to patients

7. Referral NetworkCopy Anchor Link

• Build professional connections
• Send and receive referrals across clinics (cross-tenant)
• Track referral patterns
• Professional recommendations
• Rich referral data: patient info, notes, status timestamps (accepted_at, completed_at)
• Self-referral prevention: model validation + recipient picker exclusion
• CMS integration: PatientPicker for patient selection, "Refer" button on patient detail, referrals in sidebar
• Security: status transitions gated by dedicated endpoints (not PATCHable), patient ID immutable after create, RequireAccess on all CMS routes

8. Staff work profileCopy Anchor Link

• A staff member gets a work profile that moves with them between facilities: bio, languages, qualifications, years of experience and work history.
• Work history shows the Kulcare roles with "Verified by Kulcare", then the jobs the person added.
• Admins and colleagues at the person's current practices see it. The facility page lists "People at your practices" for a colleague.
• The person can share it by link (7, 30 or 90 days, or no expiry). Patients and Connect search never see it.
• Pages: StaffProfilePage (own profile), the staff view of PeerProfilePage, and SharedProfilePage at /connect/shared/:token.

9. One bioCopy Anchor Link

• The bio of the Identity record is the only bio, for practitioners, vendors and staff. Onboarding, My profile, the colleague view and the patient app read and write it. The limit is 5000 characters in every form.

10. Vendor practiceCopy Anchor Link

• Words from the category. The vendor's service category gives the word for an offering: Classes (education), Sessions (fitness), Visits (home care), Meal plans (meals), and Services for the others. offeringWord.ts and vendorCategories.ts in shared-services hold the map and the category list. The backend sends the same offering_word.
• Offerings of four kinds: 1:1 session, group class, home visits and meal plan. The editor shows only the fields of the kind. A sold offering keeps its price, currency, duration and kind; the vendor duplicates it to change them.
• Clients: a table with search, sort and pages. The vendor adds a client by hand or by CSV import, and sends a booking link by copy or SMS. Client detail shows contact details, private notes, and one section for each kind the vendor sells.
• Class schedule: batches with a pattern of dates, seats, a waitlist and a clash preview. Sessions show on Schedule.
• Visit schedule: visits that repeat at the client's home. A paid request waits for the vendor to confirm or decline it within 72 hours. Care notes show on client detail and on each visit in Schedule. The client reads them in the patient app.
• Deliveries: the day's meal deliveries, with print.
• Refund requests: a card on the Payments page. The vendor approves or rejects with a note. The approve dialog says when the refund is full and ends the service.
• Sidebar: the offering word, then "Class schedule", "Visit schedule" or "Deliveries" when the vendor has that kind of offering, then Clients and Schedule. No two entries have the same label.
• Onboarding: the vendor picks a category on the About step, and the Offerings step starts with the category's default kind.

The patient app gets the same features: the booking link landing page, batch detail with a seat hold countdown, My classes, the visit plan request form, My visits, care notes, the meal plan order form, My meal plans, and "Request a refund" on each paid vendor order.

Technical ArchitectureCopy Anchor Link

Multi-Clinic Data FlowCopy Anchor Link

Connect App
    ├── Aggregate Mode (Default)
    │   ├── Combines data from all clinics
    │   ├── Shows unified metrics
    │   └── Single inbox for all messages
    │
    └── Clinic-Specific Mode
        ├── Filters to selected clinic
        ├── Clinic-specific metrics
        └── Filtered communications

CMS IntegrationCopy Anchor Link

When navigating from Connect to CMS:

1. System checks if action requires clinic context
2. For single clinic → Auto-selects and proceeds
3. For multiple clinics → Shows clinic selector modal
4. User selects clinic → System passes context to CMS
5. Context maintained for session duration

Deep Linking FlowCopy Anchor Link

// Example deep link handling
connectApp.handleDeepLink('/cms/patient/123') => {
  1. Check clinic context requirement
  2. If multiple clinics: Show selector
  3. User selects: Store selection
  4. Navigate to CMS with clinic ID
}

Design SystemCopy Anchor Link

Practitioner Type IndicatorsCopy Anchor Link

Using icon-based differentiation (no custom colors):

• 🩺 Doctor (Stethoscope icon)
• 💉 Nurse (Heart icon)
• 🧠 Therapist (Brain icon)
• 💪 Physiotherapist (Activity icon)
• 🦷 Dentist (Smile icon)
• 🥗 Dietitian (Apple icon)
• 🔬 Lab Technician (Microscope icon)
• 💊 Pharmacist (Pill icon)

Clinic DifferentiationCopy Anchor Link

Using existing chart colors from Kulcare design system:

• Chart colors 1-5 for visual differentiation
• Subtle left borders in calendars
• Clinic logos in selectors and badges

User FlowsCopy Anchor Link

Daily WorkflowCopy Anchor Link

1. Morning

   • Open app → See aggregate dashboard
   • Check unified inbox for all clinics
   • Review combined schedule

2. During Day

   • Click appointment → Auto-switch to clinic context
   • Access CMS → Maintain clinic selection
   • Return to Connect → Remember context

3. Evening

   • Review aggregate analytics
   • Check professional development content
   • Update availability across clinics

First-Time SetupCopy Anchor Link

1. Create professional profile
2. Add first clinic affiliation
3. Add additional clinics (if applicable)
4. Set primary clinic
5. Configure availability per clinic
6. Dashboard shows aggregate view

API EndpointsCopy Anchor Link

Multi-Clinic Aware EndpointsCopy Anchor Link

GET  /api/v1/connect/practitioners/profile
GET  /api/v1/connect/practitioners/clinics
GET  /api/v1/connect/practitioners/clinics/:id/schedule
GET  /api/v1/connect/practitioners/aggregate/schedule
GET  /api/v1/connect/practitioners/aggregate/inbox
GET  /api/v1/connect/practitioners/aggregate/analytics
POST /api/v1/connect/practitioners/clinic/:id/deeplink

Implementation StatusCopy Anchor Link

Phase 1: Foundation (Week 1) ✅Copy Anchor Link

• Project structure created
• Multi-clinic architecture planned
• Shell integration pending
• Basic routing setup

Phase 2: Profile & Discovery (Week 2) 🚧Copy Anchor Link

• Multi-clinic profile management
• Practitioner type system
• Search and discovery

Phase 3: Communication Hub (Week 3) ⏳Copy Anchor Link

• Unified inbox
• Notification system
• CMS integration

Phase 4: Schedule & Analytics (Week 4) ⏳Copy Anchor Link

• Multi-clinic schedule
• Aggregate analytics
• Comparison charts

Phase 5: CMS Integration (Week 5) ⏳Copy Anchor Link

• Deep linking system
• Data synchronization
• Context management

Phase 6: Professional Features (Week 6) 🚧Copy Anchor Link

• CME hub
• News feed
• Alumni network
• Referral system (core flow shipped: create → receive → accept/decline/complete/cancel; CMS PatientPicker + Connect inbox; PRs #1295, #1314, #1544)

Success MetricsCopy Anchor Link

Target MetricsCopy Anchor Link

• User Acquisition: 100K practitioners in 6 months
• Daily Active Users: 40% of registered users
• Profile Completion: >70% within first week
• CMS Conversion: 15% trial activation, 8% paid conversion

Technical MetricsCopy Anchor Link

• Page load time < 2 seconds
• 99.9% uptime
• API response time < 100ms
• Mobile-first responsive design

Security & ComplianceCopy Anchor Link

• HIPAA compliance for health data
• Multi-factor authentication support
• Role-based access per clinic
• Audit logging with clinic context
• Data encryption at rest and transit

Future EnhancementsCopy Anchor Link

Planned FeaturesCopy Anchor Link

• Job board integration
• Telemedicine support
• AI-powered content recommendations
• Advanced analytics and insights
• Mobile native apps (iOS/Android)

Integration OpportunitiesCopy Anchor Link

• Electronic Health Records (EHR)
• Insurance verification systems
• Payment processing
• Prescription management
• Lab result integration

Support & ResourcesCopy Anchor Link

• Documentation: This document and inline code documentation
• API Reference: /docs/api/connect-endpoints.md
• Design System: /docs/design-system/
• Support: Contact development team

Last Updated: [Current Date] Version: 1.0.0