saga-sm - Saga Schedule Manager

saga-sm is a tRPC API service that provides schedule management functionality for Saga Connect, built with saga-soa infrastructure.

🚀 Quick Start for New Developers

What is saga-soa?

saga-soa is our shared infrastructure framework for building consistent APIs across different protocols:

• Multi-protocol support: REST endpoints, tRPC procedures, and TypeGraphQL resolvers
• Common patterns: Dependency injection, logging, database connections, and PubSub events
• Developer experience: Hot reloading, type safety, and consistent project structure
• Business logic organization: Sector-based architecture for domain separation

What is saga-sm?

This project provides:

• Schedule CRUD operations: Create, read, update, delete schedules
• Real-time updates: PubSub events for schedule changes
• Type-safe API: Full TypeScript support from API to client
• Interactive testing: Web client for endpoint exploration and testing

📁 Project Structure

saga-sm/
├── apps/
│   ├── api/                    # tRPC API service (port 3000)
│   │   ├── src/
│   │   │   ├── sectors/        # Business logic by domain
│   │   │   │   ├── schedule/   # Schedule management
│   │   │   │   └── pubsub/     # Event definitions
│   │   │   ├── main.ts         # API bootstrap
│   │   │   └── inversify.config.ts
│   │   └── package.json
│   └── web-client/             # Next.js test client (port 3001)
│       ├── app/                # Testing interfaces
│       │   ├── endpoints/      # Interactive endpoint testing
│       │   ├── api-test/       # Connection testing
│       │   ├── schedule-demo/  # Live demo interface
│       │   └── page.tsx        # Home page
│       ├── src/services/       # tRPC client integration
│       └── package.json
├── scripts/                    # Development setup automation
└── package.json               # Workspace orchestration

🛠️ Development Setup

Prerequisites

• Node.js >= 18
• pnpm >= 8
• MongoDB (local or remote)
• saga-soa repository (must be cloned alongside this project)

Required Directory Structure

dev/
├── saga-soa/          # Shared infrastructure (clone first)
└── saga-sm/           # This project

Quick Setup

1. Clone both repositories:

cd dev/
git clone [saga-soa-repo-url] saga-soa
git clone [saga-sm-repo-url] saga-sm

2. Link saga-sm to saga-soa for concurrent development:

cd saga-sm

# Option A: pnpm link (recommended for active saga-soa development)
./scripts/setup-local-dev.sh

# Option B: file protocol (simpler, automatic updates)
./scripts/setup-file-protocol.sh

3. Configure environment:

# Copy and customize API configuration
cp apps/api/.env.example apps/api/.env
# Update MongoDB URI and other settings as needed

4. Start development servers:

# Terminal 1: Start saga-soa packages (if using pnpm link)
cd ../saga-soa && turbo run dev --filter='@saga-soa/*'

# Terminal 2: Start saga-sm applications
cd saga-sm && pnpm dev

Applications

• API Server: http://localhost:3000

  • tRPC endpoints: /trpc
  • Health check: /health
  • PubSub port: 3002

• Web Client: http://localhost:3001

  • Interactive endpoint testing
  • Live schedule management demo
  • Connection diagnostics

📜 Available Scripts

Root Level (Turborepo)

pnpm dev          # Run both API and web client
pnpm build        # Build all applications  
pnpm test         # Run all tests
pnpm check        # Full validation (build + test + lint + typecheck)
pnpm lint         # Lint all code
pnpm typecheck    # TypeScript validation

Individual Applications

# API only
pnpm --filter @saga-sm/api dev
pnpm --filter @saga-sm/api test

# Web client only  
pnpm --filter @saga-sm/web-client dev
pnpm --filter @saga-sm/web-client test

🏗️ Architecture

API Application (apps/api/)

Following saga-soa patterns:

• Sector-based organization - Business logic organized by domain
• Dependency injection - Using Inversify for service management
• tRPC API - Type-safe API endpoints
• PubSub events - Real-time event system
• 4-space indentation - Code style consistency

Web Client Application (apps/web-client/)

Next.js 15 application with App Router providing:

• Interactive Endpoint Testing - Full tRPC and HTTP testing interface
• Live Demo Interface - Schedule management with real-time updates
• Connection Diagnostics - API health monitoring
• Code Generation - Both tRPC client and cURL examples
• Dual Service Support - tRPC client and HTTP-based access

Pages:

• / - Navigation hub with application overview
• /endpoints - Interactive API endpoint explorer
• /api-test - Connection testing and diagnostics
• /schedule-demo - Live schedule management interface

📡 Available Endpoints

The tRPC API provides these schedule management endpoints:

• schedule.getSchedules - Retrieve all schedules
• schedule.getScheduleById - Get specific schedule by ID
• schedule.createSchedule - Create new schedule
• schedule.updateSchedule - Update existing schedule
• schedule.deleteSchedule - Remove schedule

📻 PubSub Events

Real-time events for schedule changes:

• schedule:created - New schedule created
• schedule:updated - Schedule modified
• schedule:deleted - Schedule removed
• schedule:started - Schedule execution began
• schedule:completed - Schedule execution finished

🧪 Testing

Run Tests

pnpm test                         # All tests across workspace
pnpm --filter @saga-sm/api test  # API tests only
pnpm --filter @saga-sm/web-client test # Client tests only

Test Types

• Unit tests: Individual function/class testing
• Integration tests: API endpoint and database testing
• Type checking: TypeScript validation across codebase

🔧 Development Features

Hot Reloading

• saga-soa packages rebuild automatically when changed
• API server restarts on code changes
• Web client has instant hot reload

Testing Interface

The web client provides comprehensive testing tools:

• Endpoint Explorer - Interactive forms for all API endpoints
• Dual Approach - Switch between tRPC client and HTTP calls
• Code Generation - Copy-ready code examples
• Response Inspection - Detailed API response analysis
• Real-time Updates - Live PubSub event monitoring

Type Safety

• Full TypeScript support throughout
• Shared type definitions (when available)
• End-to-end type safety from API to client

🚨 Troubleshooting

Common Issues

"saga-soa packages not found"

• Ensure saga-soa is cloned in the correct directory structure
• Re-run the setup script: ./scripts/setup-local-dev.sh

"Database connection failed"

• Check MongoDB is running locally or update MONGODB_URI in apps/api/.env
• Verify network connectivity to remote MongoDB instance

"Port already in use"

• API (3000), Web Client (3001), or PubSub (3002) ports are occupied
• Stop other services or update port configuration

"Hot reloading not working"

• Restart both terminal sessions
• Verify saga-soa packages are building with turbo run dev

🚀 Deployment

When ready for production:

1. Update saga-soa dependencies to published npm packages
2. Build applications: pnpm build
3. Deploy API and web client independently
4. Configure environment variables for production

📚 Next Steps

1. Explore the codebase: Start with apps/api/src/sectors/schedule/
2. Test the API: Use the web client to understand available endpoints
3. Read saga-soa docs: Understand the underlying infrastructure patterns
4. Make your first change: Add a new endpoint or modify existing logic