Architecture Overview

Singularity is a modular monolith -- a single deployable unit that enforces strict module boundaries internally. This page explains the philosophy behind that choice, walks through the full system architecture, and details how a request travels from client to database and back.

Modular Monolith Philosophy

Microservices solve organizational scaling problems (independent teams, independent deployments) but introduce significant operational complexity: distributed tracing, network partitions, data consistency, and deployment orchestration. For most projects -- especially early-stage ones -- that complexity is not justified.

Singularity takes a different approach:

Full Architecture Diagram

The following diagram shows every major component in the system and how they connect. External clients and webhook providers enter through the FastAPI layer. The Manager orchestrates service registration and dependency injection. The RPC Registry handles both local in-process calls and remote HTTP discovery via Redis. Background tasks flow through Redis into Celery workers.

Request Lifecycle

Every HTTP request follows the same path through the system. Middleware layers execute in registration order before the request reaches the router. The router dispatches to the correct service method, which performs business logic -- typically involving database access -- and returns a response that travels back through the middleware stack.

What Happens at Each Layer

Application Lifespan

The application goes through a precise sequence of steps from process start to serving requests, and an orderly teardown on shutdown. Understanding this flow is critical for knowing when services, RPC, and the heartbeat become available.

Startup Phase (Synchronous)

The synchronous portion runs when the module is first imported, before the ASGI server starts accepting connections:

Startup Phase (Asynchronous)

Once uvicorn or gunicorn starts the ASGI server, the lifespan context manager fires:

Shutdown Phase

Design Principles

Singularity is built on three core principles that inform every design decision in the framework.

Auto-Discovery

Services, middlewares, tasks, and scripts are all discovered automatically by scanning the filesystem. There are no registration arrays to maintain, no import lists to keep in sync. The conventions are:

Convention Over Configuration

Singularity minimizes configuration by defining sensible defaults and consistent patterns:

• URL routing is derived from the directory path: services/v1/payments/service.py mounts at /api/v1/payments.
• HTTP methods map to method names: define async def get(self) and you get a GET endpoint.
• Custom routes use http_exposed with a simple method=path syntax: "get=status" maps to get_status().
• Service names for RPC are the directory name, injected automatically as _service_name.

Dependency Injection

The Acquire container holds all shared resources -- database sessions, settings, the task runner, the WebSocket manager, caches, and utilities. The Manager inspects each service's __init__ signature: if it accepts acquire, it receives the container. Services that do not need shared resources can omit the parameter entirely.

# Service WITH dependency injection
class PaymentsService(Service):
    def __init__(self, acquire):
        super().__init__(acquire)
        self.db = acquire.db_session
        self.settings = acquire.settings

# Service WITHOUT dependency injection
class HealthService(Service):
    async def get(self):
        return {"status": "healthy"}

Both patterns are valid. The Manager handles both transparently, keeping service code focused on business logic rather than infrastructure wiring.