svc-infra 0.1.672__tar.gz → 1.6.1__tar.gz

svc_infra-1.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nfrax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

svc_infra-1.6.1/PKG-INFO

@@ -0,0 +1,362 @@
+Metadata-Version: 2.3
+Name: svc-infra
+Version: 1.6.1
+Summary: Infrastructure for building and deploying prod-ready services
+License: MIT
+Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
+Author: Ali Khatami
+Author-email: aliikhatami94@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Provides-Extra: adyen
+Provides-Extra: duckdb
+Provides-Extra: metrics
+Provides-Extra: mongodb
+Provides-Extra: mssql
+Provides-Extra: mysql
+Provides-Extra: payments
+Provides-Extra: pg
+Provides-Extra: pg2
+Provides-Extra: redshift
+Provides-Extra: s3
+Provides-Extra: snowflake
+Provides-Extra: sqlite
+Provides-Extra: stripe
+Requires-Dist: adyen (>=10.0.0) ; extra == "payments" or extra == "adyen"
+Requires-Dist: aioboto3 (>=12.0.0) ; extra == "s3"
+Requires-Dist: aiofiles (>=24.0.0)
+Requires-Dist: aiosqlite (>=0.19.0) ; extra == "sqlite"
+Requires-Dist: alembic (>=1.13.0)
+Requires-Dist: asyncpg (>=0.29.0) ; extra == "pg"
+Requires-Dist: authlib (>=1.0.0)
+Requires-Dist: cashews[redis] (>=7.0)
+Requires-Dist: duckdb (>=0.10.0) ; extra == "duckdb"
+Requires-Dist: email-validator (>=2.0.0)
+Requires-Dist: fastapi (>=0.110.0)
+Requires-Dist: fastapi-users-db-sqlalchemy (>=7.0.0)
+Requires-Dist: fastapi-users[oauth] (>=14.0.0)
+Requires-Dist: greenlet (>=3.0)
+Requires-Dist: httpx (>=0.25.0)
+Requires-Dist: httpx-oauth (>=0.15.0)
+Requires-Dist: itsdangerous (>=2.0.0)
+Requires-Dist: mcp (>=1.0.0)
+Requires-Dist: motor (>=3.0.0) ; extra == "mongodb"
+Requires-Dist: mysqlclient (>=2.2.0) ; extra == "mysql"
+Requires-Dist: opentelemetry-exporter-otlp (>=1.20.0)
+Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.41b0)
+Requires-Dist: opentelemetry-instrumentation-httpx (>=0.41b0)
+Requires-Dist: opentelemetry-instrumentation-requests (>=0.41b0)
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.41b0)
+Requires-Dist: opentelemetry-propagator-b3 (>=1.20.0)
+Requires-Dist: opentelemetry-sdk (>=1.20.0)
+Requires-Dist: passlib[bcrypt] (>=1.7.4)
+Requires-Dist: prometheus-client (>=0.18.0) ; extra == "metrics"
+Requires-Dist: psycopg2-binary (>=2.9.0) ; extra == "pg2"
+Requires-Dist: psycopg[binary] (>=3.0) ; extra == "pg"
+Requires-Dist: pydantic-settings (>=2.0)
+Requires-Dist: pymysql (>=1.1.0) ; extra == "mysql"
+Requires-Dist: pyodbc (>=5.0.0) ; extra == "mssql"
+Requires-Dist: pyotp (>=2.9.0)
+Requires-Dist: python-dotenv (>=1.0.0)
+Requires-Dist: redis (>=5.0.0)
+Requires-Dist: redshift-connector (>=2.0.0) ; extra == "redshift"
+Requires-Dist: snowflake-connector-python (>=3.0.0) ; extra == "snowflake"
+Requires-Dist: sqlalchemy[asyncio] (>=2.0)
+Requires-Dist: stripe (>=7.0.0) ; extra == "payments" or extra == "stripe"
+Requires-Dist: typer (>=0.12.0)
+Requires-Dist: websockets (>=12.0)
+Project-URL: Documentation, https://nfrax.com/svc-infra
+Project-URL: Homepage, https://github.com/nfraxlab/svc-infra
+Project-URL: Issues, https://github.com/nfraxlab/svc-infra/issues
+Project-URL: Repository, https://github.com/nfraxlab/svc-infra
+Description-Content-Type: text/markdown
+
+# svc-infra
+
+**Production-ready FastAPI infrastructure in one import.**
+
+[![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
+[![CI](https://github.com/nfraxlab/svc-infra/actions/workflows/ci.yml/badge.svg)](https://github.com/nfraxlab/svc-infra/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/svc-infra.svg)](https://pypi.org/project/svc-infra/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Overview
+
+Stop rebuilding auth, billing, webhooks, and background jobs for every project.
+
+### Key Features
+
+- **Auth** - JWT, sessions, OAuth/OIDC, MFA, API keys
+- **Billing** - Usage tracking, subscriptions, invoices, Stripe sync
+- **Database** - PostgreSQL + MongoDB, migrations, inbox/outbox
+- **Jobs** - Background tasks, scheduling, retries, DLQ
+- **Webhooks** - Subscriptions, HMAC signing, delivery retries
+- **Observability** - Prometheus, Grafana dashboards, OTEL
+
+## Why svc-infra?
+
+Every FastAPI project needs the same things: authentication, database setup, background jobs, caching, webhooks, billing... You've written this code before. Multiple times.
+
+**svc-infra** packages battle-tested infrastructure used in production, so you can focus on your actual product:
+
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(name="MyAPI", release="1.0.0")
+# Health checks, CORS, security headers, structured logging
+# Prometheus metrics, OpenTelemetry tracing
+# Request IDs, idempotency middleware
+# That's it. Ship it.
+```
+
+## Quick Install
+
+```bash
+pip install svc-infra
+```
+
+## What's Included
+
+| Feature | What You Get | One-liner |
+|---------|-------------|-----------|
+| **Auth** | JWT, sessions, OAuth/OIDC, MFA, API keys | `add_auth_users(app)` |
+| **Billing** | Usage tracking, subscriptions, invoices, Stripe sync | `add_billing(app)` |
+| **Database** | PostgreSQL + MongoDB, migrations, inbox/outbox | `add_sql_db(app)` |
+| **Jobs** | Background tasks, scheduling, retries, DLQ | `easy_jobs()` |
+| **Webhooks** | Subscriptions, HMAC signing, delivery retries | `add_webhooks(app)` |
+| **Cache** | Redis/memory, decorators, namespacing | `init_cache()` |
+| **Observability** | Prometheus, Grafana dashboards, OTEL | Built-in |
+| **Storage** | S3, local, memory backends | `add_storage(app)` |
+| **Multi-tenancy** | Tenant isolation, scoped queries | Built-in |
+| **Rate Limiting** | Per-user, per-endpoint, headers | Built-in |
+
+## 30-Second Example
+
+Build a complete SaaS backend:
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.ease import easy_service_app
+from svc_infra.api.fastapi.db.sql.add import add_sql_db
+from svc_infra.api.fastapi.auth import add_auth_users, current_active_user
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.fastapi import require_signature
+
+# Create app with batteries included
+app = easy_service_app(name="MySaaS", release="1.0.0")
+
+# Add infrastructure
+add_sql_db(app)                    # PostgreSQL with migrations
+add_auth_users(app)                # Full auth system
+queue, scheduler = easy_jobs()     # Background jobs
+
+# Your actual business logic
+@app.post("/api/process")
+async def process_data(user=Depends(current_active_user)):
+    job = queue.enqueue("heavy_task", {"user_id": user.id})
+    return {"job_id": job.id, "status": "queued"}
+
+# Webhook endpoint with signature verification
+@app.post("/webhooks/stripe")
+async def stripe_webhook(payload=Depends(require_signature(lambda: ["whsec_..."]))):
+    queue.enqueue("process_payment", payload)
+    return {"received": True}
+```
+
+**That's a production-ready API** with auth, database, background jobs, and webhook handling.
+
+## Feature Highlights
+
+### Authentication & Security
+
+Full auth system with zero boilerplate:
+
+```python
+from svc_infra.api.fastapi.auth import add_auth_users, current_active_user
+
+add_auth_users(app)  # Registers /auth/* routes automatically
+
+@app.get("/me")
+async def get_profile(user=Depends(current_active_user)):
+    return {"email": user.email, "mfa_enabled": user.mfa_enabled}
+```
+
+**Includes:** JWT tokens, session cookies, OAuth/OIDC (Google, GitHub, etc.), MFA/TOTP, password policies, account lockout, key rotation.
+
+### Usage-Based Billing
+
+Track usage and generate invoices:
+
+```python
+from svc_infra.billing import BillingService
+
+billing = BillingService(session=db, tenant_id="tenant_123")
+
+# Record API usage (idempotent)
+billing.record_usage(metric="api_calls", amount=1, idempotency_key="req_abc")
+
+# Generate monthly invoice
+invoice = billing.generate_monthly_invoice(
+    period_start=datetime(2025, 1, 1),
+    period_end=datetime(2025, 2, 1),
+)
+```
+
+**Includes:** Usage events, aggregation, plans & entitlements, subscriptions, invoices, Stripe sync hooks.
+
+### Background Jobs
+
+Redis-backed job queue with retries:
+
+```python
+from svc_infra.jobs.easy import easy_jobs
+
+queue, scheduler = easy_jobs()  # Auto-detects Redis or uses memory
+
+# Enqueue work
+queue.enqueue("send_email", {"to": "user@example.com", "template": "welcome"})
+
+# Schedule recurring tasks
+scheduler.add("cleanup", interval_seconds=3600, target="myapp.tasks:cleanup")
+```
+
+```bash
+# Run the worker
+svc-infra jobs run
+```
+
+**Includes:** Visibility timeout, exponential backoff, dead letter queue, interval scheduler, CLI worker.
+
+### Webhooks
+
+Send and receive webhooks with proper security:
+
+```python
+from svc_infra.webhooks import add_webhooks, WebhookService
+
+add_webhooks(app)  # Adds subscription management routes
+
+# Publish events
+webhook_service.publish("invoice.paid", {"invoice_id": "inv_123"})
+
+# Verify incoming webhooks
+@app.post("/webhooks/external")
+async def receive(payload=Depends(require_signature(lambda: ["secret1", "secret2"]))):
+    return {"ok": True}
+```
+
+**Includes:** Subscription store, HMAC-SHA256 signing, delivery retries, idempotent processing.
+
+### Observability
+
+Production monitoring out of the box:
+
+```python
+app = easy_service_app(name="MyAPI", release="1.0.0")
+# Prometheus metrics at /metrics
+# Health checks at /healthz, /readyz, /startupz
+# Request tracing with OpenTelemetry
+```
+
+```bash
+# Generate Grafana dashboards
+svc-infra obs dashboard --service myapi --output ./dashboards/
+```
+
+**Includes:** Prometheus metrics, Grafana dashboard generator, OTEL integration, SLO helpers.
+
+## Configuration
+
+Everything is configurable via environment variables:
+
+```bash
+# Database
+SQL_URL=postgresql://user:pass@localhost/mydb
+MONGO_URL=mongodb://localhost:27017
+
+# Auth
+AUTH_JWT__SECRET=your-secret-key
+AUTH_SMTP_HOST=smtp.sendgrid.net
+
+# Jobs
+JOBS_DRIVER=redis
+REDIS_URL=redis://localhost:6379
+
+# Storage
+STORAGE_BACKEND=s3
+STORAGE_S3_BUCKET=my-uploads
+
+# Observability
+ENABLE_OBS=true
+METRICS_PATH=/metrics
+```
+
+See the [Environment Reference](docs/environment.md) for all options.
+
+## Documentation
+
+| Module | Description | Guide |
+|--------|-------------|-------|
+| **API** | FastAPI bootstrap, middleware, versioning | [docs/api.md](docs/api.md) |
+| **Auth** | Sessions, OAuth/OIDC, MFA, API keys | [docs/auth.md](docs/auth.md) |
+| **Billing** | Usage tracking, subscriptions, invoices | [docs/billing.md](docs/billing.md) |
+| **Database** | SQL + MongoDB, migrations, patterns | [docs/database.md](docs/database.md) |
+| **Jobs** | Background tasks, scheduling | [docs/jobs.md](docs/jobs.md) |
+| **Webhooks** | Publishing, signing, verification | [docs/webhooks.md](docs/webhooks.md) |
+| **Cache** | Redis/memory caching, TTL helpers | [docs/cache.md](docs/cache.md) |
+| **Storage** | S3, local, memory file storage | [docs/storage.md](docs/storage.md) |
+| **Observability** | Metrics, tracing, dashboards | [docs/observability.md](docs/observability.md) |
+| **Security** | Password policy, headers, MFA | [docs/security.md](docs/security.md) |
+| **Tenancy** | Multi-tenant isolation | [docs/tenancy.md](docs/tenancy.md) |
+| **CLI** | Command-line tools | [docs/cli.md](docs/cli.md) |
+
+## Running the Example
+
+See all features working together:
+
+```bash
+git clone https://github.com/nfraxlab/svc-infra.git
+cd svc-infra
+
+# Setup and run
+make setup-template    # Creates DB, runs migrations
+make run-template      # Starts at http://localhost:8001
+```
+
+Visit http://localhost:8001/docs to explore the API.
+
+## Related Packages
+
+svc-infra is part of the **nfrax** infrastructure suite:
+
+| Package | Purpose |
+|---------|---------|
+| **[svc-infra](https://github.com/nfraxlab/svc-infra)** | Backend infrastructure (auth, billing, jobs, webhooks) |
+| **[ai-infra](https://github.com/nfraxlab/ai-infra)** | AI/LLM infrastructure (agents, tools, RAG, MCP) |
+| **[fin-infra](https://github.com/nfraxlab/fin-infra)** | Financial infrastructure (banking, portfolio, insights) |
+
+## License
+
+MIT License - use it for anything.
+
+---
+
+<div align="center">
+
+**Built by [nfraxlab](https://github.com/nfraxlab)**
+
+[Star us on GitHub](https://github.com/nfraxlab/svc-infra) · [View on PyPI](https://pypi.org/project/svc-infra/)
+
+</div>
+

svc_infra-1.6.1/README.md

@@ -0,0 +1,277 @@
+# svc-infra
+
+**Production-ready FastAPI infrastructure in one import.**
+
+[![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
+[![CI](https://github.com/nfraxlab/svc-infra/actions/workflows/ci.yml/badge.svg)](https://github.com/nfraxlab/svc-infra/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/svc-infra.svg)](https://pypi.org/project/svc-infra/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Overview
+
+Stop rebuilding auth, billing, webhooks, and background jobs for every project.
+
+### Key Features
+
+- **Auth** - JWT, sessions, OAuth/OIDC, MFA, API keys
+- **Billing** - Usage tracking, subscriptions, invoices, Stripe sync
+- **Database** - PostgreSQL + MongoDB, migrations, inbox/outbox
+- **Jobs** - Background tasks, scheduling, retries, DLQ
+- **Webhooks** - Subscriptions, HMAC signing, delivery retries
+- **Observability** - Prometheus, Grafana dashboards, OTEL
+
+## Why svc-infra?
+
+Every FastAPI project needs the same things: authentication, database setup, background jobs, caching, webhooks, billing... You've written this code before. Multiple times.
+
+**svc-infra** packages battle-tested infrastructure used in production, so you can focus on your actual product:
+
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(name="MyAPI", release="1.0.0")
+# Health checks, CORS, security headers, structured logging
+# Prometheus metrics, OpenTelemetry tracing
+# Request IDs, idempotency middleware
+# That's it. Ship it.
+```
+
+## Quick Install
+
+```bash
+pip install svc-infra
+```
+
+## What's Included
+
+| Feature | What You Get | One-liner |
+|---------|-------------|-----------|
+| **Auth** | JWT, sessions, OAuth/OIDC, MFA, API keys | `add_auth_users(app)` |
+| **Billing** | Usage tracking, subscriptions, invoices, Stripe sync | `add_billing(app)` |
+| **Database** | PostgreSQL + MongoDB, migrations, inbox/outbox | `add_sql_db(app)` |
+| **Jobs** | Background tasks, scheduling, retries, DLQ | `easy_jobs()` |
+| **Webhooks** | Subscriptions, HMAC signing, delivery retries | `add_webhooks(app)` |
+| **Cache** | Redis/memory, decorators, namespacing | `init_cache()` |
+| **Observability** | Prometheus, Grafana dashboards, OTEL | Built-in |
+| **Storage** | S3, local, memory backends | `add_storage(app)` |
+| **Multi-tenancy** | Tenant isolation, scoped queries | Built-in |
+| **Rate Limiting** | Per-user, per-endpoint, headers | Built-in |
+
+## 30-Second Example
+
+Build a complete SaaS backend:
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.ease import easy_service_app
+from svc_infra.api.fastapi.db.sql.add import add_sql_db
+from svc_infra.api.fastapi.auth import add_auth_users, current_active_user
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.fastapi import require_signature
+
+# Create app with batteries included
+app = easy_service_app(name="MySaaS", release="1.0.0")
+
+# Add infrastructure
+add_sql_db(app)                    # PostgreSQL with migrations
+add_auth_users(app)                # Full auth system
+queue, scheduler = easy_jobs()     # Background jobs
+
+# Your actual business logic
+@app.post("/api/process")
+async def process_data(user=Depends(current_active_user)):
+    job = queue.enqueue("heavy_task", {"user_id": user.id})
+    return {"job_id": job.id, "status": "queued"}
+
+# Webhook endpoint with signature verification
+@app.post("/webhooks/stripe")
+async def stripe_webhook(payload=Depends(require_signature(lambda: ["whsec_..."]))):
+    queue.enqueue("process_payment", payload)
+    return {"received": True}
+```
+
+**That's a production-ready API** with auth, database, background jobs, and webhook handling.
+
+## Feature Highlights
+
+### Authentication & Security
+
+Full auth system with zero boilerplate:
+
+```python
+from svc_infra.api.fastapi.auth import add_auth_users, current_active_user
+
+add_auth_users(app)  # Registers /auth/* routes automatically
+
+@app.get("/me")
+async def get_profile(user=Depends(current_active_user)):
+    return {"email": user.email, "mfa_enabled": user.mfa_enabled}
+```
+
+**Includes:** JWT tokens, session cookies, OAuth/OIDC (Google, GitHub, etc.), MFA/TOTP, password policies, account lockout, key rotation.
+
+### Usage-Based Billing
+
+Track usage and generate invoices:
+
+```python
+from svc_infra.billing import BillingService
+
+billing = BillingService(session=db, tenant_id="tenant_123")
+
+# Record API usage (idempotent)
+billing.record_usage(metric="api_calls", amount=1, idempotency_key="req_abc")
+
+# Generate monthly invoice
+invoice = billing.generate_monthly_invoice(
+    period_start=datetime(2025, 1, 1),
+    period_end=datetime(2025, 2, 1),
+)
+```
+
+**Includes:** Usage events, aggregation, plans & entitlements, subscriptions, invoices, Stripe sync hooks.
+
+### Background Jobs
+
+Redis-backed job queue with retries:
+
+```python
+from svc_infra.jobs.easy import easy_jobs
+
+queue, scheduler = easy_jobs()  # Auto-detects Redis or uses memory
+
+# Enqueue work
+queue.enqueue("send_email", {"to": "user@example.com", "template": "welcome"})
+
+# Schedule recurring tasks
+scheduler.add("cleanup", interval_seconds=3600, target="myapp.tasks:cleanup")
+```
+
+```bash
+# Run the worker
+svc-infra jobs run
+```
+
+**Includes:** Visibility timeout, exponential backoff, dead letter queue, interval scheduler, CLI worker.
+
+### Webhooks
+
+Send and receive webhooks with proper security:
+
+```python
+from svc_infra.webhooks import add_webhooks, WebhookService
+
+add_webhooks(app)  # Adds subscription management routes
+
+# Publish events
+webhook_service.publish("invoice.paid", {"invoice_id": "inv_123"})
+
+# Verify incoming webhooks
+@app.post("/webhooks/external")
+async def receive(payload=Depends(require_signature(lambda: ["secret1", "secret2"]))):
+    return {"ok": True}
+```
+
+**Includes:** Subscription store, HMAC-SHA256 signing, delivery retries, idempotent processing.
+
+### Observability
+
+Production monitoring out of the box:
+
+```python
+app = easy_service_app(name="MyAPI", release="1.0.0")
+# Prometheus metrics at /metrics
+# Health checks at /healthz, /readyz, /startupz
+# Request tracing with OpenTelemetry
+```
+
+```bash
+# Generate Grafana dashboards
+svc-infra obs dashboard --service myapi --output ./dashboards/
+```
+
+**Includes:** Prometheus metrics, Grafana dashboard generator, OTEL integration, SLO helpers.
+
+## Configuration
+
+Everything is configurable via environment variables:
+
+```bash
+# Database
+SQL_URL=postgresql://user:pass@localhost/mydb
+MONGO_URL=mongodb://localhost:27017
+
+# Auth
+AUTH_JWT__SECRET=your-secret-key
+AUTH_SMTP_HOST=smtp.sendgrid.net
+
+# Jobs
+JOBS_DRIVER=redis
+REDIS_URL=redis://localhost:6379
+
+# Storage
+STORAGE_BACKEND=s3
+STORAGE_S3_BUCKET=my-uploads
+
+# Observability
+ENABLE_OBS=true
+METRICS_PATH=/metrics
+```
+
+See the [Environment Reference](docs/environment.md) for all options.
+
+## Documentation
+
+| Module | Description | Guide |
+|--------|-------------|-------|
+| **API** | FastAPI bootstrap, middleware, versioning | [docs/api.md](docs/api.md) |
+| **Auth** | Sessions, OAuth/OIDC, MFA, API keys | [docs/auth.md](docs/auth.md) |
+| **Billing** | Usage tracking, subscriptions, invoices | [docs/billing.md](docs/billing.md) |
+| **Database** | SQL + MongoDB, migrations, patterns | [docs/database.md](docs/database.md) |
+| **Jobs** | Background tasks, scheduling | [docs/jobs.md](docs/jobs.md) |
+| **Webhooks** | Publishing, signing, verification | [docs/webhooks.md](docs/webhooks.md) |
+| **Cache** | Redis/memory caching, TTL helpers | [docs/cache.md](docs/cache.md) |
+| **Storage** | S3, local, memory file storage | [docs/storage.md](docs/storage.md) |
+| **Observability** | Metrics, tracing, dashboards | [docs/observability.md](docs/observability.md) |
+| **Security** | Password policy, headers, MFA | [docs/security.md](docs/security.md) |
+| **Tenancy** | Multi-tenant isolation | [docs/tenancy.md](docs/tenancy.md) |
+| **CLI** | Command-line tools | [docs/cli.md](docs/cli.md) |
+
+## Running the Example
+
+See all features working together:
+
+```bash
+git clone https://github.com/nfraxlab/svc-infra.git
+cd svc-infra
+
+# Setup and run
+make setup-template    # Creates DB, runs migrations
+make run-template      # Starts at http://localhost:8001
+```
+
+Visit http://localhost:8001/docs to explore the API.
+
+## Related Packages
+
+svc-infra is part of the **nfrax** infrastructure suite:
+
+| Package | Purpose |
+|---------|---------|
+| **[svc-infra](https://github.com/nfraxlab/svc-infra)** | Backend infrastructure (auth, billing, jobs, webhooks) |
+| **[ai-infra](https://github.com/nfraxlab/ai-infra)** | AI/LLM infrastructure (agents, tools, RAG, MCP) |
+| **[fin-infra](https://github.com/nfraxlab/fin-infra)** | Financial infrastructure (banking, portfolio, insights) |
+
+## License
+
+MIT License - use it for anything.
+
+---
+
+<div align="center">
+
+**Built by [nfraxlab](https://github.com/nfraxlab)**
+
+[Star us on GitHub](https://github.com/nfraxlab/svc-infra) · [View on PyPI](https://pypi.org/project/svc-infra/)
+
+</div>