bloomBUILD•SHIP•BLOOM
Bloom ServerBloom Server Overview
.md
Backend Architecture

Bloom Server Overview

Bloom Server is a comprehensive 15-package backend ecosystem modeled on the architectural patterns of Django and the project's own djangors-* Rust crates. It delivers an integrated ORM, migrations, authentication, validation, REST ViewSets, realtime WebSockets, task queues, and an HTML admin panel—built directly on pure Dart with Go/Rust-tier memory efficiency.

Unified Architecture

Unlike traditional multi-tier setups where backend and frontend exist in separate language silos or rely on generated client SDKs, Bloom Server shares the exact same foundation package—bloom_framework—between your server and Flutter client.

Shared Client-Server Primitives

BloomQuery and BloomMutation on Flutter clients communicate seamlessly with BloomRequest and BloomResponse on the server without intermediary codegen tools, OpenAPI bridges, or duplicate schema declarations.

Django-Style Modular Apps

Server projects are organized into domain apps (lib/apps/<name>/) containing models.dart, serializers.dart, views.dart, permissions.dart, and urls.dart.

bin/server.dart
dart
// bin/server.dart - Bootstrapping a High-Performance Bloom Server
import 'package:bloom_framework/bloom_server.dart';
import 'package:bloom_errors/bloom_errors.dart';
import 'package:bloom_db/bloom_db.dart';
import 'package:bloom_migrate/bloom_migrate.dart';
import 'package:bloom_realtime/bloom_realtime.dart';

Future<void> main(List<String> args) async {
  // 1. Connect to PostgreSQL or SQLite via unified DbExecutor
  final db = await PostgresDbExecutor.connect(
    host: BloomEnv.get('DB_HOST', defaultValue: '127.0.0.1'),
    port: BloomEnv.getInt('DB_PORT', defaultValue: 5432),
    username: BloomEnv.get('DB_USER', defaultValue: 'postgres'),
    password: BloomEnv.get('DB_PASSWORD', defaultValue: 'postgres'),
    database: BloomEnv.get('DB_NAME', defaultValue: 'bloom_server_dev'),
  );

  // 2. Run pending schema migrations automatically
  final runner = MigrationRunner(db: db, migrationsDirectory: 'migrations');
  await runner.migrate();

  // 3. Mount router with dev/prod error masking
  final router = BloomApiRouter();
  router.use(const BloomErrorMiddleware());

  router.get('/api/health', (req) async {
    return BloomResponse.json({'status': 'healthy'});
  });

  // 4. Multi-isolate cluster or single-process HTTP
  await router.serve(port: 8080);
}

Verified Performance & Benchmarks (8 vCPUs, Linux x64)

Dart is often underestimated as a client-only runtime. Under rigorous multi-core stress testing against Node.js, Fastify, NestJS, and Prisma, Bloom Server demonstrates massive architectural superiority in both raw throughput and resource consumption:

REALTIME FAN-OUT78k msgs/s
640 ms Total Delivery

50k messages delivered across 1,000 active WebSockets. 2x faster than Fastify (1,266 ms) while using only 3.7 MB RSS vs. Fastify's 107 MB.

NATIVE ORM LOOKUPS12.5k ops/s
12.7x Faster Than Prisma

5,000 database point lookups completed in 400 ms (Prisma took 5,089 ms, Drizzle took 731 ms). Bulk 2,300+ row update finished in 2 ms.

HTTP CONCURRENCY9.1k req/s
29.3 ms p99 Tail Latency

Under 1,000 concurrent HTTP keep-alive connections, Bloom maintained sub-30ms p99 latency with zero spikes. NestJS spiked to 1,120 ms.

bin/cluster_server.dart
dart
// bin/cluster_server.dart - Production Multi-Core Cluster
import 'dart:io';
import 'package:bloom_realtime/bloom_realtime.dart';

void main() async {
  // Binds HTTP/WS port across all physical CPU cores using HttpServer.bind(shared: true)
  // Utilizes peer-to-peer SendPort isolate mesh with zero Redis dependency.
  final cluster = await BloomRealtimeCluster.bind(
    port: 8080,
    workers: Platform.numberOfProcessors, // e.g. 8 isolate workers
  );

  print('Bloom Server Cluster running on port ${cluster.port} across ${cluster.workerCount} isolates');
}

Comparing Bloom vs. Node.js & Other Dart Backends

Understanding how Bloom Server compares to existing full-stack backend solutions:

Bloom Server vs. Node.js / NestJS / Fastify

