GOD-EYE Event Contracts

Standardized event schemas and stream definitions for 8Medical microservices architecture.

🎉 Latest Update: v1.0.11 - COMPLETE STANDARDIZATION ACHIEVED

✅ ZERO legacy code or hardcoded strings remaining ✅ ALL services use standardized constants ✅ Event flow mismatches completely resolved ✅ Clean, maintainable folder structure ✅ 100% type safety with TypeScript

🏗️ Architecture

This package provides a unified event-driven communication contract for all microservices in the GOD-EYE Healthcare Platform.

📁 Project Structure

@kenniy/godeye-event-contracts/
src/
├── consumers/           # Consumer group definitions
│   └── index.ts        # ConsumerGroups, ConsumerGroupName type
├── events/             # Service-specific event schemas
│   ├── user-service/
│   │   ├── index.ts    # UserServiceEvents
│   │   └── registration.ts
│   ├── hrm-service/
│   │   └── index.ts    # HrmServiceEvents
│   ├── file-notification-service/
│   │   └── index.ts    # NotificationServiceEventTypes
│   └── system/
│       └── index.ts    # SystemEventTypes
├── schemas/            # Base event interfaces
│   └── base-event.ts   # BaseEvent, EventEnvelope, etc.
├── services/           # Service name constants
│   └── index.ts        # ServiceNames, ServiceName type
├── streams/            # Stream definitions
│   └── index.ts        # EventStreams, EventStreamName type
├── config/             # Configuration mappings
│   ├── index.ts        # Barrel file
│   ├── consumer-group-streams.ts
│   └── service-consumer-recommendations.ts
└── index.ts            # Main barrel file

🚀 Installation

npm install @kenniy/godeye-event-contracts

📖 Usage

Basic Event Publishing

import {
  EventStreams,
  UserServiceEvents,
  ServiceNames
} from '@kenniy/godeye-event-contracts';

// Publish a business registration event
await eventPublisher.publish(
  EventStreams.USER_SERVICE_EVENTS,
  UserServiceEvents.BUSINESS_REGISTERED,
  {
    businessId: '123',
    businessName: 'Medical Center',
    email: '[email protected]'
  }
);

Event Consumption

import {
  EventStreams,
  UserServiceEvents,
  ConsumerGroups
} from '@kenniy/godeye-event-contracts';

// Listen for business registration events
consumer.subscribe(
  EventStreams.USER_SERVICE_EVENTS,
  ConsumerGroups.EMAIL_PROCESSORS,
  (event) => {
    if (event.eventType === UserServiceEvents.BUSINESS_REGISTERED) {
      // Send welcome email
      console.log(`Welcome ${event.data.businessName}!`);
    }
  }
);

Consumer Group Configuration

import {
  ConsumerGroups,
  getConsumerGroupStreams,
  getServiceConsumerGroups
} from '@kenniy/godeye-event-contracts';

// Get recommended consumer groups for a service
const groups = getServiceConsumerGroups(ServiceNames.FILE_NOTIFICATION_SERVICE);
// Returns: [ConsumerGroups.EMAIL_PROCESSORS, ConsumerGroups.SMS_PROCESSORS, ...]

// Get streams for a consumer group
const streams = getConsumerGroupStreams(ConsumerGroups.EMAIL_PROCESSORS);
// Returns: [EventStreams.USER_SERVICE_EVENTS, EventStreams.HRM_SERVICE_EVENTS, ...]

🎯 Event Types by Service

User Service Events

• CUSTOMER_REGISTERED - New customer registration
• BUSINESS_REGISTERED - New business registration
• ADMIN_CREATED - Admin user creation
• CUSTOMER_LOGGED_IN/OUT - Authentication events
• EMAIL_VERIFIED - Email verification completion
• PASSWORD_RESET_REQUESTED - Password reset requests

HRM Service Events

• HOSPITAL_REGISTERED - Hospital registration
• BED_ALLOCATED/RELEASED - Bed management
• STAFF_ASSIGNED - Staff assignments
• EMERGENCY_ALERT - Emergency notifications

File+Notification Service Events

• EMAIL_SENT/FAILED/DELIVERED - Email delivery tracking
• SMS_SENT/FAILED/DELIVERED - SMS delivery tracking
• FILE_UPLOADED/PROCESSED - File processing events

System Events

