Enterprise backend SDK and CLI for FastAPI systems.

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for eitoh-brand from gravatar.com eitoh-brand

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT
  • Author: EitohTech
  • Tags cli , enterprise , fastapi , scaffold , sdk
  • Requires: Python >=3.12
  • Provides-Extra: aws , dev , release
Classifiers
Report project as malware

Project description

EitohForge

PyPI version Python versions Build License

EitohForge is an enterprise backend toolkit for Python/FastAPI that ships as one PyPI package:

  • SDK: eitohforge_sdk (middleware, auth, tenanting, observability, infra contracts/adapters)
  • CLI: eitohforge (project scaffolding, CRUD module generation, migration helpers, local multi-service dev)

This README is intentionally long-form for PyPI and covers features, module usage, and integration options.

How to read this README

  • Main sections (through Deployment Blueprints) follow a single path: run the API → project layout → feature toggling (including REST/WebSocket effects) → data & environments → scaling & CLI reference → SDK depth → infra blueprints.
  • Appendix inlines the same topics as docs/guides/ for offline / single-file PyPI reading — intentional, not accidental duplication.
  • Use the table of contents or PyPI quick navigation to jump; skip the appendix unless you want the full inlined reference.

Gist (1 minute)

  • Install: pip install eitohforge (or pipx install eitohforge for CLI isolation)
  • Scaffold + run REST API: eitohforge create project my_service -> uvicorn app.main:app --reload
  • Validate baseline routes: GET /health, /ready, /status, /sdk/capabilities; interactive API docs (FastAPI): /docs (Swagger UI), /redoc (ReDoc), GET /openapi.json (OpenAPI schema)
  • Enable platform layers via env (CLI shortcut: eitohforge config feature-set <name> --enabled true|false --env-file .env): security_hardening, audit, observability, jwt, https_redirect, idempotency, rate_limit, request_signing, tenant, feature_flags (HTTP endpoint), realtime, realtime_jwt (socket handshake), multi_db_analytics, multi_db_search — run eitohforge config feature-list for the full key → EITOHFORGE_* map
  • Everything else is still EITOHFORGE_* (no separate CLI toggle yet): cache, storage, search, secrets (Vault/AWS/Azure), webhooks, jobs, notifications, messaging — see Configuration and Environment Variables and Feature Coverage
  • Promote by stage: local/dev/staging/prod (UAT usually maps operationally to staging)
  • Scale topology when ready: multi-port local apps (eitohforge dev), multi-instance deploys, optional multi-DB/realtime fanout

Hello World (SDK in 30 seconds)

This is the smallest possible FastAPI app that uses eitohforge_sdk to expose /sdk/capabilities and health endpoints. Docs are FastAPI defaults: /docs, /redoc, /openapi.json.

from fastapi import FastAPI

from eitohforge_sdk.core.capabilities import register_capabilities_endpoint
from eitohforge_sdk.core.config import get_settings
from eitohforge_sdk.core.health import register_health_endpoints


def create_app() -> FastAPI:
    app = FastAPI(title="hello-eitohforge")
    register_capabilities_endpoint(app, settings_provider=get_settings)
    register_health_endpoints(app, settings_provider=get_settings)
    return app


app = create_app()

Run:

uvicorn app:app --reload

Then open:

  • GET /health, /ready, /status
  • /sdk/capabilities
  • /docs, /redoc, /openapi.json

PyPI Quick Navigation

Table of Contents

Installation

Requires Python 3.12+.

Install from PyPI

python -m pip install eitohforge

Install CLI with pipx

pipx install eitohforge
eitohforge --help

Install with uv

uv tool install eitohforge
# or for an app project:
uv add eitohforge

Verify

eitohforge version
python -c "import eitohforge_sdk; print('ok')"

Development install from source

git clone https://github.com/eitoh-brand/EitohForge.git
cd EitohForge
uv sync --all-extras
uv run eitohforge --help

Quick Start

1) Create a project

eitohforge create project my_service
cd my_service

Options:

  • --mode sdk|standalone
    • sdk (default): generated app consumes eitohforge_sdk
    • standalone: self-contained generated core files
  • --profile standard|minimal
    • standard: most platform features enabled by default
    • minimal: opt-in features via env vars

2) Add a CRUD module

eitohforge create crud orders --path .

3) Run app

uvicorn app.main:app --reload

4) Check endpoints

  • GET /health
  • GET /ready
  • GET /status
  • GET /sdk/capabilities
  • OpenAPI / Swagger (FastAPI built-ins) — not separate EitohForge toggles; enabled unless you turn them off on FastAPI(...):
    • GET /docs — Swagger UI (try requests in the browser)
    • GET /redoc — ReDoc (alternate layout)
    • GET /openapi.json — machine-readable OpenAPI 3 schema (for codegen, gateways, CI)

In production, disable or protect public docs: pass docs_url=None, redoc_url=None, and/or openapi_url=None to FastAPI(...), or put the app behind an ingress that blocks /docs unless authenticated.

Project Architecture (folders/files and why)

This repo ships both a reusable SDK and an operator-focused CLI. The structure is intentionally split so runtime framework code, scaffold generation code, docs, and tests evolve independently.

Root folders

Path Why it exists
src/eitohforge_sdk/ Runtime SDK used by generated apps: middleware, settings, infra contracts/adapters, realtime, observability, security layers.
src/eitohforge_cli/ CLI for scaffolding and operations (create, db, dev, plus helper groups).
docs/guides/ Multi-page operational docs (usage, profiles, websocket, runbook, cookbook).
docs/releases/ Human-readable release notes by version.
examples/ Working sample projects for minimal and enterprise patterns.
tests/unit/ Unit tests for SDK and CLI behavior.
scripts/ Project automation helpers (build/release/support scripts).
dist/ Built wheel/sdist artifacts (generated for release checks).

Core SDK package map (src/eitohforge_sdk/)

