Singularity
A production-ready, modular Python backend framework built with FastAPI, Celery, SQLAlchemy, and Redis. Designed for scalability, maintainability, and developer experience.
Convention-based FastAPI microservices framework. Build scalable APIs with
auto-discovered services, hooks, caching, inter-service RPC, and background
tasks — pip install singularity-fm and go.
Why Singularity?
Singularity gives you a fully wired backend skeleton so you can focus on business logic instead of plumbing. Every module -- services, tasks, scripts, RPC, webhooks -- follows the same conventions and is automatically discovered at startup.
Modular Services
Self-contained business logic modules in services/. Auto-discovered by the Manager, injected with dependencies, and exposed as REST endpoints -- no manual registration required.
Inter-Service RPC
Call any service method from any other service via rpc("caller").target.method(). Supports blacklist enforcement, local dispatch, and Redis-backed remote discovery with heartbeat.
Background Tasks
Decorator-based task system powered by Celery and Redis. Define tasks with @task, attach notification channels (log, webhook, WebSocket, callback), and submit from any service.
Webhook Receivers
Build webhook endpoints with the BaseWebhook class. Signature verification, event-type routing, and handler dispatch are handled for you -- just implement your business logic.
CLI Tooling
Unified singularity CLI for scaffolding projects, generating services and tasks, and running the dev server. singularity new, singularity generate, singularity dev.
Dependency Injection
The Acquire container provides every service with access to the database session, settings, task runner, WebSocket manager, cache, and more. No globals, no singletons scattered across modules.
Architecture
Singularity follows a modular monolith pattern. The application core consists of a FastAPI app, a Service Manager that handles auto-discovery and dependency injection, an RPC registry for inter-service communication, and a task runner for background work. External infrastructure (PostgreSQL, Redis, Celery workers) is accessed through well-defined boundaries.
Quick Start
Get a running development server in five commands:
mkdir my-project && cd my-project
uv init && uv add singularity-fm
uv run singularity new
uv run singularity dev(singularity new scaffolds into the current directory — Singularity must already
be installed, so the project folder and Python env are expected to exist.)
The API will be available at http://localhost:8000 and the interactive Swagger docs at http://localhost:8000/docs.
From here, scaffold your first service:
singularity generate service usersRead the Installation guide for detailed setup instructions, or jump to Project Structure to understand how the codebase is organized.