Memory Footprint: Node.js requires spawning 8 separate OS processes to utilize an 8-core CPU (consuming ~1 GB RAM) and requires external Redis infrastructure for pub/sub. Bloom's BloomRealtimeCluster runs 8 isolate worker threads inside a single 3.7 MB process with native in-memory isolate message passing.

Type Safety: TypeScript types are completely erased at runtime, requiring runtime validators (Zod/Valibot) and tRPC boilerplate. Dart features reified static types compiled to native AOT machine code, ensuring end-to-end type safety between Flutter UI and PostgreSQL database models.

Bloom Server vs. Serverpod

The Differentiator: Bloom Server's primary distinction is that client data primitives (BloomQuery / BloomMutation) and server primitives (BloomRequest / BloomResponse) come directly from the same bloom_framework package without any client SDK codegen step. In contrast, Serverpod generates a separate Dart client SDK bridging Dart-to-Dart communication.

The Tradeoff: Serverpod is a mature, production-proven framework with years of battle-testing. Bloom Server is an integrated Django-style monorepo ecosystem with unified signals reactivity.

Bloom Server vs. Dart Frog & Shelf

Dart Frog and Shelf are intentionally minimal, low-level HTTP routing toolkits designed around a "bring-your-own-everything" model (you supply your own ORM, auth, migrations, admin panel, job queues, and validation). Bloom Server is a full-stack, batteries-included framework containing an integrated ORM, auth, admin, and migration toolchain in one cohesive design.

The 15-Package Ecosystem

The Bloom Server stack consists of 15 modular packages designed to work together or as standalone libraries:

Data Layer & Migrations

  • bloom_db

    Core ORM runtime and annotations for Bloom framework. SQLite and PostgreSQL, QuerySet API modeled on djangors-orm.

  • bloom_db_generator

    build_runner code generator for bloom_db models — generates ModelMeta and row-mapping boilerplate from @BloomModel annotations.

  • bloom_migrate

    Database migrations CLI and library for Bloom applications using bloom_db.

Auth, Security & Errors

  • bloom_auth_server

    Server-side authentication primitives for the Bloom framework, including password hashing, session/bearer token issuance, rate limiting, password reset workflows, and auth middleware.

  • bloom_security

    Production-ready CORS, security headers, rate limiting, and WebSocket upgrade utilities for Bloom servers.

  • bloom_errors

    Strongly-typed HTTP error hierarchy, sibling package error mapping, and dev/prod error-rendering middleware for Bloom.

  • bloom_validate

    Declarative, strictly-typed request and DTO schema validation for Bloom API routes.

API Layer & Administration

  • bloom_rest

    DRF-style (Django REST Framework) REST layer on top of BloomApiRouter and bloom_db, providing serializers, ViewSets, pagination, filters, permissions, and throttling.

  • bloom_admin

    Automatic server-rendered HTML administration interface for Bloom web applications.

  • bloom_realtimev0.2.0

    Real-time pub/sub layer with multi-isolate clustering (BloomRealtimeCluster), zero-copy binary streaming, and query invalidation bridges.

Operations & Infrastructure

  • bloom_cache

    Server-side caching abstraction and backends (In-Memory LRU, Database, Redis) with HTTP response caching middleware for Bloom applications.

  • bloom_jobs

    Background job queue and worker system for Bloom server applications.

  • bloom_mail

    Transactional email sending for Bloom server applications with swappable delivery backends.

  • bloom_storage

    Flexible, swappable file storage abstraction for Bloom server applications (Local Disk and S3-compatible backends like AWS S3, Cloudflare R2, MinIO, and Supabase Storage).

  • bloom_i18n

    Internationalization, locale resolution, ICU message formatting, and date localization for Bloom applications.

Package Availability & Ecosystem Versioning

The current release and distribution status of Bloom Server packages across the ecosystem:

Official Ecosystem Packages

bloom_framework ^0.2.2, bloom_db ^0.1.0, bloom_db_generator ^0.1.0, bloom_migrate ^0.1.0, bloom_validate ^0.1.0, bloom_auth_server ^0.1.0, bloom_mail ^0.1.0, bloom_jobs ^0.1.0, bloom_security ^0.1.0, bloom_storage ^0.1.0, bloom_realtime ^0.2.0, bloom_cache ^0.1.0, bloom_rest ^0.1.0, bloom_admin ^0.1.0, bloom_i18n ^0.1.0, bloom_errors ^0.1.0.

Get Started

Ready to build your first backend? Head over to the Scaffolding a Server guide to scaffold a new project with bloom server create.

For a complete, real-world reference project that wires all fifteen packages together against PostgreSQL, explore examples/bloom_fullstack_todo in the Bloom monorepo.

Previous: Hosting, Observability & AutomationNext: Scaffolding a Server