Path Why needed
core/config.py Typed AppSettings (EITOHFORGE_*) and environment behavior resolution.
core/forge_application.py build_forge_app(...) composition root wiring middleware + routes from settings/toggles.
core/forge_toggles.py Code-level per-layer overrides (ForgePlatformToggles) for deterministic composition.
core/health.py /health, /ready, /status endpoints.
core/capabilities.py /sdk/capabilities runtime contract and feature introspection output.
core/feature_flags.py Feature-flag endpoint wiring and service abstractions.
core/* middleware modules Cross-cutting concerns: auth, tenant, idempotency, rate limit, signing, observability, audit.
infrastructure/repositories/sqlalchemy_repository.py Generic repository implementation on SQLAlchemy with query spec support.
infrastructure/sockets/ WebSocket transport (/realtime/ws), auth extraction, optional Redis fan-out bridge.
infrastructure/* (cache/storage/search/webhooks/jobs/...) Provider adapters and integration primitives for platform capabilities.

CLI package map (src/eitohforge_cli/)

Path Why needed
main.py Typer root command registration and entrypoint.
commands/create.py Project and CRUD scaffold generation.
commands/db.py Alembic wrapper commands for migration workflows.
commands/dev.py Multi-service local startup from forge.dev.json.
commands/config.py Env group discovery and profile env template output.
commands/docs.py Fast lookup of docs topics and canonical file paths.
templates.py + template_parts/*.py Source-of-truth scaffold templates split by concern (core/security/storage/cache/etc.).

Why this split matters

  • eitohforge_sdk can be versioned and consumed independently of scaffold templates.
  • CLI scaffolding remains composable: template modules map directly to generated project areas.
  • Docs and tests stay close to behavior and release notes, making upgrades auditable.

Feature Enable/Disable Strategy

One place for toggles: environment flags and ForgePlatformToggles decide which HTTP routes, WebSocket endpoints, and middleware are active. The tables under What toggling affects on the wire are part of this same topic — not a separate “REST API chapter.”

There are three practical layers:

  1. Profile at scaffold time (create project --profile standard|minimal)
  • standard: starts with more platform behavior enabled by default
  • minimal: conservative defaults and explicit opt-in
  1. Runtime flags via environment variables (EITOHFORGE_*)
    Common examples:
EITOHFORGE_RATE_LIMIT_ENABLED=true
EITOHFORGE_IDEMPOTENCY_ENABLED=true
EITOHFORGE_REQUEST_SIGNING_ENABLED=false
EITOHFORGE_OBSERVABILITY_ENABLED=true
EITOHFORGE_OBSERVABILITY_ENABLE_PROMETHEUS=true
EITOHFORGE_OBSERVABILITY_OTEL_ENABLED=true
EITOHFORGE_REALTIME_ENABLED=true
EITOHFORGE_REALTIME_REQUIRE_ACCESS_JWT=true
EITOHFORGE_AUTH_JWT_ENABLED=true
EITOHFORGE_RUNTIME_ENFORCE_HTTPS_REDIRECT=true
EITOHFORGE_TENANT_ENABLED=true
EITOHFORGE_DB_ANALYTICS_ENABLED=true
EITOHFORGE_DB_SEARCH_ENABLED=true

For TLS certificate pinning: apply at API gateway/client transport layer (outside SDK runtime flags), then document rotation policy in your platform runbook.

  1. Code-level toggles for controlled rollout (ForgePlatformToggles)
    Useful when you want deterministic app composition per deployment stage.
from eitohforge_sdk.core import ForgeAppBuildConfig, ForgePlatformToggles, build_forge_app
from eitohforge_sdk.core.config import get_settings

toggles = ForgePlatformToggles(
    realtime_websocket=False,
    observability=True,
    feature_flags=True,
)

app = build_forge_app(
    build=ForgeAppBuildConfig(
        title="My Service",
        settings_provider=get_settings,
        toggles=toggles,
    )
)

What toggling affects on the wire (REST & WebSocket)

build_forge_app(ForgeAppBuildConfig(...)) registers platform routes and middleware. ForgeAppBuildConfig.wire_platform_middleware=False builds a minimal FastAPI app (CORS + optional HTTPS redirect only) — no health/capabilities/feature-flags/realtime routers and no platform middleware stack.

Surface Method / path Primary controls If disabled or not mounted
Health GET /health, /ready, /status wire_health_family; ForgePlatformToggles.health; settings-driven layers for readiness 404 on those paths
Capabilities GET /sdk/capabilities wire_capabilities; toggles.capabilities 404
Feature flags GET + EITOHFORGE_FEATURE_FLAGS_ENDPOINT_PATH (default /sdk/feature-flags) EITOHFORGE_FEATURE_FLAGS_ENABLED; wire_feature_flags; toggles.feature_flags 404 (endpoint not registered when FEATURE_FLAGS_ENABLED=false)
Prometheus GET + EITOHFORGE_OBSERVABILITY_PROMETHEUS_METRICS_PATH (default /metrics) EITOHFORGE_OBSERVABILITY_ENABLED; EITOHFORGE_OBSERVABILITY_ENABLE_PROMETHEUS; toggles.observability 404
Realtime WebSocket /realtime/ws EITOHFORGE_REALTIME_ENABLED; wire_realtime_websocket; toggles.realtime_websocket; Redis URL for cross-worker fan-out 404 or failed upgrade; hub features off when REALTIME_ENABLED=false

/sdk/capabilities JSON includes pointers such as feature_flags.endpoint_path so clients can discover the exact feature-flag URL.

OpenAPI / Swagger UI (interactive HTTP docs)

These come from FastAPI on the generated app object (defaults apply unless you override FastAPI(...)):

Path Purpose
GET /docs Swagger UI — interactive “try it” browser for REST routes
GET /redoc ReDoc — alternate API reference UI
GET /openapi.json OpenAPI 3 schema (SDK clients, codegen, API gateways)

They are not controlled by EITOHFORGE_* unless your app.main passes custom docs_url / redoc_url / openapi_url. For production hardening, disable or restrict these paths (see Quick start — check endpoints).

eitohforge ops check also probes GET /openapi.json to confirm the schema is served.

Middleware-only toggles (HTTP outcomes)

These layers are toggled the same way as above (EITOHFORGE_* + optional ForgePlatformToggles); they do not add separate “feature CRUD” routes — they change behavior on matching requests:

Layer Key settings Typical client-visible outcome
Security hardening EITOHFORGE_SECURITY_HARDENING_* 400 (body/hosts) / rejected requests
Request signing EITOHFORGE_REQUEST_SIGNING_* (headers configurable) 401 / 403 when signature invalid or missing
Rate limit EITOHFORGE_RATE_LIMIT_* 429 when exceeded
Idempotency EITOHFORGE_IDEMPOTENCY_* + idempotency header (default Idempotency-Key) Replay: same stored status + body + X-Idempotent-Replay: true; 409 if the same key is reused with a different payload
Tenant isolation EITOHFORGE_TENANT_* 400 / 403 when tenant missing or not allowed
Audit EITOHFORGE_AUDIT_* No dedicated status; writes audit records
Observability EITOHFORGE_OBSERVABILITY_* Request IDs / tracing headers per config; no error by default

ForgePlatformToggles fields (security_hardening, audit, observability, …) override AppSettings.*.enabled per layer when you need code-level on/off regardless of env files.

Database Selection and Connectivity

DB selection is controlled by EITOHFORGE_DB_DRIVER + related settings.

PostgreSQL (default path)

EITOHFORGE_DB_DRIVER=postgresql+psycopg
EITOHFORGE_DB_HOST=localhost
EITOHFORGE_DB_PORT=5432
EITOHFORGE_DB_USERNAME=postgres
EITOHFORGE_DB_PASSWORD=postgres
EITOHFORGE_DB_NAME=eitohforge

MySQL

EITOHFORGE_DB_DRIVER=mysql+pymysql
EITOHFORGE_DB_HOST=localhost
EITOHFORGE_DB_PORT=3306
EITOHFORGE_DB_USERNAME=root
EITOHFORGE_DB_PASSWORD=secret
EITOHFORGE_DB_NAME=my_service

SQLite

EITOHFORGE_DB_DRIVER=sqlite
EITOHFORGE_DB_NAME=./data/app.db
# or in-memory:
# EITOHFORGE_DB_NAME=:memory:

Connectivity and migration workflow

eitohforge db init --path .
eitohforge db migrate -m "init schema" --path .
eitohforge db upgrade --path .
eitohforge db current --path .

For tenant-aware Postgres schema isolation:

EITOHFORGE_TENANT_ENABLED=true
EITOHFORGE_TENANT_DB_SCHEMA_ISOLATION_ENABLED=true
EITOHFORGE_TENANT_DB_SCHEMA_NAME_TEMPLATE={tenant_id}

Multi-Environment Usage (local/dev/staging/prod)

EITOHFORGE_APP_ENV controls environment posture and capability hints (local, dev, staging, prod).

Recommended environment layering

  • Local laptop: .env + optional .env.local
  • CI/dev namespace: CI/CD injected env vars
  • Staging/prod: secret manager + deployment manifests (no plaintext secrets in repo)

Example: local

EITOHFORGE_APP_ENV=local
EITOHFORGE_DB_DRIVER=sqlite
EITOHFORGE_DB_NAME=:memory:
EITOHFORGE_AUTH_JWT_SECRET=replace-with-long-local-secret
EITOHFORGE_OBSERVABILITY_ENABLED=true
EITOHFORGE_REALTIME_ENABLED=false

Example: dev/staging

EITOHFORGE_APP_ENV=staging
EITOHFORGE_DB_DRIVER=postgresql+psycopg
EITOHFORGE_DB_HOST=postgres.staging.internal
EITOHFORGE_DB_PORT=5432
EITOHFORGE_DB_USERNAME=svc_eitohforge
EITOHFORGE_DB_PASSWORD=***from-secret-store***
EITOHFORGE_DB_NAME=eitohforge_staging
EITOHFORGE_CACHE_PROVIDER=redis
EITOHFORGE_CACHE_REDIS_URL=redis://redis.staging.internal:6379/0
EITOHFORGE_REALTIME_ENABLED=true
EITOHFORGE_REALTIME_REDIS_URL=redis://redis.staging.internal:6379/2
EITOHFORGE_OBSERVABILITY_OTEL_ENABLED=true
EITOHFORGE_OBSERVABILITY_OTEL_OTLP_HTTP_ENDPOINT=http://otel-collector:4318/v1/traces

Example: production

EITOHFORGE_APP_ENV=prod
EITOHFORGE_RUNTIME_ENFORCE_HTTPS_REDIRECT=true
EITOHFORGE_SECURITY_HARDENING_ENABLED=true
EITOHFORGE_RATE_LIMIT_ENABLED=true
EITOHFORGE_REQUEST_SIGNING_ENABLED=true
EITOHFORGE_TENANT_ENABLED=true
EITOHFORGE_OBSERVABILITY_ENABLE_PROMETHEUS=true

Environment profile guidance

  • local: fastest feedback, lightweight dependencies
  • dev: integration behavior close to prod, relaxed blast radius
  • staging: pre-prod with production-like data shape/traffic simulation
  • prod: strict security, observability, controlled rollout and autoscaling

New deployment targets (UAT, staging, custom)

Two different meanings of “new environment”:

What you want Code change? What to do
New operational target (e.g. a UAT cluster, namespace, or CI stage) No Provision infra + secrets; set EITOHFORGE_* per target (often a dedicated secret store entry or .env.uat). Keep EITOHFORGE_APP_ENV as one of the built-in values: local, dev, staging, prod. Many teams map UAT → staging so posture stays “pre-prod-like” without a new enum.
New first-class label (e.g. EITOHFORGE_APP_ENV=uat as its own value) Yes Extend app_env in AppSettings (and generated templates), update resolve_environment_behavior() and any validators that branch on app_env. This is a small SDK/template change — not something you can turn on from env alone.

Practical recipe (no code change): create uat (or any name) as a deployment name in K8s/Helm/CI; wire its ConfigMap/secret to EITOHFORGE_APP_ENV=staging (or dev) and set DB/cache URLs for that cluster. The runtime only sees the four built-in env values.

See also docs/guides/usage-complete.md → Environments (EITOHFORGE_APP_ENV).

Multi-Port and Multi-Instance Patterns

Local multi-port development

Use eitohforge dev with forge.dev.json to run several FastAPI services at once (different ports, optional working directories and env overrides).

eitohforge dev validate --path .
eitohforge dev --path .

Horizontal multi-instance deployment

EitohForge apps are stateless by design at the HTTP layer and can run as multiple instances behind a load balancer. For shared behavior across instances:

  • Session/cache: use Redis provider
  • Realtime socket fanout/direct messaging: set EITOHFORGE_REALTIME_REDIS_URL
  • Idempotency/rate-limit/replay semantics: prefer shared backing stores for strict cross-instance behavior

Example production launch styles:

# Single process dev-like
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Multi-worker single node
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

In clustered/container environments, run multiple pods/instances behind your ingress/LB and keep Redis/Postgres as shared stateful services.

CLI Usage (complete)

eitohforge --help

Top-level command groups:

  • version
  • create
  • db
  • dev
  • config
  • docs
  • ops
  • feature-flags
  • doctor

Use eitohforge config feature-set to write EITOHFORGE_* flags into an env file; that complements the Feature Enable/Disable Strategy section above.

eitohforge version

Prints installed package version (from distribution metadata).

eitohforge create

Create project

eitohforge create project my_service --path . --mode sdk --profile standard

Create CRUD module

eitohforge create crud orders --path ./my_service

Generate implementation pseudocode

eitohforge create pseudocode --path ./my_service

eitohforge db

Alembic helper commands for generated projects:

eitohforge db init --path .
eitohforge db migrate -m "add orders table" --path .
eitohforge db upgrade --revision head --path .
eitohforge db downgrade --revision -1 --path .
eitohforge db current --path .

eitohforge dev

Runs multiple uvicorn services from forge.dev.json.

eitohforge dev --path .
eitohforge dev validate --path .

Example forge.dev.json:

{
  "schema_version": 1,
  "default_host": "127.0.0.1",
  "services": [
    {
      "name": "api",
      "module": "app.main:app",
      "port": 8000
    },
    {
      "name": "worker-api",
      "module": "worker_app.main:app",
      "port": 8100,
      "working_directory": "."
    }
  ]
}

eitohforge config

Configuration helpers for environment management:

eitohforge config env-groups
eitohforge config env-template --profile local
eitohforge config env-template --profile staging
eitohforge config feature-list
eitohforge config feature-set jwt --enabled true --env-file .env
eitohforge config feature-set realtime --enabled true --env-file .env
eitohforge config feature-set realtime_jwt --enabled true --env-file .env
eitohforge config feature-set https_redirect --enabled true --env-file .env
eitohforge config feature-set multi_db_analytics --enabled true --env-file .env
eitohforge config feature-set rate_limit --enabled true --env-file .env
eitohforge config feature-set request_signing --enabled false --env-file .env

eitohforge docs

Documentation discovery helpers:

eitohforge docs list
eitohforge docs path usage
eitohforge docs path architecture

eitohforge ops

Runtime endpoint checks against a deployed or local service:

eitohforge ops check --base-url http://127.0.0.1:8000
eitohforge ops smoke --base-url http://127.0.0.1:8000 --max-latency-ms 500

Checks GET /health, /ready, /status, /sdk/capabilities, and GET /openapi.json (prints a one-line OpenAPI summary; use /docs and /redoc in the browser for interactive docs).

eitohforge feature-flags

Inspect the running feature flags endpoint:

eitohforge feature-flags get --base-url http://127.0.0.1:8000
# custom path:
eitohforge feature-flags get --base-url https://api.example.com --path /sdk/feature-flags

eitohforge doctor

Sanity-check generated project structure:

eitohforge doctor check --path .
eitohforge doctor check --path . --file forge.dev.json

SDK Usage (complete)

The package name is eitohforge, but imports are from eitohforge_sdk.

Minimal app

from fastapi import FastAPI

from eitohforge_sdk.core.capabilities import register_capabilities_endpoint
from eitohforge_sdk.core.config import get_settings

def create_app() -> FastAPI:
    app = FastAPI(title="My Service")
    register_capabilities_endpoint(app, settings_provider=get_settings)

    @app.get("/health")
    def health() -> dict[str, str]:
        return {"status": "ok"}

    return app

app = create_app()

Full platform app

from fastapi import FastAPI

from eitohforge_sdk.core import ForgeAppBuildConfig, build_forge_app
from eitohforge_sdk.core.config import get_settings

app: FastAPI = build_forge_app(
    build=ForgeAppBuildConfig(
        title="My Service",
        settings_provider=get_settings,
    )
)

Feature Coverage and Module-by-Module Usage

This section focuses on practical usage for each major capability.

1) API capabilities endpoint

from eitohforge_sdk.core.capabilities import register_capabilities_endpoint
register_capabilities_endpoint(app)

Runtime discovery payload includes:

  • feature toggles (rate_limit, request_signing, tenant_isolation, realtime_websocket, ...)
  • provider choices (cache, storage, search, secrets)
  • headers and runtime contracts (e.g., request signing headers)

2) Authentication: JWT

from datetime import timedelta

from eitohforge_sdk.core.auth import JwtTokenManager, TokenType

manager = JwtTokenManager(
    secret="a-very-long-secret-at-least-32-chars",
    access_ttl=timedelta(minutes=15),
    refresh_ttl=timedelta(days=7),
)

pair = manager.issue_token_pair(subject="user-123", tenant_id="tenant-a")
access_claims = manager.decode_and_validate(pair.access_token, expected_type=TokenType.ACCESS)
rotated = manager.rotate_refresh_token(pair.refresh_token)

3) Authentication: sessions (memory or Redis)

from eitohforge_sdk.core.auth import SessionManager, build_session_store

store = build_session_store(provider="memory")
# store = build_session_store(provider="redis", redis_url="redis://localhost:6379/0")

sessions = SessionManager(store=store)
record = sessions.create_session(subject="user-123", tenant_id="tenant-a")
validated = sessions.validate_session(record.session_id)
sessions.revoke_session(record.session_id)

4) Authentication: SSO broker + adapters (OIDC/SAML)

from eitohforge_sdk.core.auth import InMemorySsoLinkStore, SsoBroker

link_store = InMemorySsoLinkStore()
broker = SsoBroker(link_store=link_store)
# Register OidcSsoProvider / SamlSsoProvider and call broker.authenticate(...)

5) RBAC / ABAC / security context

from eitohforge_sdk.core import require_roles, require_policies, TenantMatchPolicy

# Use `require_roles("admin")` as route dependency
# Use `require_policies(TenantMatchPolicy())` for tenant-aware policy checks

6) Tenant isolation and context

TenantContext.current() is available when tenant middleware is wired.

  • tenant headers enforced by TenantIsolationRule
  • cache keys and storage keys are tenant-prefixed when tenant enabled
  • optional Postgres schema isolation via search_path

7) Realtime WebSocket (JWT + rooms + direct messaging)

from eitohforge_sdk.infrastructure.sockets.realtime_router import build_realtime_router, attach_socket_hub
from eitohforge_sdk.core.config import get_settings

attach_socket_hub(app, settings_provider=get_settings)
app.include_router(build_realtime_router(settings_provider=get_settings))

Client message types include ping, join, leave, broadcast, and direct.

Socket authentication modes

  • EITOHFORGE_REALTIME_REQUIRE_ACCESS_JWT=true:
    • token required at handshake
    • invalid/missing token is rejected with close code 1008
  • false:
    • anonymous principal is allowed
    • if token is present and valid, actor/tenant claims are still used

Client message contract (inbound)

{ "type": "ping" }
{ "type": "join", "room": "orders:tenant-a" }
{ "type": "leave", "room": "orders:tenant-a" }
{ "type": "broadcast", "room": "orders:tenant-a", "event": "order.updated", "payload": { "id": "o-1" } }
{ "type": "direct", "target_actor_id": "user-42", "event": "notify", "payload": { "kind": "alert" } }

Server message contract (outbound examples)

{ "type": "connected", "connection_id": "...", "actor_id": "user-1", "tenant_id": "tenant-a" }
{ "type": "joined", "room": "orders:tenant-a", "ok": true }
{ "type": "broadcast_result", "room": "orders:tenant-a", "delivered": 5 }
{ "type": "event", "event": "order.updated", "room": "orders:tenant-a", "payload": { "id": "o-1" } }
{ "type": "error", "code": "NOT_IN_ROOM", "message": "Join the room before broadcasting." }

Scaling sockets across instances

  • Single-process: in-memory hub is sufficient
  • Multi-worker / multi-pod: configure EITOHFORGE_REALTIME_REDIS_URL to enable Redis fanout hub
  • Keep sticky sessions optional; fanout works across workers through Redis channel transport
  • For private/direct actor messages across instances, ensure consistent actor identity in JWT claims

Production socket hardening checklist

  • require JWT handshake (EITOHFORGE_REALTIME_REQUIRE_ACCESS_JWT=true)
  • isolate room naming by tenant (tenant_id prefix convention)
  • enforce payload size limits at ingress / reverse proxy
  • monitor connection counts and broadcast delivery metrics
  • apply backpressure/timeouts in client and gateway layers

8) Request signing middleware

from eitohforge_sdk.core.request_signing import RequestSigningRule, register_request_signing_middleware

register_request_signing_middleware(
    app,
    RequestSigningRule(enabled=True),
    resolve_secret=lambda key_id: "shared-secret" if key_id in (None, "", "default") else None,
)

This enforces tamper and replay protection (timestamp, nonce, signature over canonical payload).

9) Idempotency middleware

from eitohforge_sdk.core.idempotency import IdempotencyRule, register_idempotency_middleware

register_idempotency_middleware(
    app,
    IdempotencyRule(header_name="idempotency-key", ttl_seconds=86400),
)

10) Rate limiting middleware

from eitohforge_sdk.core.rate_limit import RateLimitRule, register_rate_limiter_middleware

register_rate_limiter_middleware(
    app,
    RateLimitRule(max_requests=120, window_seconds=60),
)

11) Observability (request logging, metrics, tracing)

from eitohforge_sdk.core.observability import (
    ObservabilityRule,
    PrometheusMetricsSink,
    register_observability_middleware,
    register_prometheus_metrics_endpoint,
)

metrics_sink = PrometheusMetricsSink(namespace="eitohforge")
register_prometheus_metrics_endpoint(app, metrics_sink=metrics_sink, path="/metrics")
register_observability_middleware(app, ObservabilityRule(enabled=True), metrics_sink=metrics_sink)

OTEL is enabled through settings (EITOHFORGE_OBSERVABILITY_OTEL_*) in full app wiring.

12) Audit middleware

from eitohforge_sdk.core.audit import AuditRule, register_audit_middleware

register_audit_middleware(app, AuditRule(enabled=True, methods=("POST", "PUT", "PATCH", "DELETE")))

13) Security hardening middleware

from eitohforge_sdk.core.security_hardening import SecurityHardeningRule, register_security_hardening_middleware

register_security_hardening_middleware(
    app,
    SecurityHardeningRule(enabled=True, max_request_bytes=1_048_576),
)

14) Cache providers (memory / Redis)

from eitohforge_sdk.core.config import get_settings
from eitohforge_sdk.infrastructure.cache import build_cache_provider

cache = build_cache_provider(get_settings())
cache.set("k", {"ok": True}, ttl_seconds=30)
value = cache.get("k")

15) Storage providers (local / S3)

from eitohforge_sdk.core.config import get_settings
from eitohforge_sdk.infrastructure.storage import build_storage_provider

storage = build_storage_provider(get_settings())
obj = storage.put_bytes("docs/report.txt", b"hello", content_type="text/plain")
exists = storage.exists(obj.key)

Tenant-enabled mode wraps with tenant key prefix automatically.

16) Search providers (memory / OpenSearch / Elasticsearch)

from eitohforge_sdk.core.config import get_settings
from eitohforge_sdk.infrastructure.search import build_search_provider

search = build_search_provider(get_settings())
# index/search operations depend on provider contract

17) External API client (retry + circuit breaker)

from eitohforge_sdk.infrastructure.external_api import ApiRequest, HttpMethod, ResilientExternalApiClient

client = ResilientExternalApiClient()
request = ApiRequest(method=HttpMethod.GET, url="https://api.example.com/ping")
# await client.call(request, transport=my_transport)

18) Background jobs (in-memory queue)

from eitohforge_sdk.infrastructure.jobs import InMemoryBackgroundJobQueue

queue = InMemoryBackgroundJobQueue()
queue.register_handler("send-email", lambda job: None)
queue.enqueue("send-email", payload={"to": "u@example.com"})
# await queue.run_all_available()

19) Notifications

from eitohforge_sdk.infrastructure.notifications import (
    InMemoryNotificationGateway,
    NotificationChannel,
    NotificationMessage,
    success_result_for,
)

gateway = InMemoryNotificationGateway()
gateway.register_sender(NotificationChannel.EMAIL, lambda msg: success_result_for(msg))
# await gateway.send(NotificationMessage(...))

20) Webhooks (signed delivery + dead-letter)

from datetime import UTC, datetime

from eitohforge_sdk.infrastructure.webhooks import WebhookDispatcher, WebhookEndpointConfig, WebhookEvent

dispatcher = WebhookDispatcher()
event = WebhookEvent(name="order.created", payload={"id": "o-1"}, occurred_at=datetime.now(UTC))
endpoint = WebhookEndpointConfig(url="https://example.com/webhooks", secret="whsec-test")
# await dispatcher.dispatch(event, endpoint, transport=my_transport)

21) Messaging / event bus

Use InMemoryEventBus and dispatcher patterns for domain events; optional Redis bridge support exists for cross-process publish.

22) Feature flags and plugins

from eitohforge_sdk.core import FeatureFlagDefinition, FeatureFlagService, PluginRegistry

flags = FeatureFlagService()
flags.register(FeatureFlagDefinition(key="new_checkout", enabled=True, rollout_percentage=10))

plugins = PluginRegistry()
# plugins.register(my_plugin_module)

Third-Party Support Matrix

The SDK is designed to work with these ecosystem components (directly or through provider adapters):

Area Supported / integrated
Web framework FastAPI, Starlette
Settings/validation pydantic, pydantic-settings
ORM/migrations SQLAlchemy, Alembic
Databases PostgreSQL (psycopg), MySQL (pymysql), SQLite
Cache/session/realtime fanout Redis
Tracing/metrics OpenTelemetry (opentelemetry-api/sdk/exporter-otlp), Prometheus (prometheus-client)
Search OpenSearch / Elasticsearch compatible endpoints
CLI Typer
Templating/scaffolding Jinja2

Notes:

  • Some providers are optional at runtime and activated by EITOHFORGE_* settings.
  • Missing optional deps typically surface as clear runtime errors (e.g., Redis store without redis runtime).

Configuration and Environment Variables

All runtime settings are namespaced with EITOHFORGE_*.

Major groups:

  • EITOHFORGE_APP_*
  • EITOHFORGE_DB_*, EITOHFORGE_DB_ANALYTICS_*, EITOHFORGE_DB_SEARCH_*
  • EITOHFORGE_CACHE_*
  • EITOHFORGE_STORAGE_*
  • EITOHFORGE_AUTH_*
  • EITOHFORGE_TENANT_*
  • EITOHFORGE_RATE_LIMIT_*
  • EITOHFORGE_IDEMPOTENCY_*
  • EITOHFORGE_REQUEST_SIGNING_*
  • EITOHFORGE_OBSERVABILITY_*
  • EITOHFORGE_AUDIT_*
  • EITOHFORGE_SEARCH_*
  • EITOHFORGE_REALTIME_*
  • EITOHFORGE_SECRET_*

For exhaustive keys and behavior, see:

  • docs/guides/usage-complete.md
  • generated project .env.example

Examples

  • examples/example-minimal/ — minimal app with health + capabilities
  • examples/example-enterprise/ — full platform wiring using build_forge_app

Deployment Blueprints (end-to-end)

These blueprints provide practical infrastructure layouts for common maturity stages.

Blueprint A: Single node (small internal service)

Best for: development, POC, low traffic internal tools.

  • 1 VM/container host running app (uvicorn --workers N)
  • local or managed PostgreSQL
  • optional Redis (if using Redis cache/session/realtime fanout)
  • reverse proxy / TLS terminator (Nginx/Caddy/Ingress)

Suggested settings:

EITOHFORGE_APP_ENV=dev
EITOHFORGE_DB_DRIVER=postgresql+psycopg
EITOHFORGE_CACHE_PROVIDER=memory
EITOHFORGE_REALTIME_ENABLED=false
EITOHFORGE_OBSERVABILITY_ENABLE_PROMETHEUS=true

Trade-offs:

  • simplest operations
  • limited horizontal scale and fault tolerance

Blueprint B: HA service (LB + app replicas + Redis + Postgres)

Best for: production baseline with predictable traffic and HA requirements.

Topology:

  • L7 load balancer / ingress
  • 2+ stateless app instances
  • managed PostgreSQL (primary + replica/backup strategy)
  • managed Redis (cache/session/realtime pub-sub)
  • OTEL collector + Prometheus scraping (optional but recommended)

Suggested runtime contracts:

EITOHFORGE_APP_ENV=prod
EITOHFORGE_DB_DRIVER=postgresql+psycopg
EITOHFORGE_CACHE_PROVIDER=redis
EITOHFORGE_CACHE_REDIS_URL=redis://redis.internal:6379/0
EITOHFORGE_REALTIME_ENABLED=true
EITOHFORGE_REALTIME_REDIS_URL=redis://redis.internal:6379/2
EITOHFORGE_TENANT_ENABLED=true
EITOHFORGE_RATE_LIMIT_ENABLED=true
EITOHFORGE_REQUEST_SIGNING_ENABLED=true

Operational notes:

  • keep app layer stateless
  • use Redis-backed providers for cross-instance consistency
  • perform zero-downtime deploys with rolling updates and readiness probes

Blueprint C: Kubernetes (multi-env, autoscaling)

Best for: team-scale platform operations and multi-environment delivery.

Typical layout:

  • namespace per environment (dev, staging, prod)
  • Deployment for API app, optional Deployment for workers
  • Service + Ingress for HTTP/WebSocket
  • HPA for API pods
  • Secret/ConfigMap for EITOHFORGE_*
  • external managed Postgres/Redis/OpenSearch

Minimal K8s env strategy:

  • ConfigMap: non-secret settings (feature flags, host/port, toggles)
  • Secret: DB credentials, JWT/request-signing secrets, provider credentials
  • rollout by image tag + env version stamp

WebSocket and realtime in production blueprints

For Blueprint B/C:

  • enable realtime route and JWT requirement:
    • EITOHFORGE_REALTIME_ENABLED=true
    • EITOHFORGE_REALTIME_REQUIRE_ACCESS_JWT=true
  • configure Redis fanout:
    • EITOHFORGE_REALTIME_REDIS_URL=redis://...
  • ensure ingress supports WebSocket upgrades and sane idle timeouts

Database and migration operations in blueprints

Common release flow:

  1. deploy new code with backward-compatible schema reads
  2. run eitohforge db upgrade (or CI/CD migration step)
  3. switch traffic progressively
  4. monitor health/readiness/error/latency dashboards

For multi-tenant schema isolation in Postgres:

EITOHFORGE_TENANT_ENABLED=true
EITOHFORGE_TENANT_DB_SCHEMA_ISOLATION_ENABLED=true
EITOHFORGE_TENANT_DB_SCHEMA_NAME_TEMPLATE={tenant_id}

Security baseline across all blueprints

  • enforce HTTPS redirect and host hardening
  • use strong JWT secret and rotate periodically
  • enable request signing for write-critical APIs
  • enable rate limit + idempotency on mutating routes
  • avoid plaintext secrets in repo; use secret manager/CI secrets

Platform primitives (ecosystem gaps)

These modules address common “framework maturity” gaps: contracts, persistence, providers, and inbound integrations.

Area What to use
Repository contract eitohforge_sdk.domain.BaseRepository / RepositoryContract — SQLAlchemyRepository is the reference implementation.
Response envelopes eitohforge_sdk.application.dto.ok, paginated, err — thin helpers over ApiResponse / PaginatedApiResponse / ApiErrorResponse.
Feature flags + Redis FeatureFlagDefinition.to_mapping / from_mapping, FeatureFlagService.reload, load_definitions_from_redis_json / save_definitions_to_redis_json.
Secrets `EITOHFORGE_SECRET_PROVIDER=env
Inbound webhooks register_inbound_webhook_router — HMAC verification (timestamp-canonical or plain body digest).
SendGrid email build_sendgrid_email_sender + InMemoryNotificationGateway.register_sender("email", sender).
Policy registry PolicyRegistry — register named AccessPolicy instances for composition and future DSL hooks.
Multi-engine DB routing EngineRegistry — named SQLAlchemy engines; for logical roles + DatabaseProvider, see infrastructure.database.registry.DatabaseRegistry.
CLI provider stub eitohforge create provider <name> --path . — scaffolds app/providers/<name>.py.

Appendix: Full Feature & Operations Reference

The section below inlines the repository’s multi-page guides and the architecture spec so PyPI visitors get a single, self-contained reference.

Usage Complete (end-to-end reference)

EitohForge — Complete Usage Guide

End-to-end reference for installing the SDK/CLI, configuring services, and operating generated applications.

1) Install

From source (development)

git clone https://github.com/eitoh-brand/EitohForge.git
cd EitohForge
uv pip install -e ".[dev]"
eitohforge --help

From an internal package index

pip install eitohforge

Verify:

eitohforge version
python -c "import eitohforge_sdk; print('ok')"

2) Create a project

SDK-first (default) — generated apps depend on eitohforge / eitohforge-sdk for core middleware and primitives:

eitohforge create project my_service

Profile — default standard (most platform features on in .env.example). Use --profile minimal for a slimmer default and enable features via env when needed (see docs/guides/forge-profiles.md).

Standalone — self-contained copies of SDK patterns inside the repo (no runtime SDK dependency):

eitohforge create project my_service --mode standalone

Add a CRUD module

cd my_service
eitohforge create crud orders --path .

3) Configuration

  • All runtime settings use the EITOHFORGE_* prefix (see generated .env.example).
  • Layered files: .env, then .env.local, then process environment (see pydantic-settings model config in AppSettings).
  • Production: set EITOHFORGE_APP_ENV to dev, staging, or prod and supply a real EITOHFORGE_AUTH_JWT_SECRET (local allows the placeholder).

Environments (EITOHFORGE_APP_ENV)

Built-in values (validated in AppSettings): local, dev, staging, prod. Pick one per deployment; the capability profile’s deployment block reflects derived hints (see resolve_environment_behavior in the SDK).

Operational “new environment” (no code change): provision a new target (namespace, cluster stage, etc.) and give it its own secrets and env file or secret store — e.g. .env.staging, CI variables for uat, Helm values — still setting EITOHFORGE_APP_ENV to one of the built-in values. Many teams map UAT to staging so behavior stays “pre-production-like” without a separate enum.

New named stage (e.g. uat as its own label): today requires extending the app_env type in AppSettings (and the generated app/core/config.py template) plus updating resolve_environment_behavior() and any validators that branch on app_env. That is a small SDK/template change, not something toggled from env alone.

Key groups:

Area Prefix Notes
App EITOHFORGE_APP_ name, env, log level
Database EITOHFORGE_DB_ SQLAlchemy URL pieces. Postgres: default driver=postgresql+psycopg. MySQL: EITOHFORGE_DB_DRIVER=mysql+pymysql, EITOHFORGE_DB_PORT=3306 (typical), name = database name. SQLite: EITOHFORGE_DB_DRIVER=sqlite (or sqlite+pysqlite), EITOHFORGE_DB_NAME=:memory: or path to .db file.
API versioning EITOHFORGE_API_VERSION_ DEPRECATE_V1, optional V1_SUNSET_HTTP_DATE, V1_LINK_DEPRECATION for /v1 deprecation headers (see cookbook).
Realtime cluster EITOHFORGE_REALTIME_ REDIS_URL enables cross-worker broadcast fan-out; optional REDIS_BROADCAST_CHANNEL (default eitohforge:realtime:broadcast).
Auth EITOHFORGE_AUTH_ JWT secret, token TTL
Cache EITOHFORGE_CACHE_ Redis vs memory
Tenant EITOHFORGE_TENANT_ isolation rules (+ optional Postgres schema isolation via EITOHFORGE_TENANT_DB_SCHEMA_ISOLATION_ENABLED and EITOHFORGE_TENANT_DB_SCHEMA_NAME_TEMPLATE).
Feature flags EITOHFORGE_FEATURE_FLAGS_ endpoint path, enable
Security hardening EITOHFORGE_SECURITY_HARDENING_ hosts, max body, headers
Observability EITOHFORGE_OBSERVABILITY_ request logging/metrics/tracing; optional Prometheus /metrics + OTEL OTLP traces.
Secret management EITOHFORGE_SECRET_ secret provider selection (env / vault / aws / azure). Vault reads KV values on each get (no client-side caching), so rotations are picked up naturally; Vault token comes from VAULT_TOKEN (or EITOHFORGE_SECRET_VAULT_TOKEN fallback).

Capability discovery for clients:

  • GET /sdk/capabilities — enabled features and header names.
  • GET /sdk/feature-flags — evaluated flags for the current request context.
  • WebSocket — generated apps expose /realtime/ws when EITOHFORGE_REALTIME_ENABLED=true (JWT handshake, rooms, broadcast). See docs/guides/realtime-websocket.md.

4) Migrations (Alembic)

Generated projects include migrations/ and alembic.ini.

cd my_service
eitohforge db init          # first-time
eitohforge db migrate -m "message"
eitohforge db upgrade
eitohforge db current

CI enforces migration policy via scripts/check_migration_policy.py (destructive changes require an explicit approval marker).

5) Authentication and authorization

  • JWT: JwtTokenManager (access/refresh, rotation) — see app.core.auth in generated apps.
  • Sessions: Redis-backed session manager with revocation hooks.
  • RBAC: require_roles dependency from headers (x-roles, x-actor-id).
  • ABAC: policy engine and require_policies for tenant-aware routes.
  • SSO: SsoBroker with OIDC/SAML adapters (OidcSsoProvider, SamlSsoProvider).

6) Plugins and extension

  • Implement a PluginModule (name + optional register_routes / register_providers / register_events).
  • Register with PluginRegistry and call apply(...) during startup.

7) Deploy and operate

  • Health: GET /health, GET /ready, GET /status.
  • Runbook: docs/guides/operations-runbook.md.
  • TLS / LB / rollout: docs/guides/tls-and-cert-rotation-runbook.md, load-balancing-and-health-routing.md, deployment-strategies-and-rollback-controls.md.

Container-style run (example):

uvicorn app.main:app --host 0.0.0.0 --port 8000

8) Packaging and release

  • Build: python -m build (reproducibility checks in CI).
  • Publish: internal workflow publish-internal.yml; optional PyPI publish-pypi.yml.
  • Details: docs/guides/python-packaging-and-publishing.md.

9) Troubleshooting

Symptom Check
Startup fails on config Env vars and AppSettings validators (EITOHFORGE_APP_ENV, JWT secret).
403 on writes Tenant middleware: x-tenant-id / EITOHFORGE_TENANT_*.
429 responses Rate limit headers and EITOHFORGE_RATE_LIMIT_*.
401 on signed APIs Request signing secret and clock skew (EITOHFORGE_REQUEST_SIGNING_*).
DB connection errors EITOHFORGE_DB_*, driver (postgresql+psycopg, mysql+pymysql, sqlite), port (3306 vs 5432), and network reachability.
Import errors in SDK mode pip install eitohforge and matching version in generated pyproject.toml.

10) Reference examples

  • Minimal: examples/example-minimal/ — capabilities + health.
  • Enterprise-style: examples/example-enterprise/ — hardening, observability, tenant, flags, health family.

See each example’s README.md for run and test commands.

11) Further reading

  • docs/guides/cookbook.md
  • docs/guides/realtime-websocket.md
  • docs/guides/forge-profiles.md (includes forge_platform_toggles_uniform)
  • docs/guides/query-spec-reference.md — QuerySpec operators and SQLAlchemyRepository behavior
  • Repository root secure_backend_sdk_architecture.md — specification; see its appendix for implementation coverage vs §1–§44
  • docs/guides/enterprise-readiness-checklist.md
  • docs/guides/testing-and-example-project-strategy.md
  • docs/roadmap/architecture-coverage-matrix.md

Cookbook (recipes)

EitohForge Cookbook

Practical recipes for common implementation patterns.

1) Enable Strict Tenant Isolation

Set:

  • EITOHFORGE_TENANT_ENABLED=true
  • EITOHFORGE_TENANT_REQUIRED_FOR_WRITE_METHODS=true
  • EITOHFORGE_TENANT_RESOURCE_TENANT_HEADER=x-resource-tenant-id

Behavior:

  • write methods without tenant context are denied (403)
  • cross-tenant access via mismatched resource tenant header is denied (403)

2) Add a Plugin Module

Implement a plugin object with a unique name, optionally:

  • register_routes(app)
  • register_providers(registry)
  • register_events(registry)

Register it with PluginRegistry.register(plugin) and apply with PluginRegistry.apply(...).

3) Roll Out a Feature Gradually

Use FeatureFlagService and register:

  • FeatureFlagDefinition(key="new-ui", rollout_percentage=10)

Then evaluate with actor/tenant context:

  • FeatureFlagTargetingContext(actor_id="actor-1", tenant_id="tenant-a")

Expose runtime values via register_feature_flags_endpoint(app).

4) Harden HTTP Surface

Use register_security_hardening_middleware with SecurityHardeningRule to:

  • enforce max request size
  • restrict allowed hosts
  • set strict response security headers

5) Baseline and Check Performance

Generate baseline:

  • uv run python scripts/performance_baseline.py --mode baseline

Run regression check:

  • uv run python scripts/performance_baseline.py --mode check --threshold 25

6) Realtime WebSocket (generated apps)

  • Ensure EITOHFORGE_REALTIME_ENABLED=true (default).
  • Connect to /realtime/ws with a valid access JWT (?token=... or Authorization: Bearer ...).
  • Use JSON frames: join / leave / broadcast / direct / presence / ping — see docs/guides/realtime-websocket.md.
  • Single worker: default in-memory hub only.
  • Multi-worker (EITOHFORGE_REALTIME_REDIS_URL): RedisFanoutSocketHub PUBLISHes each client broadcast and direct to peers; presence / room_members stay per process. Private “rooms” are a naming convention only; direct targets actor_id (JWT subject) and does not enforce authorization—see realtime-websocket.md.
  • Manual two-worker check: run Redis; start two Uvicorn processes with the same EITOHFORGE_REALTIME_REDIS_URL; connect WebSockets on different workers, join the same room, broadcast from one — the other should receive the event. Expect each worker’s presence to list only its local connections.

7) Deprecate /v1 with HTTP headers

build_forge_app registers deprecation middleware automatically. Enable with:

  • EITOHFORGE_API_VERSION_DEPRECATE_V1=true
  • Optional EITOHFORGE_API_VERSION_V1_SUNSET_HTTP_DATE (e.g. Sat, 31 Dec 2026 23:59:59 GMT)
  • Optional EITOHFORGE_API_VERSION_V1_LINK_DEPRECATION (URL for Link: <...>; rel="deprecation")

Responses for paths starting with /v1 then include Deprecation: true plus Sunset / Link when set.

8) Versioned OpenAPI documents

FastAPI exposes one root OpenAPI by default. For separate OpenAPI per major version, mount sub-applications:

from fastapi import FastAPI

root = FastAPI()
v1_app = FastAPI(title="API v1", openapi_url="/openapi.json")
v2_app = FastAPI(title="API v2", openapi_url="/openapi.json")
root.mount("/v1", v1_app)
root.mount("/v2", v2_app)

Clients then use /v1/openapi.json and /v2/openapi.json. Combine with register_versioned_routers on each sub-app or include routers manually.

9) Event bus: local + Redis publish

  • In-process: InMemoryEventBus from eitohforge_sdk.infrastructure.messaging.
  • Cross-process fan-out: build_redis_publishing_event_bus(redis_url="redis://localhost:6379/0") implements EventBus; publish notifies local subscribers and PUBLISHes JSON to eitohforge:evt:{event_name}.

Other workers must run a Redis SUBSCRIBE loop (or use a task queue) to consume those messages; the SDK does not start a background subscriber in the web process.

10) Observability: Prometheus + OTEL

Prometheus metrics (/metrics)

  • Enable: EITOHFORGE_OBSERVABILITY_ENABLE_PROMETHEUS=true
  • Path: EITOHFORGE_OBSERVABILITY_PROMETHEUS_METRICS_PATH (default: /metrics)

Request metrics are exported using a per-app Prometheus registry:

  • eitohforge_http_requests_total{method,path,status}
  • eitohforge_http_requests_duration_ms{method,path,status}

OTEL tracing

  • Enable: EITOHFORGE_OBSERVABILITY_OTEL_ENABLED=true
  • Service name: EITOHFORGE_OBSERVABILITY_OTEL_SERVICE_NAME (default: eitohforge)
  • OTLP traces over HTTP (optional): EITOHFORGE_OBSERVABILITY_OTEL_OTLP_HTTP_ENDPOINT

When enabled, responses include x-trace-id (derived from the active OTEL span context when available).

Forge Profiles

Forge scaffold profiles and feature toggles

CLI profiles (create project)

eitohforge create project my_api --profile standard   # default
eitohforge create project my_api --profile minimal      # most platform features off in `.env.example`
  • standard — typical enterprise defaults (tenant, rate limit, observability, audit, realtime WebSocket, feature flags, etc. enabled in the generated .env.example).
  • minimal — the same codebase layout, but .env.example starts with most optional middleware disabled. Turn features on by setting the matching EITOHFORGE_*_ENABLED (or related) variables to true and redeploying.

Runtime behavior always follows loaded settings (AppSettings), not the profile name, after you copy .env.example → .env.

build_forge_app toggles (SDK)

For SDK-only apps, use ForgeAppBuildConfig.toggles (ForgePlatformToggles) to override each layer without changing environment:

  • Each field is True | False | None.
  • None means “use AppSettings” (e.g. rate_limit.enabled).
  • False forces that layer off even if env says on; True forces it on.
from eitohforge_sdk.core import ForgeAppBuildConfig, ForgePlatformToggles, build_forge_app

app = build_forge_app(
    build=ForgeAppBuildConfig(
        toggles=ForgePlatformToggles(
            rate_limit=False,
            realtime_websocket=False,
            https_redirect=False,
        ),
    )
)

Other toggle keys match platform concerns: security_hardening, audit, observability, request_signing, idempotency, tenant, security_context, cors, health, capabilities, feature_flags, realtime_websocket, https_redirect.

wire_realtime_websocket=False on ForgeAppBuildConfig skips mounting /realtime/ws entirely (in addition to toggles).

Uniform toggle (all layers on or off)

To force every ForgePlatformToggles field to the same value (overriding AppSettings for each wired layer), use:

from eitohforge_sdk.core import ForgeAppBuildConfig, build_forge_app, forge_platform_toggles_uniform

app = build_forge_app(
    build=ForgeAppBuildConfig(
        toggles=forge_platform_toggles_uniform(enabled=False),
        wire_realtime_websocket=False,
    )
)

Use enabled=True only when you intentionally want all toggled layers on regardless of env. wire_* flags on ForgeAppBuildConfig are separate: set them explicitly if you need to skip router families entirely.

Environment flags (auth, HTTPS, WebSocket)

Concern Variables
JWT issuance/validation for HTTP and WS EITOHFORGE_AUTH_JWT_ENABLED (default true)
WebSocket endpoint EITOHFORGE_REALTIME_ENABLED
Require access JWT on /realtime/ws EITOHFORGE_REALTIME_REQUIRE_ACCESS_JWT (if true and realtime on, AUTH_JWT_ENABLED must be true)
Redirect HTTP→HTTPS (app-level; TLS usually terminates at proxy) EITOHFORGE_RUNTIME_ENFORCE_HTTPS_REDIRECT
CORS EITOHFORGE_RUNTIME_CORS_ALLOW_ORIGINS, etc.

GET /sdk/capabilities exposes auth, runtime, and realtime blocks for clients.

Realtime WebSocket Guide

Realtime WebSocket (/realtime/ws)

Generated apps register a first-class WebSocket endpoint when EITOHFORGE_REALTIME_ENABLED=true (default).

Handshake

  • EITOHFORGE_REALTIME_REQUIRE_ACCESS_JWT (default true): when false, connections are accepted without a token (anonymous actor_id); optional JWT still upgrades the principal when EITOHFORGE_AUTH_JWT_ENABLED=true.
  • When require_access_jwt is true, a JWT access token is required before messages are accepted (and EITOHFORGE_AUTH_JWT_ENABLED must be true).
  • Pass the token as query ?token=<access_jwt> and/or Authorization: Bearer <access_jwt> (query wins if both are set — see extract_socket_token).

Hub

When EITOHFORGE_REALTIME_REDIS_URL is unset, the hub is InMemorySocketHub on app.state.socket_hub (single process). When set, build_forge_app uses RedisFanoutSocketHub: broadcast and direct traffic fan out across workers via Redis; presence / room membership stay per process (see cookbook).

Private channels vs direct messages

Mechanism What the SDK does What your app must do
Room “privacy” None — any client can join any room name string. Encode tenancy or secrecy in room naming (e.g. tenant:{id}:orders) and enforce policy in HTTP APIs or custom middleware before exposing room names.
type: "direct" Delivers to all WebSocket connections whose actor_id matches target_actor_id (JWT subject by default). Works across workers when Redis is enabled. Does not encrypt payloads or prove the recipient’s tenant; authorization (who may message whom) is application-owned. Enforce ABAC/RBAC in services or reject sensitive target_actor_id values server-side if you add hooks later.

Not supported by the SDK: end-to-end encryption, read receipts, or guaranteed offline delivery. Use app-level queues or push for those.

Client JSON protocol (text frames)

type Fields Server response
ping — { "type": "pong" }
join room (string) { "type": "joined", "room", "ok" }
leave room { "type": "left", "room", "ok" }
broadcast room, event, optional payload object Others in room get { event, room, payload, occurred_at }; caller gets { "type": "broadcast_result", "delivered" } (sender excluded from broadcast)
presence room { "type": "presence_result", "connection_ids", "by_actor" }
direct target_actor_id, event, optional payload Recipients: { event, room: "__direct__", payload, occurred_at, from_actor_id, target_actor_id }. Sender: { "type": "direct_result", "target_actor_id", "delivered" }. Requires non-anonymous actor_id.

Malformed JSON or unknown type returns { "type": "error", "code", "message" }.

Capabilities

GET /sdk/capabilities includes features.realtime_websocket and a realtime object with websocket_path, hub_kind (in_memory or redis_fanout), and direct_to_actor_supported.

Query Spec Reference

Query spec reference (QuerySpec / SQLAlchemyRepository)

This document is the contract for eitohforge_sdk.application.dto.repository.QuerySpec as applied by eitohforge_sdk.infrastructure.repositories.sqlalchemy_repository.SQLAlchemyRepository. It aligns with blueprint §6 Query specification engine for the SQL path.

Filter operators

Operator Value shape SQLAlchemy behavior
eq scalar column == value
ne scalar column != value
gt, gte, lt, lte scalar Comparison on the mapped column
contains string (typical) column.contains(value)
startswith string column.startswith(value)
endswith string column.endswith(value)
between sequence of exactly two elements column.between(lo, hi); invalid length → filter skipped
in non-string sequence column IN (...); empty sequence → matches no rows (false())
not_in non-string sequence column NOT IN (...); empty sequence → no filter (all rows pass this predicate)
exists boolean True → IS NOT NULL, False → IS NULL on the column (not a SQL EXISTS subquery)

Strings are not valid in / not_in values (use a one-element tuple or list). Unknown field names are silently ignored (no row filter applied for that condition). To fail fast, call validate_query_filters_against_columns from eitohforge_sdk.application.query_spec_support.

Sorting

SortSpec: field must exist on the model; unknown fields are skipped. Multiple sorts apply in order.

Pagination

Mode Behavior
offset OFFSET + LIMIT from pagination.offset and page_size.
cursor If cursor is numeric, used as offset; else falls back to offset.
keyset Uses first applicable sort (or id ascending); cursor is compared to the sort column (> / < for asc/desc).

Code

from eitohforge_sdk.application import validate_query_filters_against_columns
from eitohforge_sdk.application.dto.repository import FilterCondition, FilterOperator, QuerySpec

validate_query_filters_against_columns(
    query,
    valid_columns={"id", "name", "email", "tenant_id", "score"},
)

Related

  • DTO definitions: src/eitohforge_sdk/application/dto/repository.py
  • Implementation: src/eitohforge_sdk/infrastructure/repositories/sqlalchemy_repository.py
  • Tests: tests/unit/test_sqlalchemy_repository.py, tests/unit/test_query_spec_support.py

Operations Runbook

EitohForge Operations Runbook

Operational baseline for deployment, rollback, and reliability governance.

1) Deployment Workflow

  • CI quality gates must pass (ruff, mypy, pytest, migration policy).
  • Package build must pass reproducibility and metadata checks.
  • Security/compliance gates must pass (pip-audit, SBOM, license policy).
  • Publish to internal registry first (publish-internal.yml).
  • Promote to production release through environment approvals.

2) Release Environments

  • dev: automatic deploy after merge to protected branch.
  • staging: deploy candidate from internal registry and run smoke suite.
  • prod: manual approval required; use release artifact already validated in staging.

3) Rollback Procedure

  1. Identify target previous version from internal registry.
  2. Trigger rollback deployment with previous version pin.
  3. Confirm /ready and /status endpoints report healthy.
  4. Validate core API smoke suite and critical business paths.
  5. Open post-incident record with root cause and corrective action.

4) Incident Severity and Response

  • SEV-1: full outage or data integrity risk, page immediately.
  • SEV-2: degraded service with customer impact.
  • SEV-3: minor degradation or non-critical feature issue.

Escalation path:

  • On-call engineer -> platform owner -> engineering lead.

5) SLO and Error Budget Baseline

  • Availability SLO: 99.9% monthly for API endpoints.
  • p95 latency SLO: < 300ms for core read/write paths.
  • Error rate SLO: < 0.5% 5xx over rolling 30 minutes.

Error budget:

  • Monthly downtime budget for 99.9%: ~43.8 minutes.
  • If budget burn exceeds 50% mid-cycle, freeze non-critical releases.

6) Monitoring and Alerting

  • Use telemetry from observability middleware and health endpoints:
    • /health
    • /ready
    • /status
  • Alert on:
    • sustained 5xx elevation
    • SLO burn-rate threshold breach
    • readiness check failures

7) Change Management Policy

  • No direct production deploy from untagged commits.
  • Every production release must map to immutable artifacts.
  • Schema migrations must be backward-compatible for rolling deployments.

8) Operational Checklists

Pre-Deploy Checklist

  • Release artifact built in CI with reproducibility checks
  • Vulnerability and license checks green
  • Migration plan reviewed
  • Rollback candidate confirmed

Post-Deploy Checklist

  • Readiness/health green
  • No elevated error budget burn
  • Key user journeys validated
  • Incident channel quiet for 30 minutes

9) Network and Deployment References

  • docs/guides/tls-and-cert-rotation-runbook.md
  • docs/guides/mtls-trust-model.md
  • docs/guides/load-balancing-and-health-routing.md
  • docs/guides/deployment-strategies-and-rollback-controls.md

Architecture Spec + Implementation Map

Below is the complete A–Z backend architecture verdict for your reusable FastAPI-based enterprise SDK framework. This document defines the final blueprint for a low-code, pluggable, production-grade backend platform that can bootstrap any modern API system (ERP, SaaS, tracking platform, trading infra, multiplayer backend, automation stack, etc.).

You can treat this as the specification document for your backend SDK.

Backend SDK Architecture — Complete A to Z Blueprint

Objective

Build a reusable backend framework that:

  • generates clean architecture automatically
  • supports SQL + NoSQL interchangeably
  • enables security middleware on demand
  • integrates communication services
  • supports SSO and identity federation
  • handles sessions, storage, caching, sockets
  • supports multi-tenant SaaS systems
  • provides CRUD scaffolding
  • allows plugin-based extensions
  • minimizes boilerplate coding

Target outcome:

secureapi create project my_service

→ production-ready backend instantly

1. Core Architectural Philosophy

Use layered clean architecture:

Presentation Layer
Application Layer
Domain Layer
Infrastructure Layer
Core Layer

Responsibilities:

Layer Role
Presentation routers/controllers
Application use-cases
Domain entities/business logic
Infrastructure DB/storage/cache
Core config/security/providers

2. Project Auto-Generated Folder Structure

app/

  main.py

  core/
    config.py
    dependencies.py
    middleware.py
    security.py
    lifecycle.py

  domain/
    entities/
    repositories/
    specifications/

  application/
    use_cases/
    requests/
    responses/
    services/

  infrastructure/
    database/
    cache/
    storage/
    messaging/

  presentation/
    routers/
    controllers/

  modules/
    auth/
    users/

tests/

3. Configuration System (Central Control Engine)

Single config entrypoint:

BackendSDKConfig(
    database="postgres",
    orm="tortoise",
    cache="redis",
    storage="s3",
    enable_sessions=True,
    enable_signature=True,
    enable_socket=True,
    enable_sso=True
)

Controls everything dynamically.

4. Database Layer (Polyglot Persistence Support)

Supports:

DB Use
Postgres transactional
MySQL legacy
SQLite local/dev
MongoDB document
Elastic search
Redis cache/session
Clickhouse analytics

Architecture:

DatabaseRegistry
RepositoryFactory
TransactionManager
SpecificationEngine

Example:

UserRepository → Postgres
AuditRepository → Mongo
SearchRepository → Elastic

5. Generic Repository Abstraction

Universal interface:

create()
get()
update()
delete()
list()
bulk_create()
paginate()

Adapters:

SQLRepository
MongoRepository
ElasticRepository
RedisRepository

Service layer never changes across DB engines.

6. Query Specification Engine

Unified filter interface:

Filter(field="age", operator="gt", value=18)

Supports:

eq
ne
gt
gte
lt
lte
contains
startswith
endswith
between
exists

Works across SQL and Mongo automatically.

7. CRUD Auto Generator

CLI:

secureapi create crud product

Creates:

entity
repository
service
schema
router
tests

Endpoints auto-generated:

POST
GET
GET/{id}
PUT/{id}
DELETE

8. Request / Response Model System

Never allow raw dictionaries.

Structure:

Request Models
Domain Entities
Response Models
Envelope Models

Standard response:

ApiResponse[T]

Example:

success
data
message
error_code
meta

9. Pagination Engine

Supports:

offset pagination
cursor pagination
keyset pagination

Response:

PaginatedResponse[T]

10. Authentication System

Supports:

JWT access tokens
refresh token rotation
device binding
session tracking
token revocation

Session store options:

Redis
Postgres
Memory

11. Session Management Engine

Supports:

multi-device login
logout single session
logout all sessions
concurrent session limits
socket session sync

Session model:

session_id
device_id
user_id
expires_at
ip_address

12. Role-Based Access Control (RBAC)

Example:

admin
manager
user
viewer

Decorator:

@requires_permission("invoice.approve")

13. Attribute-Based Access Control (ABAC)

Example:

user.department == resource.department

Policy engine:

@policy("can_edit_profile")

14. Identity Federation & SSO

Supports:

Google
Microsoft
Apple
Facebook
Azure AD
Okta
Keycloak
SAML
OIDC

Flow:

External provider
→ Identity Broker
→ Internal user mapping
→ Internal JWT issued

Multi-tenant SSO routing supported.

15. Session + JWT Unified Identity Model

Architecture:

Access Token → Stateless
Refresh Token → Stateful
Session Store → Revocation Control

16. Storage Abstraction Layer

Providers:

Local storage
AWS S3
Azure Blob
MinIO
GCS

Unified interface:

upload()
download()
delete()
exists()
generate_url()

17. Presigned URL Engine

Supports:

upload URLs
download URLs
temporary access URLs

Example:

generate_presigned_upload()

18. Storage Access Policies

Examples:

private
public
owner-only
team-visible
tenant-scoped

19. CDN Integration Layer

Supports:

CloudFront
Cloudflare
Azure CDN

Auto URL generation:

storage.public_url()

20. Distributed Cache Layer

Providers:

Redis
Memory
Memcached

Supports:

TTL
tag invalidation
prefix invalidation
lazy caching
write-through caching

Decorator:

@cached(ttl=60)

21. Rate Limiting Engine

Supports:

per-user
per-IP
per-endpoint
per-role

Example:

@rate_limit("10/minute")

22. Notification Gateway Layer

Unified interface:

send_email()
send_sms()
send_whatsapp()
send_push()
send_template()

Providers:

SES
SendGrid
SMTP
Twilio
MSG91
Meta WhatsApp
Firebase
SNS

23. Template Messaging Engine

Supports:

local templates
database templates
S3 templates
multi-language templates

Example:

send_template("otp_sms")

24. Background Job Engine

Providers:

Celery
Redis Queue
Dramatiq
Kafka

Example:

@background_task

Supports:

retry
cron
delay
batch execution

25. External API Client Framework

Unified integration layer:

ExternalServiceClient

Features:

retry policies
timeouts
circuit breakers
logging
auth injection
rate control

Example:

maps.get_distance()
payments.create_order()

26. Webhook Framework

Supports:

signature verification
event routing
retries
dead-letter queues

Example:

@webhook_handler("payment.success")

27. Event Bus Architecture

Example:

UserCreatedEvent

Handlers:

SendWelcomeEmailHandler
CreateAuditLogHandler
AssignPermissionsHandler

28. Multi-Database Support

Registry:

primary DB
analytics DB
document DB
search DB
cache DB

Usage:

db_registry.get("analytics")

29. Distributed Transaction Support

Supports:

local transactions
saga orchestration
event-driven consistency

30. Search Engine Integration

Providers:

ElasticSearch
OpenSearch
MeiliSearch

Example:

search.index()
search.query()

31. Audit Logging Engine

Tracks:

login
logout
CRUD changes
file uploads
permission updates
session revocation

Example:

audit.log("USER_UPDATED")

32. Security Middleware Stack

Optional modules:

signature validation
nonce validation
device binding
token blacklist
IP restriction
geo restriction
rate limiting

33. Request Signing Engine

Headers:

X-Timestamp
X-Nonce
X-Signature

Protects:

replay attacks
tampering
automation abuse

34. Capability Negotiation Endpoint

Expose:

/sdk/capabilities

Example:

signature_required
nonce_required
device_binding_required

Used by client SDK auto-sync.

35. Multi-Tenant Architecture Support

Supports:

schema-per-tenant
row-level filtering
storage isolation
cache isolation
identity isolation

Implementation note: schema-per-tenant uses Postgres search_path (EITOHFORGE_TENANT_DB_SCHEMA_ISOLATION_ENABLED=true) with the resolved tenant id interpolated into EITOHFORGE_TENANT_DB_SCHEMA_NAME_TEMPLATE.

36. Plugin System

Allows external modules to register:

routes
middlewares
schemas
providers
event handlers

Example:

register_plugin(InventoryPlugin)

37. Metrics & Observability

Exports:

latency
error rate
query time
cache hit rate
socket connections

Integrations:

Prometheus
Grafana
OpenTelemetry

38. Health Monitoring Endpoints

Auto-generated:

/health
/status
/metrics

Checks:

database
redis
storage
queue
search

39. Secret Management Layer

Providers:

environment variables
vault
AWS secrets manager
Azure key vault

Usage:

secret.get("API_KEY")

40. Unified Security Context Object

Accessible globally:

SecurityContext

Contains:

user
roles
permissions
session
device
tenant

Usage:

SecurityContext.current_user()

41. Socket Infrastructure

Supports:

JWT auth
rooms
presence tracking
broadcast messaging
private messaging
session sync

42. Versioned API Engine

Supports:

/v1/users
/v2/users

Backward compatibility maintained automatically.

43. Idempotency Engine

Header:

X-Idempotency-Key

Prevents duplicate operations.

44. Feature Flag System

Example:

feature_flags.is_enabled("new_dashboard")

Supports staged rollouts.

Final Result

This backend SDK becomes a complete application platform capable of powering:

  • ERP systems
  • SaaS platforms
  • tracking apps
  • trading automation
  • multiplayer engines
  • document platforms
  • notification hubs
  • identity providers
  • integration middleware

with minimal per-project coding.

If you want the next step, I can produce the module-by-module implementation roadmap (build order + priorities) so you can start developing this SDK systematically instead of all at once.

I created a downloadable Markdown architecture document for your backend SDK:

Download here: Secure Backend SDK Architecture Blueprint

Implementation Plan (Practical Build Roadmap)

Below is the recommended phased execution strategy to actually build this backend platform without chaos. Follow this order; each phase unlocks the next layer cleanly.

Phase 0 — Foundation (Week 1)

Goal: Core framework skeleton + config engine

Build:

1. Project generator CLI

Command:

secureapi create project <name>

Creates:

core/
domain/
application/
infrastructure/
presentation/
modules/

Tools to use:

  • typer (CLI)
  • jinja2 (templates)
  • cookiecutter-style scaffolding

2. BackendSDKConfig

Single control object:

BackendSDKConfig(
    database="postgres",
    orm="tortoise",
    cache="redis",
    storage="s3",
    enable_auth=True
)

Everything reads from this.

3. ProviderFactory

Core abstraction engine:

DatabaseProvider
CacheProvider
StorageProvider
NotificationProvider
AuthProvider

Factory resolves implementations dynamically.

Phase 1 — Database Abstraction Layer (Week 2)

Goal: SQL + Mongo interchangeable CRUD

Implement:

BaseRepository

create()
get()
update()
delete()
list()
paginate()

Adapters:

SQLRepository
MongoRepository

Add:

Filter
Sort
Pagination
Specification
TransactionManager

Now DB becomes swappable instantly.

Phase 2 — Response Envelope + Error System (Week 2)

Create:

ApiResponse[T]
PaginatedResponse[T]
ErrorResponse

Add:

ExceptionMiddleware
ErrorRegistry

Standardizes entire API contract.

Phase 3 — Auth + Session Engine (Week 3)

Implement:

JWTManager

create_access_token()
create_refresh_token()
verify_token()

SessionManager

Supports:

multi-device login
revoke session
revoke all sessions
session tracking

Storage:

RedisSessionProvider
DBSessionProvider

Phase 4 — RBAC + ABAC (Week 3)

Create:

RoleManager
PermissionManager
PolicyEngine

Decorators:

@requires_permission()
@policy()

Attach automatically via middleware.

Phase 5 — Storage Engine + Presigned URLs (Week 4)

Implement:

StorageProvider

Adapters:

Local
S3
Azure Blob
MinIO

Add:

generate_presigned_upload()
generate_presigned_download()

Phase 6 — Cache Engine (Week 4)

Create:

CacheProvider

Adapters:

Redis
Memory
Memcached

Add decorator:

@cached(ttl=60)

Phase 7 — CRUD Generator (Week 5)

CLI:

secureapi create crud user

Generates:

entity
schema
repository
service
router
tests

Huge productivity multiplier.

Phase 8 — Notification Gateway (Week 6)

Create:

NotificationProvider

Adapters:

SES
SendGrid
SMTP
Twilio
MSG91
WhatsApp
Firebase

Add:

template engine
queue support
localization support

Phase 9 — External API Client Framework (Week 6)

Create:

ExternalServiceClient

Features:

retry
timeout
circuit breaker
auth injectors
logging

Example:

maps_client
razorpay_client
digilocker_client

Phase 10 — SSO Engine (Week 7)

Create:

SSOProvider
IdentityBroker

Adapters:

Google
Microsoft
Apple
Okta
Azure AD
SAML
OIDC

Flow:

external login → internal JWT issued

Phase 11 — Multi-Database Registry (Week 7)

Enable:

primary DB
analytics DB
document DB
search DB

Example:

db_registry.get("analytics")

Supports polyglot persistence.

Phase 12 — Event Bus + Background Jobs (Week 8)

Create:

EventBus
BackgroundTaskProvider

Adapters:

Celery
RedisQueue
Dramatiq
Kafka

Example:

UserCreatedEvent

Triggers handlers automatically.

Phase 13 — Webhook Framework (Week 8)

Add:

WebhookManager

Supports:

signature verification
retry queue
routing
DLQ

Phase 14 — Security Middleware Stack (Week 9)

Implement optional modules:

SignatureMiddleware
NonceMiddleware
DeviceBindingMiddleware
RateLimitMiddleware
GeoRestrictionMiddleware

Controlled via config flags.

Phase 15 — Capability Negotiation Endpoint (Week 9)

Expose:

/sdk/capabilities

Used by Flutter SDK auto-sync.

Example response:

signature_required
nonce_required
device_binding_required

Phase 16 — Plugin System (Week 10)

Create:

PluginRegistry

Plugins can register:

routes
middleware
providers
schemas
events

Example:

register_plugin(InventoryPlugin)

Phase 17 — Observability + Health Monitoring (Week 10)

Add:

Endpoints:

/health
/status
/metrics

Integrations:

Prometheus
Grafana
OpenTelemetry

Phase 18 — Multi-Tenant Engine (Week 11)

Support:

tenant DB schema isolation
tenant cache namespace
tenant storage prefix
tenant SSO mapping

Expose:

TenantContext.current()

Final Result After These Phases

You will have a reusable backend platform comparable in capability to:

  • NestJS (Node)
  • Spring Boot (Java)
  • ASP.NET Core (C#)

—but optimized for FastAPI and mobile-first architectures.

Appendix — EitohForge implementation map (living)

This blueprint predates the eitohforge CLI and eitohforge_sdk package. The target command line for the shipped product is:

eitohforge create project <name> [--profile standard|minimal]

not secureapi create. The table below maps blueprint sections (§1–§44) to the current repository state. Implemented means a usable baseline exists in tree; Partial means the idea is present but narrower than the blueprint; Planned / gap means not yet aligned with the spec.

§ Blueprint topic Status Notes
1 Layered clean architecture Implemented Templates + SDK modules follow presentation / application / domain / infrastructure / core.
2 Generated folder structure Implemented eitohforge create project scaffolds app/ layout consistent with the blueprint.
3 Central configuration Partial AppSettings (pydantic-settings, EITOHFORGE_*) replaces the sample BackendSDKConfig API; feature toggles via env, ForgePlatformToggles, forge_platform_toggles_uniform, and ForgeAppBuildConfig.wire_*.
4 Polyglot persistence Partial Postgres, MySQL (MySQLProvider, mysql+pymysql, pymysql), SQLite in factory + registry roles. DatabaseSettings.sqlalchemy_url covers all three. Mongo etc. still out of scope.
5 Generic repository Implemented RepositoryContract (Protocol) + SqlalchemyRepository adapter.
6 Query specification Partial QuerySpec + SQLAlchemyRepository document and tests in docs/guides/query-spec-reference.md (blueprint §6 operators on SQL path; extensions in / not_in). Optional validate_query_filters_against_columns. Not a Mongo/document engine or standalone query DSL beyond this.
7 CRUD auto generator Partial eitohforge create crud ships richer field types (optional text, int, bool, datetime, FK-style parent_resource_id) + golden tests; still in-memory service stub, not full SQL CRUD codegen per entity.
8–9 Request/response + pagination Implemented DTOs (ApiResponse, pagination types) in application layer.
10–15 Auth, session, RBAC, ABAC, SSO, JWT+session Implemented / Partial JWT, session stores, RBAC helpers, ABAC PolicyEngine, OIDC/SAML SSO adapters; “unified identity model” depth varies by integration.
16–19 Storage, presign, policies, CDN Implemented / Partial StorageProvider / PresignableStorageProvider, local + S3, policy + CDN helpers.
20 Distributed cache Implemented Memory + Redis contracts and factory.
21–23 Rate limit, notifications, templated messaging Implemented Middleware + gateway + template engine baselines.
24–26 Jobs, external API, webhooks Implemented In-memory jobs, HTTP client, webhook dispatcher + signing contracts.
27 Event bus Partial InMemoryEventBus + RedisPublishingEventBus (Redis PUBLISH sidecar); cross-process SUBSCRIBE is app-owned (cookbook).
28–29 Multi-DB + distributed transactions Partial Registry + saga module; depth below full blueprint.
30 Search Partial Memory + OpenSearch-style adapter; Elasticsearch-specific breadth not guaranteed.
31–33 Audit, security middleware, request signing Implemented Wired through build_forge_app with toggles.
34 Capabilities endpoint Implemented /sdk/capabilities (+ profile for auth/runtime/realtime).
35–36 Multi-tenant + plugins Implemented Tenant middleware + PluginRegistry.
37–38 Observability + health Implemented Middleware with optional Prometheus request metrics (/metrics) + OTEL tracer wiring (sets x-trace-id from span context when enabled); health routes remain intact.
39 Secret management Implemented VaultSecretProvider implements the SecretProvider contract via Vault KV read (best-effort) and is wired in build_secret_provider for EITOHFORGE_SECRET_PROVIDER=vault. Value extraction supports common KV v2/v1 shapes; unit tests mock HTTP responses (no caching, so rotation is picked up on re-fetch).
40 Security context Implemented Request-scoped context middleware.
41 Sockets Partial InMemorySocketHub / RedisFanoutSocketHub (multi-worker broadcast + direct to actor_id via Redis); /realtime/ws; room “privacy” is naming-only; authorization for who may join or direct-message whom is application-owned (documented in realtime-websocket.md).
42 Versioned API Partial ApiVersion, build_versioned_router, ApiVersioningSettings + deprecation headers on /v1 via build_forge_app; separate OpenAPI per mount documented in cookbook.
43–44 Idempotency + feature flags Implemented Header-based idempotency + feature flag service and endpoint.

Conclusion: The blueprint is not fully implemented line-for-line; it remains the north star. The SDK covers a large subset of §1–§44 with protocol-first infra boundaries where it matters (storage, DB provider, repositories). Gaps cluster around additional database engines, richer query/event systems, socket private channels, and operations/secret backends. Use this appendix when prioritizing roadmap items; keep it updated when major capabilities land.

For day-to-day usage, see docs/guides/usage-complete.md, docs/guides/forge-profiles.md, and docs/standards/engineering-standards.md.

To close remaining gaps vs this specification, see docs/roadmap/blueprint-completion-waves.md and execution board Phase 17 (P17-*).

Documentation (multi-page)

Yes, multi-page docs are supported in this repository via docs/guides/.

Start here:

  • docs/README.md (docs index)
  • docs/guides/usage-complete.md (full usage reference)
  • docs/guides/cookbook.md (recipes)
  • docs/guides/realtime-websocket.md
  • docs/guides/query-spec-reference.md
  • docs/guides/python-packaging-and-publishing.md
  • secure_backend_sdk_architecture.md (architecture + implementation map)

License

Proprietary (see pyproject.toml).

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for eitoh-brand from gravatar.com eitoh-brand

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT
  • Author: EitohTech
  • Tags cli , enterprise , fastapi , scaffold , sdk
  • Requires: Python >=3.12
  • Provides-Extra: aws , dev , release
Classifiers

Release history Release notifications | RSS feed

This version

0.1.6

0.1.5

0.1.3

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

eitohforge-0.1.6.tar.gz (392.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

eitohforge-0.1.6-py3-none-any.whl (237.4 kB view details)

Uploaded Python 3

File details

Details for the file eitohforge-0.1.6.tar.gz.

File metadata

  • Download URL: eitohforge-0.1.6.tar.gz
  • Upload date:
  • Size: 392.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for eitohforge-0.1.6.tar.gz
Algorithm Hash digest
SHA256 7cc9fd89eb0376b858a85480745adccca63d1f5578f4e58c839be8fe76a0f9e5
MD5 a5296734d68a3af2dfd545437ffe85cc
BLAKE2b-256 ca7b38a2cb7adb3d5ec18616823b7ec86272b210b7dfdfcaa1f556bcc3256210

See more details on using hashes here.

Provenance

The following attestation bundles were made for eitohforge-0.1.6.tar.gz:

Publisher: publish-pypi.yml on eitoh-brand/EitohForge

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file eitohforge-0.1.6-py3-none-any.whl.

File metadata

  • Download URL: eitohforge-0.1.6-py3-none-any.whl
  • Upload date:
  • Size: 237.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for eitohforge-0.1.6-py3-none-any.whl
Algorithm Hash digest
SHA256 375cb6f7f957cb0cef7b2bf7399043bb5143c57b65a603d1682c4fa6cea62c51
MD5 48ee08f0a9d5aa48d45d602a7722b292
BLAKE2b-256 f1602a310dd9b1a66e578da5c1e50bd3d96a346587ec985d0f9b1e4f4b62ab64

See more details on using hashes here.

Provenance

The following attestation bundles were made for eitohforge-0.1.6-py3-none-any.whl:

Publisher: publish-pypi.yml on eitoh-brand/EitohForge

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page