bloomBUILD•SHIP•BLOOM
Bloom ServerScaffolding a Server
.md
CLI Scaffolding

Scaffolding a Server

The bloom server CLI commands provide Django-style scaffolding for entire backend server projects and modular domain applications.

Creating a New Server Project

Run bloom server create <name> to generate a complete backend server repository configured with starter apps, migrations, and a database connection:

Terminal
bash
# Create a new Bloom Server project with PostgreSQL (default)
bloom server create my_backend

# Or create a server configured for SQLite
bloom server create my_backend --db=sqlite

# Inside a monorepo, point to local packages directory
bloom server create my_backend --packages-path=/path/to/packages

CLI Options & Flags:

  • <name> — Required project name (lowercase letters, numbers, and underscores, starting with a letter).
  • --db=<postgres|sqlite> — Default database dialect for settings.dart (defaults to postgres).
  • --packages-path=<path> — Optional path to directory containing local bloom_* server packages.

Project Structure & Layout

A scaffolded Bloom Server project follows a standardized, modular layout with two pre-configured starter apps: accounts (user authentication) and notes (ownership-scoped CRUD):

Project Structure
yaml
my_backend/
├── bin/
│   └── server.dart          # Entrypoint: runs migrations and starts BloomApiRouter
├── lib/
│   ├── settings.dart        # Environment configuration, DB executor, and DI wiring
│   ├── urls.dart            # Root router: mounts app-level URL routers
│   └── apps/
│       ├── accounts/        # Starter app: authentication, signup, login, user models
│       │   ├── models.dart
│       │   ├── serializers.dart
│       │   ├── views.dart
│       │   ├── permissions.dart
│       │   └── urls.dart
│       └── notes/           # Starter app: ownership-scoped CRUD ViewSet
│           ├── models.dart
│           ├── serializers.dart
│           ├── views.dart
│           ├── permissions.dart
│           └── urls.dart
├── migrations/
│   ├── accounts/
│   │   └── 0001_initial.sql # SQL DDL migration for accounts_users
│   └── notes/
│       └── 0001_initial.sql # SQL DDL migration for notes_notes
├── storage/
│   └── uploads/             # Local file uploads directory
├── .env                     # Local environment secrets and DB connection config
├── .env.example
├── pubspec.yaml             # Wires core 7 runtime packages + build_runner dev deps
└── README.md

Core Packages Installed

Every scaffolded server project wires in the "core 7" package list in pubspec.yaml, plus dev dependencies:

bloom_framework

Core router, requests, responses, DI container, and env config.

bloom_db

ORM runtime, QuerySet API, and PostgreSQL / SQLite executors.

bloom_validate

Declarative request body validation schemas.

bloom_auth_server

BCrypt password hashing, JWT tokens, and auth middleware.

bloom_errors

Unified error middleware with dev/prod exception masking.

bloom_rest

DRF-style ViewSets, serializers, pagination, and filters.

bloom_migrate

DDL migration runner and schema version tracking.

bloom_db_generator (dev)

Optional build_runner codegen for @BloomModel annotations.

Scaffolding New Modular Apps

To add a new domain feature to your project, use bloom server startapp <app_name>:

Terminal
bash
# Add a new modular domain app (e.g. billing)
bloom server startapp billing

# Or specify the server directory explicitly
bloom server startapp billing --server-dir=/path/to/my_backend

This command generates:

  • lib/apps/<app_name>/models.dart — Starter model with @BloomModel and ModelMeta.
  • lib/apps/<app_name>/serializers.dart — Placeholder for BloomRequestSchema subclasses.
  • lib/apps/<app_name>/views.dart — Placeholder for view handlers and ViewSets.
  • lib/apps/<app_name>/permissions.dart — Permissions exports.
  • lib/apps/<app_name>/urls.dart — App-level route registration function.
  • migrations/<app_name>/0001_initial.sql — Initial DDL migration SQL file.

The CLI also automatically wires the new app into lib/urls.dart by adding the import and registering its routes in registerUrls().

Mounting App Routes in urls.dart

The root lib/urls.dart acts as the central router aggregator, similar to Django's root urls.py:

lib/urls.dart
dart
// lib/urls.dart - Root URL Routing
import 'package:bloom_framework/bloom_server.dart';
import 'settings.dart';
import 'apps/accounts/urls.dart' as accounts;
import 'apps/notes/urls.dart' as notes;

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

  // Mount each modular app's router
  accounts.registerUrls(router, ctx);
  notes.registerUrls(router, ctx);
}
Previous: Bloom Server OverviewNext: ORM & Migrations