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.

npm

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: '[email protected]',
  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

Production OSS Remote Storage Boundary

open-microservices is the production runtime catalog for the open package ecosystem, but it does not replace repo-native local storage. Each open-[name] package still owns its local-first default and, when needed, its own optional remote adapter.

For direct internal OSS remote mode, use service-prefixed env names and opensource-first AWS names:

Item	Standard
Storage mode	`HASNA_[SERVICE]_STORAGE_MODE=local
RDS URL	HASNA_[SERVICE]_DATABASE_URL
RDS schema	HASNA_[SERVICE]_DATABASE_SCHEMA
S3 bucket	hasna-xyz-opensource-[service]-prod
S3 env	HASNA_[SERVICE]_S3_BUCKET, HASNA_[SERVICE]_S3_PREFIX, HASNA_[SERVICE]_AWS_REGION
Secrets	hasna/xyz/opensource/[service]/prod/{env,rds,s3}

Canonical service names are plural where the package is plural. For example, connect, connector, and open-connectors all resolve to connectors, so production secrets live under hasna/xyz/opensource/connectors/prod/....

Direct OSS remote databases are for internal cross-machine open package state. SaaS wrappers such as platform-todos and platform-skills keep tenant data, accounts, billing, queues, workers, deploy config, and observability in the wrapper/platform database. Do not point an open package direct remote adapter at a SaaS tenant database.

Use the hub CLI to inspect the generated contract:

microservices prod-plan todos
microservices prod-plan connect --json
microservices prod-plan --all

The same contract surface is exported for agents and downstream packages:

import { createMicroservicesStorageContract } from "@hasna/microservices/storage";

const contract = createMicroservicesStorageContract("open-connectors");
console.log(contract.database.urlEnv); // HASNA_CONNECTORS_DATABASE_URL

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 prod-plan todos         # Show RDS/S3/secrets naming for an open package
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