Bloom Affordable Housing Platform

Bloom is Exygy’s affordable housing platform. Bloom's goal is to be a single entry point for affordable housing seekers and application management for developers. You can read more about the platform on bloomhousing.com.

Overview

Bloom consists of a client/server architecture using Next.js for the frontend applications and NestJS, Prisma, and Postgres on the backend.

Structure

Bloom uses a monorepo-style repository containing multiple user-facing applications and backend services. The main high-level packages are api, sites, model, and shared-helpers. Additionally, Bloom's UI leverages the in-house packages @bloom-housing/ui-seeds and @bloom-housing/ui-components.

bloom/
├── api/                    # NestJS backend services
├── model/                  # Risk prediction microservice (Flask, XGBoost)
├── sites/
│   ├── public/             # Next.js applicant-facing portal
│   └── partners/           # Next.js developer/admin portal
├── shared-helpers/         # Shared types and utilities
├── @bloom-housing/ui-seeds # Design system and React components
└── @bloom-housing/ui-components # Legacy React component library

• sites/public: Applicant-facing site for browsing and applying to listings using Bloom’s Common Application or third-party applications. See sites/public/README.
• sites/partners: Secure portal for housing developers, property managers, and city/county employees to manage applications and listings. Requires login. See sites/partners/README.
• api: Backend services (e.g., listings, applications, users) stored in a Postgres database and served via a REST API over HTTPS. See api/README.
• model: Flask-based microservice using XGBoost to predict housing instability risk based on features like income and household size. Exposes a /predict endpoint. See model/README.
• shared-helpers: Shared types, functions, and components for public and partners sites. See shared-helpers/README.
• @bloom-housing/ui-seeds: Component library with React components and design system tokens. Explore the Storybook and design documentation.
• @bloom-housing/ui-components: Legacy component library, being replaced by ui-seeds. View the Storybook.

Getting Started

If you're new to Bloom, follow the individual README files in each package first:

• api/: api/README.md
• sites/public/: sites/public/README.md
• sites/partners/: sites/partners/README.md
• model/: model/README.md

Local Environment Variables

Configuration is read from environment variables. Copy .env.template to .env in sites/public, sites/partners, api, and model. Some keys are secret and available internally. Template files include default values and variable descriptions.

VSCode Extensions

Recommended extensions for VSCode:

• Prettier: Enable Format on Save (⌘⇧P > Open User Settings > search Format on Save > enable, then Reload Window).
• Postgres Explorer: Inspect local database (see api/README).
• Code Spell Checker: Flags spelling errors.
• CSS Variable Autocomplete: Autocompletes ui-seeds CSS variables (see public/README).
• CSS Module Autocomplete: Autocompletes CSS module files.
• Python: Supports model development.

Local Development Setup

1. Install Dependencies

   yarn install
   cd api && yarn install

   If you don’t have Yarn installed, install Homebrew and run brew install yarn.

2. Environment Variables Copy .env.template to .env in each of sites/public, sites/partners, api, and model, then fill in any required secrets.

3. Run Everything

   yarn dev:all

   This starts:

   • Public: http://localhost:3000
   • Partners: http://localhost:3001
   • API: http://localhost:3100

Alternatively, run each process individually from separate terminals in api, sites/public, or sites/partners with yarn dev.

Risk Prediction Model (model/)

The model/app/ directory contains a Flask-based microservice powered by an XGBoost model to predict housing instability risk. It exposes a /predict endpoint and can be run standalone for local development or testing without requiring the full Bloom platform.

New Data & Training Workflow

1. Download AHS 2023 Data

   • Go to: https://www.census.gov/.../ahs-2023-national-public-use-file--puf-.html
   • Download the AHS 2023 National PUF v1.1 CSV zip and extract the CSV into model/data/.

2. Install Python Dependencies

   cd model
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Run Pipeline

   python pipeline/data_processing.py
   python pipeline/model_training.py

   • Outputs model/app/xgboost_model.pkl and model/app/scaler.pkl.

4. Start Flask Service

   python app/main.py

5. Testing

   # Local Flask tests
   pytest tests/test_prediction.py

Docker Usage

cd model
docker-compose up --build
# Local tests
pytest tests/test_prediction.py

Bloom UIC Development

Because Bloom’s ui-components package is a separate open-source repository, developing in Bloom while iterating in ui-components requires linking the folders:

Directory Setup

1. Clone both Bloom and the ui-components repository at the same directory level.

Symlinking UIC

1. In the Bloom directory, run yarn link:uic.
2. Open the next.config.js file in the public and partners directories.
3. Uncomment the experimental property at the bottom of each file.
4. Run Bloom locally with yarn dev:all. This allows local ui-components changes to reflect in Bloom’s node_modules.

Unlinking UIC

1. In the Bloom directory, run yarn unlink:uic.
2. Open the next.config.js file in the public and partners directories.
3. Comment out the experimental property.
4. Run Bloom locally with yarn dev:all. Bloom will use the published @bloom-housing/ui-components version specified in package.json.

📄 Contribution Guidelines

Contributions to Bloom’s applications and services are welcomed. To meet quality and maintainability goals, contributors must follow these guidelines:

1. Fork and clone the repo
2. Create a feature branch:
   git checkout -b feature/improve-validation
3. Code your change
4. Write/update tests
5. Commit with a conventional commit
6. Push and open a Pull Request to develop
7. Tag maintainers for review

Issue Tracking

• Development tasks are managed via GitHub Issues.
• Submit issues even if you don’t plan to implement them.
• Check for existing issues before creating new ones, and provide detailed descriptions with screenshots.
• Contact the Bloom team (@ludtkemorgan, @emilyjablonski, @yazeedloonat) before starting work to avoid duplication.

Committing

We adhere to Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/

• Install Commitizen globally:

  npm install -g commitizen

• Run git cz to generate well-formed commit messages, or write your own following the format:

  <type>(<scope>): <short summary>
  
  <detailed description>
  

Types include:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring (no feature change)
• test: Adding or updating tests
• chore: Maintenance (build config, etc.)

Pull Requests

• Target the main branch.
• Include the PR template with:
  • Issue reference (e.g., Closes #123).
  • Description of changes.
  • Testing instructions for reviewers.
  • A checklist of completed tasks.
• Label PRs appropriately:
  • needs review(s) when ready for review.
  • wip for work in progress.
• Reviewers:
  • Mark “Requested Changes” if further work is needed, or “Approved” when ready to merge.

License

MIT License