• SERVICE_WELCOME - Service startup announcements
• SERVICE_HEARTBEAT - Health check events

🔄 Event Streams

• USER_SERVICE_EVENTS - User registration, authentication
• HRM_SERVICE_EVENTS - Hospital resource management
• NOTIFICATION_SERVICE_EVENTS - Email/SMS delivery
• BUSINESS_VERIFICATION_EVENTS - Business verification workflow
• SERVICE_HEALTH_EVENTS - System monitoring

👥 Consumer Groups

• EMAIL_PROCESSORS - Email notification handling
• SMS_PROCESSORS - SMS notification handling
• HRM_PROCESSORS - Hospital business logic
• ANALYTICS_PROCESSORS - Data analytics and reporting
• AUDIT_PROCESSORS - Compliance and security logging

🏥 Service Names

• USER_SERVICE - User management and authentication
• HRM_SERVICE - Hospital resource management
• FILE_NOTIFICATION_SERVICE - File processing and notifications
• PAYMENT_SERVICE - Payment processing
• TRANSPORT_SERVICE - Ambulance and logistics
• AGGREGATOR_SERVICE - Data aggregation
• GATEWAY_SERVICE - API gateway

📝 Type Safety

All events are fully typed with TypeScript interfaces:

import { BusinessRegisteredEvent, CustomerRegisteredEvent } from '@kenniy/godeye-event-contracts';

function handleBusinessRegistration(event: BusinessRegisteredEvent) {
  // event.data is fully typed
  console.log(`New business: ${event.data.businessName}`);
  console.log(`Contact: ${event.data.email}`);
}

🔧 Configuration

The package provides configuration helpers for setting up consumer groups and stream mappings:

import {
  ServiceConsumerRecommendations,
  ConsumerGroupStreams
} from '@kenniy/godeye-event-contracts';

// Get all recommended setups
const recommendations = ServiceConsumerRecommendations;
const streamMappings = ConsumerGroupStreams;

📊 Event Flow Examples

Business Registration Flow

1. User Service publishes UserServiceEvents.BUSINESS_REGISTERED
2. File+Notification Service consumes via ConsumerGroups.EMAIL_PROCESSORS
3. HRM Service consumes via ConsumerGroups.HRM_PROCESSORS
4. Welcome email sent + hospital profile created

Hospital Bed Management

1. HRM Service publishes HrmServiceEvents.BED_ALLOCATED
2. Analytics Service tracks via ConsumerGroups.ANALYTICS_PROCESSORS
3. Notification Service sends alerts via ConsumerGroups.SMS_PROCESSORS

🔄 Migration from Legacy

Before (Event Mismatches)

// File+Notification Service was importing:
import { UserServiceEventTypes } from '@kenniy/godeye-event-contracts'; // ❌ DIDN'T EXIST!

// Causing events to be lost between services

After (Fixed)

// Now correctly imports:
import { UserServiceEvents } from '@kenniy/godeye-event-contracts'; // ✅ WORKS!

// Events flow correctly: User Service → File+Notification Service

🚦 Version History

• v1.0.11 - Complete standardization with clean folder structure
• v1.0.10 - Added missing event types and fixed import mismatches
• v1.0.9 - Event flow mapping and mismatch resolution
• v1.0.8 - Consumer group reorganization
• v1.0.7 - Stream standardization
• v1.0.6 - Initial standardized contracts

🛠️ Development

# Clone and setup
git clone https://github.com/keniiy/event-contracts.git
cd event-contracts
npm install

# Build
npm run build

# Watch mode
npm run dev

# Publish (maintainers only)
npm run prepublishOnly
npm publish

🔗 Related Packages

This package is part of the GOD-EYE Healthcare Platform:

• @kenniy/godeye-user-service
• @kenniy/godeye-hrm-service
• @kenniy/godeye-file-notification-service

📄 License

Private package for 8Medical GOD-EYE Healthcare Platform.

🆘 Support

• Issues: GitHub Issues
• Email: [email protected]

🎯 Complete Event Standardization Achieved

• ✅ Zero legacy code or naming inconsistencies
• ✅ All services use standardized event constants
• ✅ Event flows properly mapped end-to-end
• ✅ Type safety with full TypeScript support
• ✅ Clean, maintainable folder structure
• ✅ All import mismatches resolved
• ✅ Event communication working perfectly