Project Anatomy & Monorepo Layout

Bloom is engineered for both vertical full-stack applications (Mobile + Web + Backend in a unified Turborepo-style workspace) and focused single-target applications.

Full-Stack Monorepo Layout (Turborepo-Style)

This workspace structure separates executable targets (apps/) from shared, versioned modules (packages/) with pipeline-first dependency graphs:

Full-Stack Workspace Layout

bash

my_bloom_project/
├── bloom.yaml                    # Root workspace + CLI orchestration config
├── melos.yaml                    # Monorepo task pipeline definitions
├── .env.example                  # Shared env template (API_URL, DB_PATH, etc.)
│
├── .github/
│   └── workflows/
│       ├── ci.yml                # Test + lint on every pull request
│       ├── deploy-backend.yml    # bloom deploy → server cluster
│       └── ota-mobile.yml        # bloom deploy --ota → Shorebird instant release
│
├── apps/                         # Executable Target Applications
│   │
│   ├── mobile/                   # 📱 iOS & Android (Flutter Engine + Impeller)
│   │   ├── bloom.yaml            # Shorebird OTA, bundle ID, native permissions
│   │   ├── pubspec.yaml          # deps: bloom_framework, core, ui
│   │   ├── lib/
│   │   │   ├── routes/           # Next.js-style file-system GoRouter pages
│   │   │   │   ├── index.dart    # → /
│   │   │   │   ├── feed/
│   │   │   │   │   └── index.dart
│   │   │   │   └── profile/
│   │   │   │       └── [id].dart # → /profile/:id (strongly-typed)
│   │   │   ├── controllers/      # BloomController + reactive Signals state
│   │   │   └── main.dart         # Thin boot sequence (BloomBoot.init)
│   │   ├── ios/                  # Auto-managed by bloom prebuild
│   │   └── android/              # Auto-managed by bloom prebuild
│   │
│   ├── web/                      # 🌐 Flutter Web / Admin Portal / Desktop
│   │   ├── pubspec.yaml          # deps: bloom_framework, core, ui
│   │   ├── lib/
│   │   │   ├── routes/
│   │   │   │   ├── index.dart
│   │   │   │   ├── dashboard/
│   │   │   │   │   └── index.dart
│   │   │   │   └── (auth)/       # Route group (no URL segment)
│   │   │   │       └── login.dart
│   │   │   ├── layouts/
│   │   │   │   └── _layout.dart  # Multi-pane responsive sidebar shell
│   │   │   └── main.dart         # Web target (Wasm / CanvasKit)
│   │   └── web/                  # index.html, manifest.json
│   │
│   └── server/                   # 🖥️ Bloom Server (Pure Dart AOT Backend)
│       ├── pubspec.yaml          # deps: bloom_rest, bloom_db, bloom_realtime, core
│       ├── bin/
│       │   └── server.dart       # Multi-isolate cluster entrypoint (78k msgs/s)
│       ├── lib/
│       │   ├── apps/             # Django-style domain modular apps
│       │   │   ├── auth/         # models.dart, serializers.dart, views.dart, admin.dart
│       │   │   ├── feed/         # models.dart, serializers.dart, views.dart
│       │   │   └── billing/      # models.dart, serializers.dart, views.dart
│       │   ├── config/
│       │   │   ├── database.dart # bloom_db SQLite/PostgreSQL connection pool
│       │   │   ├── cache.dart    # bloom_cache stampede locks & Redis backend
│       │   │   └── mailer.dart   # bloom_mail transactional SMTP config
│       │   └── router.dart       # Mount all ViewSets + WebSocket channels
│       └── migrations/           # Linear SQL diffs (bloom_migrate)
│           ├── 0001_initial.sql
│           └── 0002_add_billing.sql
│
└── packages/                     # 📦 Shared Internal Packages
    │
    ├── core/                     # 🧠 Shared Business Logic (Pure Dart • Zero Flutter)
    │   ├── pubspec.yaml          # Pure Dart only
    │   └── lib/
    │       ├── models/           # Shared DTOs & entities (User, Post, Invoice)
    │       │   ├── user.dart
    │       │   ├── post.dart
    │       │   └── models.dart   # Barrel export
    │       ├── validation/       # Shared field validators (bloom_validate)
    │       ├── api/              # Typed request/response contracts
    │       │   ├── endpoints.dart
    │       │   └── query_keys.dart
    │       └── core.dart         # Public package barrel export
    │
    ├── ui/                       # 🎨 Shared Design System (Flutter package)
    │   ├── pubspec.yaml          # deps: bloom_ui, flutter
    │   └── lib/
    │       ├── components/       # 60+ shadcn primitives (Button, Dialog, Chart)
    │       ├── tokens/           # Shared colors, typography, border radii
    │       └── ui.dart
    │
    └── config/                   # ⚙️  Shared Constants & Feature Flags (Pure Dart)
        ├── pubspec.yaml          # Pure Dart
        └── lib/
            ├── env.dart          # Typed env parsing (String.fromEnvironment)
            ├── flags.dart        # Feature flag definitions
            └── config.dart

The 3 Golden Architecture Rules

Data Flows Down, Never Sideways

apps/* depend on packages/*. Packages never import from apps, and apps never import directly from sibling apps.

packages/core is Pure Dart

Zero Flutter dependencies in core. This allows apps/server to consume exact data models without dragging in the Flutter UI engine.

Contracts Over Codegen

Shared schemas, DTOs, and query keys live in packages/core. Client BloomQuery and server BloomViewSet share exact types.

Monorepo Task Pipeline (`melos.yaml`)

Melos orchestrates multi-package linking, dependency synchronization, concurrent development servers, and automated deployment pipelines:

melos.yaml

yaml

# melos.yaml - Task Pipeline Definitions
name: my_bloom_project

packages:
  - apps/**
  - packages/**

scripts:
  # Concurrent local development
  dev:
    run: melos run dev:backend & melos run dev:mobile
    description: Start server and mobile app concurrently

  dev:backend:
    run: cd apps/server && bloom server dev
    description: Run backend server with hot-reload

  dev:mobile:
    run: cd apps/mobile && flutter run -d ios

  dev:web:
    run: cd apps/web && flutter run -d chrome

  # Build pipeline (packages built before apps)
  build:
    run: melos exec -- flutter build appbundle
    packageFilters:
      dependsOn: core

  # Database migrations
  migrate:
    run: cd apps/server && bloom migrate run
  migrate:make:
    run: cd apps/server && bloom migrate make $name

  # Quality checks
  test:
    run: melos exec -- flutter test
  lint:
    run: melos exec -- dart analyze

  # Deployment
  deploy:server:
    run: cd apps/server && bloom deploy
  deploy:ota:
    run: cd apps/mobile && bloom deploy --ota --channel production

Single-App Project Structure

For standalone mobile or web projects created with bloom create my_app, Bloom organizes files into feature slices:

Single-App Structure