@hasna/microservices

@hasna/microservices

Production-grade microservice building blocks for SaaS apps.

Each microservice is an independent npm package with its own PostgreSQL schema, HTTP API, MCP server, and CLI binary. Install only what you need. Plug into any app.

The 21 Microservices

Package	Binary	Schema	What it does
@hasna/microservice-auth	microservice-auth	auth.*	Users, sessions, JWT, magic links, OAuth, 2FA, API keys
@hasna/microservice-teams	microservice-teams	teams.*	Workspaces, members, RBAC (owner/admin/member/viewer), invites
@hasna/microservice-billing	microservice-billing	billing.*	Stripe subscriptions, plans, invoices, usage-based billing
@hasna/microservice-llm	microservice-llm	llm.*	Multi-provider LLM gateway (OpenAI, Anthropic, DeepSeek) with cost tracking
@hasna/microservice-agents	microservice-agents	agents.*	Agent registry, orchestration, capabilities routing, multi-agent messaging
@hasna/microservice-memory	microservice-memory	memory.*	Long-term agent memory, collections, metadata, vector search
@hasna/microservice-knowledge	microservice-knowledge	knowledge.*	RAG, document ingestion, chunking, pgvector embeddings
@hasna/microservice-guardrails	microservice-guardrails	guardrails.*	AI safety, prompt injection detection, PII scanning, moderation
@hasna/microservice-prompts	microservice-prompts	prompts.*	Versioned prompt management, templates, A/B testing, rollback
@hasna/microservice-notify	microservice-notify	notify.*	Email, SMS, in-app, outbound webhooks, templates
@hasna/microservice-files	microservice-files	files.*	Uploads, S3 storage, presigned URLs, image transforms
@hasna/microservice-audit	microservice-audit	audit.*	Immutable event log, compliance trail, retention policies
@hasna/microservice-traces	microservice-traces	traces.*	Agent observability, spans, latency, token tracking
@hasna/microservice-flags	microservice-flags	flags.*	Feature flags, gradual rollouts, A/B experiments
@hasna/microservice-jobs	microservice-jobs	jobs.*	Background jobs, priority queues, cron, retries
...and 6 more!			sessions, usage, waitlist, onboarding, webhooks, search

Install

# Install one or more
bun install -g @hasna/microservice-auth @hasna/microservice-teams

# Or use the hub CLI to manage all
bun install -g @hasna/microservices
microservices install auth teams billing

Quick Start

# 0. Start a local PostgreSQL instance (with pgvector)
docker-compose up -d

# 1. Install a service
bun install -g @hasna/microservice-auth

# 2. Initialize and migrate your PostgreSQL
microservices init-all --db "$DATABASE_URL"

# 3. Start the HTTP APIs
microservices serve-all

# 4. Or start the MCP server (for AI agents)
microservice-auth mcp

Two Modes: Embedded or Standalone

Embedded — import in your app

import { migrate, register, login } from '@hasna/microservice-auth'

const sql = getDb(process.env.DATABASE_URL!)
await migrate(sql)

const { user, access_token, session } = await register(sql, {
  email: 'user@example.com',
  password: 'secure-password',
})

Standalone — run as HTTP service

microservice-auth serve --port 3001
# POST http://localhost:3001/auth/register
# POST http://localhost:3001/auth/login
# GET  http://localhost:3001/auth/session

Complete SaaS Stack Example

import { register } from '@hasna/microservice-auth'
import { createWorkspace, checkPermission } from '@hasna/microservice-teams'
import { createCheckoutSession } from '@hasna/microservice-billing'
import { sendNotification } from '@hasna/microservice-notify'
import { logEvent } from '@hasna/microservice-audit'
import { evaluateFlag } from '@hasna/microservice-flags'
import { enqueue } from '@hasna/microservice-jobs'

const { user, access_token } = await register(sql, { email, password })
const workspace = await createWorkspace(sql, { name: 'My Company', ownerId: user.id })
const checkout = await createCheckoutSession({ workspaceId: workspace.id, planId, successUrl, cancelUrl, stripeSecretKey })
await sendNotification(sql, { userId: user.id, channel: 'email', type: 'welcome', body: 'Welcome!' })
await logEvent(sql, { actorId: user.id, action: 'user.registered', resourceType: 'user', resourceId: user.id })
const { value } = await evaluateFlag(sql, 'new-onboarding', { userId: user.id })
await enqueue(sql, { type: 'onboarding.setup', payload: { userId: user.id } })

Environment Variables

Variable	Used by	Required
DATABASE_URL	All services	Yes
JWT_SECRET	auth	Yes
STRIPE_SECRET_KEY	billing	Yes
STRIPE_WEBHOOK_SECRET	billing	Yes
RESEND_API_KEY	notify (email)	Optional
TWILIO_ACCOUNT_SID	notify (SMS)	Optional
S3_BUCKET	files	Optional (falls back to local)
GITHUB_CLIENT_ID	auth (OAuth)	Optional
GOOGLE_CLIENT_ID	auth (OAuth)	Optional

Hub CLI

microservices list                    # List all available microservices
microservices install auth teams      # Install specific services
microservices install --all           # Install all 21
microservices status                  # Check what's installed
microservices info auth               # Detailed info + required env
microservices migrate-all             # Run migrations on all installed
microservices run auth status         # Run any CLI command on a service
microservices search stripe           # Search by keyword

Hub MCP Server

For AI agents — add to your Claude config:

{
  "mcpServers": {
    "microservices": {
      "command": "microservices-mcp"
    }
  }
}

Tools: list_microservices, search_microservices, install_microservice, microservice_status, run_microservice_command, remove_microservice, get_microservice_info

HTTP mode

Run a shared Streamable HTTP MCP server (stateless, 127.0.0.1 only):

microservices-mcp --http
# or: MCP_HTTP=1 microservices-mcp
# default port: 8825 (override with --port or MCP_HTTP_PORT)

Endpoints: GET /health, POST /mcp (Streamable HTTP).

PostgreSQL Schema Isolation

Each service owns its schema — all on one PostgreSQL instance:

auth.*     teams.*     billing.*   notify.*
files.*    audit.*     flags.*     jobs.*

Architecture

• Runtime: Bun
• Database: PostgreSQL (per-service schemas, migrations built-in)
• API: Bun HTTP server (standalone mode)
• MCP: @modelcontextprotocol/sdk (for AI agents)
• CLI: Commander
• Auth crypto: Web Crypto API (no external crypto deps)
• Stripe: Direct fetch() calls (no Stripe SDK)
• S3: Manual SigV4 signing via Web Crypto

Development

bun install && bun test   # 127 tests, 0 failures

With a real database:

DATABASE_URL="$DATABASE_URL" JWT_SECRET="$JWT_SECRET" bun test src/integration.test.ts

License

Apache-2.0 — Hasna