LifeLine

LifeLine is a Node.js microservices platform for emergency blood inventory, organ donor matching, hospital notifications, analytics, and workflow orchestration. It includes a global lifeline command-line interface designed for day-to-day operator use.

A narrated browser session covering the core operator workflow: creating an emergency request, running donor matching, updating hospital stock, and sending notifications. The same flow is available through the CLI with lifeline demo run.

• API Gateway: JWT authentication, rate limiting, and service proxying
• Matching Service: geospatial donor matching and compatibility scoring
• Inventory Service: hospital stock updates, reservations, and low-stock alerts
• Notification Service: SMS, email, push, and broadcast notification logging
• Analytics Service: event audit logs and platform metrics
• Saga Orchestrator: emergency workflow event history

npm install
npm link
docker compose up --build
lifeline health

The gateway runs at http://localhost:3000. Use LIFELINE_URL or --url to point the CLI at another gateway.

After npm link, run lifeline from any directory:

lifeline
lifeline help
lifeline version
lifeline health

The CLI provides:

• Styled terminal output with color, sections, and readable command groups
• Spinner feedback for API and database operations
• Interactive prompts for missing required fields in terminal sessions
• Raw JSON mode for scripts with --json
• Command-specific help with lifeline <command> --help

If you do not want to link globally, use:

npm run lifeline -- help

lifeline health
lifeline demo seed
lifeline emergency create
lifeline donors nearby --lat 19.076 --lng 72.8777 --radius 25000 --blood A+ --organ kidney
lifeline inventory stock 660000000000000000000101
lifeline analytics metrics

Running lifeline emergency create without flags opens prompts for patient id, blood type, organ, hospital id, location, and urgency.

lifeline health
lifeline token
lifeline version
lifeline compatibility A+

Use lifeline token when debugging protected gateway routes manually. Tokens use JWT_SECRET from .env.

lifeline emergency create \
  --patient alice \
  --blood A+ \
  --organ kidney \
  --hospital 660000000000000000000101 \
  --lat 19.076 \
  --lng 72.8777 \
  --urgency critical

Required fields: --patient, --blood, --organ, --hospital, --lat, --lng.

Urgency values: critical, urgent, standard.

lifeline donors nearby \
  --lat 19.076 \
  --lng 72.8777 \
  --radius 25000 \
  --blood A+ \
  --organ kidney \
  --limit 5

lifeline match run <requestId>
lifeline match status <requestId>

Radius is in meters. Use 25000 for 25 km.

lifeline inventory stock 660000000000000000000101
lifeline inventory reserve 660000000000000000000101 --blood A+ --units 1
lifeline inventory update 660000000000000000000101 --blood A+ --units +5 --lat 19.076 --lng 72.8777
lifeline inventory alerts --threshold 5

Use positive --units values to add stock and negative values to remove stock.

lifeline notify sms --to +911111111111 --message "Compatible donor found"
lifeline notify email --to [email protected] --subject "Emergency" --message "Review the request"
lifeline notify push --to device-123 --message "Please respond"
lifeline notify broadcast --message "Maintenance starts at 8 PM"

lifeline analytics metrics
lifeline analytics event --event emergency.created --request <requestId>

lifeline saga history <requestId>
lifeline saga event --event emergency.created --request <requestId>

lifeline demo seed
lifeline demo run

demo seed writes sample donors and inventory to MongoDB. demo run seeds data, creates an emergency, finds donors, runs matching, reserves inventory, sends a notification, records workflow events, and prints metrics.

The built-in help is the main documentation for CLI usage:

lifeline help
lifeline emergency --help
lifeline donors --help
lifeline inventory --help
lifeline notify --help
lifeline analytics --help
lifeline saga --help
lifeline demo --help
lifeline compatibility --help

Use this pattern when teaching users:

lifeline <area> --help

Each help page includes usage, required options, optional flags, and examples.

• --url <gateway>: override gateway URL
• --json: print raw JSON and suppress spinner/decorative output
• --help or -h: show help
• --version or -v: show version

Example:

lifeline health --url http://localhost:3000
lifeline inventory alerts --json

Create .env when running locally:

LIFELINE_URL=http://localhost:3000
JWT_SECRET=change_me_dev_secret_at_least_32_chars
MONGO_PASSWORD=change_me_mongo
INTERNAL_SERVICE_TOKEN=change_me_internal_token_16_chars
# Gateway auth is enforced by default. Set REQUIRE_AUTH=0 only for local development.
REQUIRE_AUTH=1
MONGODB_URI=mongodb://admin:change_me_mongo@localhost:27017/lifeline?authSource=admin
MONGO_MIN_POOL_SIZE=5
MONGO_MAX_POOL_SIZE=20
REDIS_URL=redis://localhost:6379
RABBITMQ_URL=amqp://admin:change_me_rabbit@localhost:5672
STRICT_SECRET_VALIDATION=false

Production startup validates service ports, dependency URLs, and required gateway secrets before a service listens. Set STRICT_SECRET_VALIDATION=true to enforce JWT_SECRET length of at least 32 characters and INTERNAL_SERVICE_TOKEN length of at least 16 characters. Mongo-backed services use MONGO_MIN_POOL_SIZE and MONGO_MAX_POOL_SIZE for Mongoose connection pools. They default to 5 and 20, and each service can override them through its own environment.

Gateway API routes require a Authorization: Bearer <jwt> header. The CLI and the web dashboard mint short-lived JWTs automatically from JWT_SECRET; use lifeline token when calling protected routes manually. Auth is enforced by default regardless of NODE_ENV; set REQUIRE_AUTH=0 to disable it for local development only. Backing services additionally verify the gateway's x-internal-token header against INTERNAL_SERVICE_TOKEN (requests are allowed through when the variable is unset), and their /health and /ready endpoints stay public for probes.

Every service returns X-Correlation-ID on responses. If the request includes X-Correlation-ID or X-Request-ID, that value is preserved; otherwise the service generates one and includes it in request logs.

Health endpoints are consistent across services:

curl http://localhost:3000/health
curl http://localhost:3000/ready

/health reports liveness. /ready reports dependency readiness and returns 503 when a configured dependency such as MongoDB, Redis, or RabbitMQ is unavailable. Services also handle SIGTERM and SIGINT by closing HTTP, MongoDB, Redis, and RabbitMQ resources before exit.

npm test
npm run lifeline -- help
npm run lifeline -- version

Service scripts:

npm run start:gateway
npm run start:matching
npm run start:inventory
npm run start:notification
npm run start:analytics
npm run start:saga

Command not found:

npm link
which lifeline

Services unavailable:

docker compose up --build
docker compose logs -f gateway
lifeline health

Need machine-readable output:

lifeline donors nearby --lat 19.076 --lng 72.8777 --radius 25000 --blood A+ --organ kidney --json

Need command details:

lifeline inventory --help