{"id":50805490,"url":"https://github.com/varunramagiri/python-microservices-framework","last_synced_at":"2026-06-13T00:33:11.118Z","repository":{"id":359811691,"uuid":"1247606199","full_name":"varunramagiri/python-microservices-framework","owner":"varunramagiri","description":"Async FastAPI template with JWT/RBAC, Redis rate limiting, circuit breakers, Prometheus, OpenTelemetry, Kubernetes HPA and Terraform IaC","archived":false,"fork":false,"pushed_at":"2026-05-23T14:42:50.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T16:24:54.021Z","etag":null,"topics":["async","docker","fastapi","jwt","kubernetes","microservices","observability","opentelemetry","prometheus","python","rest-api","terraform"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/varunramagiri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T14:40:08.000Z","updated_at":"2026-05-23T14:42:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/varunramagiri/python-microservices-framework","commit_stats":null,"previous_names":["varunramagiri/python-microservices-framework"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/varunramagiri/python-microservices-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varunramagiri%2Fpython-microservices-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varunramagiri%2Fpython-microservices-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varunramagiri%2Fpython-microservices-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varunramagiri%2Fpython-microservices-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varunramagiri","download_url":"https://codeload.github.com/varunramagiri/python-microservices-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varunramagiri%2Fpython-microservices-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34268187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","docker","fastapi","jwt","kubernetes","microservices","observability","opentelemetry","prometheus","python","rest-api","terraform"],"created_at":"2026-06-13T00:33:07.665Z","updated_at":"2026-06-13T00:33:11.108Z","avatar_url":"https://github.com/varunramagiri.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ Python Microservices Framework\n\n\u003e **Production-grade async FastAPI microservices template** — JWT Auth · Rate Limiting · Circuit Breakers · Redis Caching · Kubernetes · Terraform · Observability — zero-boilerplate for new services\n\n[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square\u0026logo=python)](https://python.org)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688?style=flat-square\u0026logo=fastapi)](https://fastapi.tiangolo.com)\n[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square\u0026logo=docker)](https://docker.com)\n[![Kubernetes](https://img.shields.io/badge/Kubernetes-326CE5?style=flat-square\u0026logo=kubernetes)](https://kubernetes.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)\n\n---\n\n## 🎯 Overview\n\nA battle-tested FastAPI microservices starter — built from backend patterns deployed at **Nationwide Mutual Insurance**, **CVS Health**, and **Gap Inc.** — that gives every new service authentication, observability, resilience patterns, and cloud deployment on day one.\n\n**What you get out of the box:**\n- Async FastAPI with proper lifespan management and dependency injection\n- JWT + OAuth2 authentication with role-based access control (RBAC)\n- Redis-backed rate limiting and distributed caching\n- Circuit breaker pattern for downstream service calls\n- Structured logging (structlog) + Prometheus metrics + distributed tracing (OpenTelemetry)\n- Health checks, readiness/liveness probes\n- Kubernetes manifests with HPA and Terraform infrastructure\n- Full CI/CD pipeline via GitHub Actions\n\n---\n\n## 📁 Folder Structure\n\n```\npython-microservices-framework/\n├── app/\n│   ├── main.py                     # FastAPI lifespan, middleware, router mount\n│   ├── api/\n│   │   ├── v1/\n│   │   │   ├── router.py           # API v1 route aggregator\n│   │   │   ├── health.py           # /health, /readiness, /liveness\n│   │   │   ├── auth.py             # /auth/token, /auth/refresh, /auth/logout\n│   │   │   └── resources.py        # Your domain endpoints go here\n│   │   └── deps.py                 # Shared FastAPI dependencies (auth, db, cache)\n│   ├── core/\n│   │   ├── config.py               # Pydantic settings (env-driven)\n│   │   ├── security.py             # JWT creation, validation, password hashing\n│   │   ├── database.py             # SQLAlchemy async engine + session factory\n│   │   └── redis.py                # Async Redis client factory\n│   ├── middleware/\n│   │   ├── auth_middleware.py      # JWT extraction + RBAC enforcement\n│   │   ├── rate_limiter.py         # Token bucket rate limiting (Redis)\n│   │   ├── circuit_breaker.py      # Circuit breaker (pybreaker)\n│   │   ├── request_id.py           # X-Request-ID propagation\n│   │   └── cors.py                 # CORS configuration\n│   ├── models/\n│   │   ├── base.py                 # SQLAlchemy base with UUID PK, timestamps\n│   │   ├── user.py\n│   │   └── audit_log.py\n│   ├── schemas/\n│   │   ├── base.py                 # Shared Pydantic response schemas\n│   │   ├── auth.py                 # Token request/response schemas\n│   │   └── pagination.py           # Cursor-based pagination schema\n│   ├── services/\n│   │   ├── auth_service.py         # Business logic: auth, token management\n│   │   └── cache_service.py        # Cache-aside pattern with TTL management\n│   └── observability/\n│       ├── metrics.py              # Prometheus: request count, latency, errors\n│       ├── logging.py              # structlog JSON config\n│       └── tracing.py              # OpenTelemetry auto-instrumentation\n├── tests/\n│   ├── conftest.py                 # pytest fixtures: test app, async client, db\n│   ├── unit/\n│   │   ├── test_auth.py\n│   │   ├── test_rate_limiter.py\n│   │   └── test_circuit_breaker.py\n│   └── integration/\n│       ├── test_auth_flow.py\n│       └── test_api_endpoints.py\n├── infra/\n│   ├── terraform/\n│   │   ├── main.tf                 # EKS cluster + RDS + ElastiCache\n│   │   ├── variables.tf\n│   │   └── outputs.tf\n│   └── k8s/\n│       ├── namespace.yaml\n│       ├── deployment.yaml\n│       ├── service.yaml\n│       ├── ingress.yaml\n│       ├── hpa.yaml                # HorizontalPodAutoscaler\n│       ├── configmap.yaml\n│       └── secrets-external.yaml   # AWS Secrets Manager external secrets\n├── scripts/\n│   ├── generate_service.py         # Scaffold a new microservice from template\n│   └── load_test.py                # Locust load test scenarios\n├── .github/\n│   └── workflows/\n│       ├── ci.yml                  # Lint + test + coverage + security scan\n│       └── cd.yml                  # Build + push + deploy to EKS\n├── Dockerfile\n├── docker-compose.yml              # Full local stack: app + postgres + redis\n├── alembic.ini\n├── pyproject.toml\n├── requirements.txt\n└── README.md\n```\n\n---\n\n## ⚡ Quick Start\n\n```bash\n# Clone\ngit clone https://github.com/varunramagiri/python-microservices-framework.git\ncd python-microservices-framework\n\n# Scaffold a new service from this template\npython scripts/generate_service.py --name my-new-service --output ../my-new-service\n\n# Start full local stack\ndocker compose up --build\n\n# Run tests with coverage\npytest tests/ -v --cov=app --cov-report=html\n\n# Access API docs\nopen http://localhost:8000/docs\n```\n\n---\n\n## 🔑 Key Patterns\n\n### Async endpoint with auth, caching, and circuit breaker\n\n```python\nfrom fastapi import APIRouter, Depends\nfrom app.api.deps import require_role, get_cache\nfrom app.middleware.circuit_breaker import breaker\n\nrouter = APIRouter()\n\n@router.get(\"/claims/{claim_id}\")\n@breaker  # Trips after 5 failures in 60s; half-open after 30s\nasync def get_claim(\n    claim_id: str,\n    current_user = Depends(require_role(\"claims:read\")),\n    cache = Depends(get_cache),\n):\n    # Check cache first (cache-aside pattern)\n    cached = await cache.get(f\"claim:{claim_id}\")\n    if cached:\n        return cached\n\n    # Fetch from downstream (circuit breaker protects this)\n    claim = await claims_service.get(claim_id)\n    await cache.set(f\"claim:{claim_id}\", claim, ttl=300)\n    return claim\n```\n\n### Rate limiter middleware\n\n```python\n# config/settings.yml\nrate_limiting:\n  default: \"100/minute\"\n  auth_endpoints: \"10/minute\"\n  ai_inference: \"20/minute\"\n```\n\n---\n\n## 📊 Observability\n\nEvery request auto-emits:\n- `http_requests_total{method, endpoint, status}` — Prometheus counter\n- `http_request_duration_seconds{method, endpoint}` — Prometheus histogram\n- Structured JSON log: `{\"request_id\": \"...\", \"user_id\": \"...\", \"latency_ms\": 42, ...}`\n- OpenTelemetry trace span (Jaeger / AWS X-Ray)\n\n```bash\n# View Grafana dashboard (local)\nopen http://localhost:3000\n```\n\n---\n\n## 🚀 Deploy to Kubernetes\n\n```bash\n# Provision EKS + RDS + ElastiCache\ncd infra/terraform \u0026\u0026 terraform apply\n\n# Deploy application\nkubectl apply -f infra/k8s/\n\n# Check rollout\nkubectl rollout status deployment/api -n production\n```\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE)\n\n*Backend patterns from 10+ years of production Python services across fintech, healthcare, insurance, and retail.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvarunramagiri%2Fpython-microservices-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvarunramagiri%2Fpython-microservices-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvarunramagiri%2Fpython-microservices-framework/lists"}