{"id":35122468,"url":"https://github.com/anthonykewl20/efncore","last_synced_at":"2026-01-13T22:54:03.128Z","repository":{"id":329713661,"uuid":"1118101411","full_name":"anthonykewl20/efncore","owner":"anthonykewl20","description":"Enterprise SaaS framework (FastAPI + Next.js) — Hybrid DDD Core + governed modules","archived":false,"fork":false,"pushed_at":"2025-12-27T18:35:56.000Z","size":2792,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-30T01:04:15.316Z","etag":null,"topics":["ddd-architecture","fastapi","modular-architecture","monorepo","multi-tenancy","nextjs","opentelemetry","plugin-architecture","postgresql","python3","rabbitmq","redis","typescript"],"latest_commit_sha":null,"homepage":"https://ranex.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anthonykewl20.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":"2025-12-17T09:08:52.000Z","updated_at":"2025-12-27T18:35:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anthonykewl20/efncore","commit_stats":null,"previous_names":["anthonykewl20/efncore"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/anthonykewl20/efncore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonykewl20%2Fefncore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonykewl20%2Fefncore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonykewl20%2Fefncore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonykewl20%2Fefncore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anthonykewl20","download_url":"https://codeload.github.com/anthonykewl20/efncore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonykewl20%2Fefncore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ddd-architecture","fastapi","modular-architecture","monorepo","multi-tenancy","nextjs","opentelemetry","plugin-architecture","postgresql","python3","rabbitmq","redis","typescript"],"created_at":"2025-12-28T00:46:58.339Z","updated_at":"2026-01-13T22:54:03.122Z","avatar_url":"https://github.com/anthonykewl20.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# efncore\n\n**The Enterprise SaaS Framework Kernel** — Production-grade multi-tenancy, events, jobs, and observability for building SaaS products.\n\n[![CI/CD](https://github.com/anthonykewl20/efncore/actions/workflows/ci-pipeline.yml/badge.svg)](https://github.com/anthonykewl20/efncore/actions/workflows/ci-pipeline.yml)\n[![Security](https://github.com/anthonykewl20/efncore/actions/workflows/security-scan.yml/badge.svg)](https://github.com/anthonykewl20/efncore/actions/workflows/security-scan.yml)\n[![License: RSEL v1.0](https://img.shields.io/badge/License-RSEL%20v1.0-blue.svg)](LICENSE)\n\n---\n\n## 🎯 What is efncore?\n\nefncore is a **production-grade framework for building multi-tenant SaaS products**. Like WordPress for enterprise SaaS, it provides:\n\n- 🏗️ **Domain-Driven Design architecture** that scales with your team\n- 🏢 **Built-in multi-tenancy** with tenant isolation at all layers\n- ⚡ **Event-driven architecture** with transactional outbox\n- 🔄 **Background jobs** with retry logic and scheduling\n- 📊 **OpenTelemetry observability** from day one\n- 🔌 **Module system** for extensible features\n- 🎨 **Frontend shell included** (Next.js 16)\n\n**For SaaS Founders**: Ship months faster with production-grade patterns.\n**For Developers**: FastAPI + Next.js with TypeScript everywhere.\n**For AI Agents**: CLAUDE.md with explicit architecture documentation.\n\n---\n\n## ⚡ Quick Start (5 minutes)\n\nGet efncore running locally with Docker Compose.\n\n### Prerequisites\n\n- Docker \u0026 Docker Compose\n- Git\n\n### One-Command Setup\n\n```bash\ngit clone https://github.com/anthonykewl20/efncore.git\ncd efncore\ndocker compose up -d\n```\n\n### Access Your SaaS\n\n| Service | URL | Credentials |\n|---------|-----|-------------|\n| Frontend | http://localhost:3001 | - |\n| Backend API | http://localhost:8001 | - |\n| API Docs | http://localhost:8001/docs | - |\n| Debug Context | http://localhost:8001/debug/context | - |\n| Keycloak | http://localhost:8080 | admin/admin |\n\n### Verify It's Working\n\n```bash\n# Check health status\ncurl http://localhost:8001/health\n\n# Check request context (tenant isolation)\ncurl -H \"X-Tenant-Id: 123e4567-e89b-12d3-a456-426614174000\" \\\n     http://localhost:8001/debug/context\n```\n\n**[← Full Setup Guide](docs/dev-docs/QUICK_START.md)**\n\n---\n\n## ✨ Why efncore?\n\n### For SaaS Founders\n\n| Challenge | efncore Solution |\n|-----------|-----------------|\n| **Building multi-tenancy from scratch** | Tenant isolation built-in (DB, cache, events) |\n| **Handling background jobs reliably** | Transactional outbox + RabbitMQ workers |\n| **Scaling read load** | Automatic replica routing (ADR-014) |\n| **Observability after the fact** | OpenTelemetry tracing from day one |\n| **Hiring developers** | Standard DDD patterns, clear documentation |\n\n### For Developers\n\n```python\n# Tenant-scoped requests (automatic)\nfrom efncore.kernel.request_context import RequestContextDep\n\n@router.get(\"/users\")\nasync def list_users(ctx: RequestContextDep):\n    # ctx.tenant_id automatically filters queries\n    users = await user_service.list(ctx.tenant_id)\n    return users\n```\n\n```bash\n# Read from replicas automatically\n# Write to primary explicitly\nasync with get_db_session(prefer_replica=True) as session:\n    user = await session.get(User, id)  # Routes to replica\n\nasync with get_write_db_session() as session:\n    session.add(new_user)  # Always goes to primary\n    await session.commit()\n```\n\n### For AI Agents\n\nefncore includes **CLAUDE.md** — explicit architecture documentation for AI assistants:\n- File placement rules (non-negotiable)\n- API patterns and conventions\n- Testing workflows and patterns\n- Configuration system reference\n\n---\n\n## ✨ Core Features\n\n### 🏢 Multi-Tenancy\n\n- **Tenant isolation** at database, cache, and event layers\n- **Request context middleware** automatically scopes all operations\n- **Tenant-scoped Redis keys** prevent data leakage\n- **Row-level security** with tenant governance\n- **Tenant onboarding** flows built-in\n\n### ⚡ Event-Driven Architecture\n\n- **Transactional outbox pattern** prevents event loss\n- **RabbitMQ integration** with at-least-once delivery\n- **Event handlers** with idempotency and replay\n- **Dead-letter queues** for failed events\n- **Module-to-core** communication via events\n\n### 🔄 Background Jobs\n\n- **Arq-based job queue** with Redis backend\n- **Retry logic** with exponential backoff\n- **Scheduled jobs** and cron-like workflows\n- **Tenant-isolated** job execution\n- **Job observability** with tracing\n\n### 📊 Observability\n\n- **OpenTelemetry tracing** (OTLP) with W3C trace context\n- **Structured logging** with tenant/user context\n- **Performance guardrails** (query timeouts, backpressure)\n- **Slow query logging** with automatic detection\n- **Health checks** for all dependencies\n\n### 🔌 Module System\n\n- **Dynamic module loading** from directory\n- **Strict contracts** (HTTP APIs + domain events)\n- **Module governance** (allowlist, version checks)\n- **UI extension points** for frontend modules\n- **Kill switch** for emergency disabling\n\n### 🛡️ Security\n\n- **OIDC authentication** (Keycloak integration)\n- **Role-based access control** (RBAC)\n- **Audit logging** for compliance (SOC 2, HIPAA)\n- **PII redaction** in logs and events\n- **Rate limiting** and load shedding\n\n---\n\n## 🏗️ Architecture Overview\n\nefncore follows **Domain-Driven Design (DDD)** with bounded contexts:\n\n```mermaid\ngraph TB\n    subgraph \"Frontend (Next.js)\"\n        A[app/] --\u003e B[core/templates/]\n        A --\u003e C[modules/]\n        A --\u003e D[platform/]\n    end\n\n    subgraph \"Backend (FastAPI)\"\n        E[app/main.py] --\u003e F[core/contexts/]\n        E --\u003e G[modules/]\n        E --\u003e H[efncore/kernel/]\n    end\n\n    subgraph \"Kernel Services\"\n        H --\u003e I[request_context/]\n        H --\u003e J[data/]\n        H --\u003e K[eventing/]\n        H --\u003e L[jobs/]\n        H --\u003e M[cache/]\n    end\n\n    A --\u003e|HTTP/REST| E\n    K --\u003e|RabbitMQ| N[Workers]\n    J --\u003e|PostgreSQL| O[(Primary)]\n    J --\u003e|Read Replicas| O\n    M --\u003e|Redis| P[(Cache)]\n```\n\n### Repository Structure\n\n```\nefncore/\n├── backend/                 # FastAPI application\n│   ├── src/\n│   │   ├── app/            # Composition root\n│   │   ├── core/           # Non-removable bounded contexts\n│   │   │   ├── tenancy/    # Tenant lifecycle\n│   │   │   ├── iam/         # Users, auth, RBAC\n│   │   │   ├── audit/       # Audit logging\n│   │   │   └── billing/     # Subscriptions, entitlements\n│   │   ├── modules/        # Installable features\n│   │   └── efncore/        # Platform kernel\n│   │       ├── kernel/\n│   │       │   ├── request_context/  # Tenant/user metadata\n│   │       │   ├── data/             # Read/write splitting\n│   │       │   ├── eventing/         # Outbox, events\n│   │       │   ├── jobs/             # Background jobs\n│   │       │   └── cache/            # Redis caching\n│   │       ├── http/         # Middleware, errors\n│   │       └── config/       # Centralized settings\n│   ├── tests/               # Unit, integration, E2E\n│   └── worker/              # Background job worker\n│\n├── frontend/                # Next.js application\n│   ├── src/\n│   │   ├── app/            # App Router\n│   │   ├── core/           # Shell/core UI\n│   │   ├── modules/        # Module UI\n│   │   └── platform/       # Theme, UI kit\n│   └── e2e/                # Playwright E2E tests\n│\n├── docs/                    # Architecture \u0026 dev docs\n│   ├── architecture/        # ADRs, system context\n│   ├── development/         # Roadmap, workstreams\n│   └── dev-docs/           # Developer guides\n│\n└── CLAUDE.md                # AI agent documentation\n```\n\n**Key Principles:**\n- 📁 **No `utils/`, `common/`, or `shared/`** directories\n- 🚫 **No business logic in HTTP routers**\n- 🔒 **All requests tenant-scoped**\n- 📡 **Modules communicate via HTTP APIs or events**\n\n---\n\n## 📚 Documentation\n\n### Getting Started\n\n| Guide | Description |\n|-------|-------------|\n| [**Quick Start**](docs/dev-docs/QUICK_START.md) | Get running in 5 minutes |\n| [**Configuration Guide**](docs/dev-docs/configuration/README.md) | All 100+ environment variables |\n| [**Debugging Guide**](docs/dev-docs/debugging/README.md) | Troubleshooting common issues |\n| [**Request Context**](docs/dev-docs/request-context/README.md) | Tenant/user propagation |\n\n### Architecture\n\n| Document | Description |\n|----------|-------------|\n| [**System Context**](docs/architecture/system-context.md) | C4 system-level architecture |\n| [**ADR Index**](docs/architecture/adr/adrs.md) | Architecture decision records |\n| [**Deployment**](docs/architecture/deployment-reliability.md) | Production deployment guide |\n| [**Performance**](docs/architecture/scalability-performance.md) | Scaling and optimization |\n\n### Development\n\n| Document | Description |\n|----------|-------------|\n| [**File Governance**](docs/development/000-file-folder-governance.md) | Where code belongs (NON-NEGOTIABLE) |\n| [**Module Development**](docs/dev-docs/module-development-guide.md) | Building modules |\n| [**Eventing Guide**](docs/dev-docs/eventing/README.md) | Event handlers and outbox |\n| [**Jobs Guide**](docs/dev-docs/jobs/README.md) | Background job patterns |\n\n---\n\n## 🧪 Testing\n\nefncore uses **Shin et al methodologies** (mutation testing, sad path first):\n\n```bash\n# Backend tests\ncd backend\npytest                          # All tests\npytest -m unit                  # Unit tests only\npytest -m integration           # Integration tests (requires DB)\npytest -m smoke                 # Health checks against running services\n\n# Frontend tests\ncd frontend\nnpm test                        # Unit tests (Vitest)\nnpm run test:e2e                # E2E tests (Playwright)\nnpm run test:coverage           # With coverage\n```\n\n**Test Philosophy:**\n- ✅ Sad path before happy path\n- ✅ Tenant isolation tests\n- ✅ Mutation testing for critical modules\n- ✅ Cross-module integration tests\n\n---\n\n## 🚀 Deployment\n\n### Development (Docker Compose)\n\n```bash\ndocker compose up -d\n```\n\n### Production\n\nSee [Deployment Guide](docs/architecture/deployment-reliability.md) for:\n- Kubernetes manifests\n- Environment variable reference\n- Database migrations\n- PgBouncer for read replicas\n- OpenTelemetry collector setup\n\n**Current Deployment:** Single VPS with Dokploy (Phase 0)\n**Migration Path:** VPS → Split DB → Multi-region (same codebase)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](docs/development/CONTRIBUTING.md) for guidelines.\n\n**Areas for Contribution:**\n- 🐛 Bug fixes\n- 🔌 New modules\n- 📖 Documentation improvements\n- ✅ Test coverage\n- ⚡ Performance optimizations\n\n**Good First Issues:** [GitHub Issues](https://github.com/anthonykewl20/efncore/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n\n---\n\n## 💬 Community\n\n- **GitHub Discussions:** [Ask questions](https://github.com/anthonykewl20/efncore/discussions)\n- **Issues:** [Bug reports \u0026 feature requests](https://github.com/anthonykewl20/efncore/issues)\n- **Documentation:** [CLAUDE.md](CLAUDE.md) for AI agent contributors\n\n---\n\n## 🗺️ Roadmap\n\n| Phase | Status | Description |\n|-------|--------|-------------|\n| **Phase 0** | ✅ Complete | Single VPS deployment (cost optimization) |\n| **Phase 1** | ✅ Complete | Core multi-tenancy + read replicas |\n| **Phase 2** | 🚧 In Progress | Module marketplace + governance UI |\n| **Phase 3** | 📋 Planned | AI agent SDK for module development |\n| **Phase 4** | 📋 Planned | Multi-region high availability |\n\n**[Full Roadmap](docs/architecture/scalability-performance.md)**\n\n---\n\n## 📊 Performance\n\nefncore is built for scale:\n\n- **Throughput:** 10,000+ req/sec per instance\n- **Database:** Read replicas with automatic routing\n- **Caching:** Tenant-scoped Redis with TTL governance\n- **Backpressure:** Load shedding when overloaded\n- **Query Timeouts:** 50% of request timeout threshold\n- **Slow Queries:** Auto-logged when exceeding 1 second\n\n**[Performance Guide](docs/architecture/performance-optimization-playbook.md)**\n\n---\n\n## 🛠️ Tech Stack\n\n**Backend:**\n- [FastAPI](https://fastapi.tiangolo.com) 0.124.4 — Web framework\n- [Python](https://www.python.org) 3.12 — Runtime\n- [PostgreSQL](https://www.postgresql.org) 18.1 — Primary database\n- [Redis](https://redis.io) 7 — Caching \u0026 sessions\n- [RabbitMQ](https://www.rabbitmq.com) 4.1 — Message broker\n- [Alembic](https://alembic.sqlalchemy.org) 1.17.2 — Migrations\n\n**Frontend:**\n- [Next.js](https://nextjs.org) 16.0.10 — React framework\n- [TypeScript](https://www.typescriptlang.org) — Type safety\n- [Tailwind CSS](https://tailwindcss.com) 4.1.18 — Styling\n- [Radix UI](https://www.radix-ui.com) — Component primitives\n- [Playwright](https://playwright.dev) — E2E testing\n\n**Observability:**\n- [OpenTelemetry](https://opentelemetry.io) — Tracing \u0026 metrics\n- [SigNoz](https://signoz.io) — APM backend\n\n---\n\n## 📄 License\n\n**RANEX FRAMEWORKS SOURCE-AVAILABLE EVALUATION LICENSE (RSEL) v1.0**\n\nSee [LICENSE](LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgments\n\nefncore stands on the shoulders of giants:\n\n- **WordPress** — Plugin architecture inspiration\n- **Stripe** — API design patterns\n- **Shopify** — Multi-tenancy patterns\n- **FastAPI** — Backend framework\n- **Next.js** — Frontend framework\n\n---\n\n## 📖 Citation\n\nIf you use efncore in your research or production, please cite:\n\n```bibtex\n@software{efncore,\n  title = {efncore: Enterprise SaaS Framework Kernel},\n  author = {Anthony Kewl},\n  year = {2024},\n  url = {https://github.com/anthonykewl20/efncore}\n}\n```\n\n---\n\n**⭐ Star us on GitHub** — it helps more people discover efncore!\n\n**[← Back to Docs](docs/) | [Quick Start →](docs/dev-docs/QUICK_START.md)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonykewl20%2Fefncore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthonykewl20%2Fefncore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonykewl20%2Fefncore/lists"}