🎯 What is Adit API?

• 🏗️ Microservices project - multiple small services instead of one big application
• 🔲 Each service handles one domain (Patient Service, Appointment Service, etc.)
• ⚡ Services communicate using gRPC (like REST API but faster and with contracts)
• 📚 We use Event Sourcing - storing all changes as events (like a history log)
• 🔄 CQRS = Separate models for reading and writing data

⚡ What is gRPC?

gRPC is a high-performance RPC (Remote Procedure Call) framework. Think of it as:

• 📦 Like REST but faster - Uses binary instead of JSON
• 📝 Contract-first - API is defined in .proto files
• 🔒 Type-safe - Generated code ensures type safety
• 🚀 Efficient - Smaller payloads, faster parsing

🔗 From Proto to TypeScript

// In your controller:
@GrpcMethod('PatientSrv', 'PatientDelete')  // Must match proto!
async patientDelete(payload: PatientDeleteRequest) {
  // payload will have: patientId, organizationId, deletedBy
}

📦 What is a "Task"?

A task represents one specific operation or endpoint in your service. For example:

• patient-create_task = Creating a new patient
• patient-update_task = Updating patient information
• patient-getbyid_task = Fetching a specific patient
• patient-delete_task = Deleting a patient

Each task is self-contained with its own business logic, data access, and API endpoint.

🎯 Key Principles

• 🚫 No framework dependencies - Pure TypeScript/JavaScript
• 📋 Business rules only - How a patient can be created, updated, deleted
• 📖 Self-documenting - The code explains the business

🎯 Key Principles

• 📦 Uses domain objects - Never duplicates business logic
• 🔧 Handles infrastructure - Database access, external services
• 🔄 Coordinates operations - Combines multiple domain operations

What Does @Adit Do?

The @Adit decorator registers your components with the framework so they can be:

• ✅ Found by dependency injection
• ✅ Connected to the right service
• ✅ Properly initialized

❌ WRONG - Missing @Adit

export class PatientDeleteTaskCommandHandler {
  // Handler won't be found!
}

✅ CORRECT - With @Adit

@Adit({
  srvName: AditService.SrvNames.PATIENT_SRV,
  type: 'RegisterCommandHandler',
})
export class PatientDeleteTaskCommandHandler {
  // Handler will work!
}

🎯 What We'll Build

• 📝 Proto file defining the API contract
• 🏗️ Domain model with business rules
• 💾 Repository for data access
• 🎮 Controller to handle gRPC requests
• ⚙️ Service to orchestrate operations
• 📦 Module to wire everything together

✅ At this point, you can:

• Start your service: npm run start:patient_srv:dev
• Call the PatientDelete endpoint
• See logs in console
• Business logic is enforced (can't delete twice)

Step 9 & 10: Create Command Structure

mkdir -p patient-delete_task/application/commands/imp
mkdir -p patient-delete_task/application/commands/handler

Create the Command

File: patient-delete_task/application/commands/imp/patient-delete.command.ts

import { ICommand } from '@adit/core/event';

export class PatientDeleteCommand implements ICommand {
  constructor(
    public readonly patientId: string,
    public readonly organizationId: string,
    public readonly deletedBy: string,
  ) {}
}

Steps 14-15: Create Event Structure & Event

mkdir -p patient-delete_task/domain/events/imp

File: patient-delete_task/domain/events/imp/patient-deleted.event.ts

import { Adit } from '@adit/decorators';
import { AditService } from '@adit/util';
import { Event, IEvent } from '@adit/core/event';

@Adit({
  srvName: AditService.SrvNames.PATIENT_SRV,
  type: 'RegisterEvent',
})
@Event('PATIENT_DELETED')
export class PatientDeletedEvent implements IEvent {
  constructor(
    public readonly data: {
      patientId: string;
      deletedBy: string;
      deletedAt: Date;
    }
  ) {}
}

📝 What happens now:

1. Controller receives request
2. Service validates and creates command
3. Command handler loads aggregate
4. Aggregate applies business rules and emits event
5. Event is automatically saved to event store
6. State is updated through event handler
7. Complete audit trail is maintained

📊 Simple Flow (After Phase 1)

┌──────────────┐     ┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Controller  │────▶│   Service   │────▶│  Repository  │────▶│   Domain    │
│  (gRPC)      │     │ (Validates) │     │ (Data Access)│     │ (Business)  │
└──────────────┘     └─────────────┘     └──────────────┘     └─────────────┘

🔄 Command Flow (After Phase 2)

┌──────────────┐     ┌─────────────┐     ┌─────────────┐
│  Controller  │────▶│   Service   │────▶│   Command   │
└──────────────┘     └─────────────┘     └─────────────┘
                                                │
                                                ▼
┌──────────────┐     ┌─────────────┐     ┌─────────────┐
│   Domain     │◀────│ Repository  │◀────│   Handler   │
└──────────────┘     └─────────────┘     └─────────────┘

📚 Event Sourcing Flow (After Phase 3)

┌──────────────┐     ┌─────────────┐
│   Domain     │────▶│    Event    │
│  (Aggregate) │     └─────────────┘
└──────────────┘            │
                            ▼
                    ┌─────────────┐
                    │ Event Store │
                    └─────────────┘

🎯 Why Testing is Important

• 🐛 Catches bugs early - Before they reach production
• 📖 Documents your code - Tests show how your code should work
• 🔄 Enables refactoring - Change code confidently when tests pass
• ✅ Required for all tasks - No feature is complete without tests

🎯 Production-Ready Patterns

• 🔐 Authentication & Security Architecture
• 🔗 Cross-Service Communication Security
• 📦 Package Management Best Practices
• 📚 Advanced Event Sourcing Patterns
• 🚀 Production Deployment Strategies
• ⚡ Performance Optimization
• 🧪 Testing Strategies for Production

🏗️ Architecture Principles

• ✅ Progressive Development - Start simple, evolve to complex
• 🎯 Domain-Driven Design - Business logic in aggregates
• 📚 Event Sourcing - Complete audit trail of all changes
• 🔄 CQRS Pattern - Separate commands from queries

🛠️ Implementation Guidelines

• 📁 Consistent folder structure - Always follow the pattern
• 🏷️ @Adit decorator - Essential for auto-registration
• 🧪 Test-first approach - No code without tests
• 📊 80% minimum coverage - 100% for business logic