Partners Portal

The administrative Next.js dashboard for housing developers, property managers, and city/county staff to manage listings, applications, lotteries, and users.

The Partners Portal is the reference implementation of the Bloom Housing administrative interface. It runs as a Next.js application on port 3001 and provides housing partners — including housing developers, property managers, cities, and counties — with tools to manage listings, review and export applications, run lotteries, and administer users.

Features

Listing management

Create, edit, publish, close, and reopen affordable housing listings. Supports draft and published states.

Application management

View, edit, add, and export applications per listing. Separate views for pending and resolved applications.

Lottery management

Run and publish lotteries for closed listings. Lottery data expires after a configurable number of days.

User management

Invite, confirm, and manage partner users and advocates. Restricted to admin roles.

Admin functions

System-level administrative operations accessible only to admin users.

Settings

Manage jurisdiction preferences, multiselect questions, and property records. Shown when the feature flag is enabled.

User roles

Access to features within the Partners Portal is controlled by role. The following roles are supported:

Role	Description
admin	Full access to all features including user management and admin functions
jurisdictionalAdmin	Administrative access scoped to a specific jurisdiction
partner	Access to listings and applications for their associated properties
leasingAgent	Access to view and manage applications for assigned listings
supportAdmin	Support staff with elevated read access for troubleshooting

User management pages (/users) and admin functions (/admin) are restricted to users with the admin or jurisdictionalAdmin role. Accessing these pages without the appropriate role will redirect to /unauthorized.

Page structure

All pages live under sites/partners/src/pages/.

Authentication pages

File	Route	Description
index.tsx	/	Root redirect to listings dashboard
sign-in.tsx	/sign-in	Partner sign-in page
forgot-password.tsx	/forgot-password	Password reset request
reset-password.tsx	/reset-password	Password reset confirmation
unauthorized.tsx	/unauthorized	Shown when a user lacks permission for a page

Listing pages (/listings)

File	Route	Description
listings/add.tsx	/listings/add	Create a new listing
listings/[id]/index.tsx	/listings/[id]	Listing detail and edit overview
listings/[id]/edit.tsx	/listings/[id]/edit	Full listing edit form
listings/[id]/lottery.tsx	/listings/[id]/lottery	Lottery management for a listing

Application pages (/listings/[id]/applications and /application)

File	Route	Description
listings/[id]/applications/index.tsx	/listings/[id]/applications	All applications for a listing
listings/[id]/applications/add.tsx	/listings/[id]/applications/add	Add a paper/manual application
listings/[id]/applications/pending/	/listings/[id]/applications/pending	Applications pending review
listings/[id]/applications/resolved/	/listings/[id]/applications/resolved	Resolved/processed applications
application/[id]/	/application/[id]	View or edit an individual application

User management pages (/users)

File	Route	Description
users/index.tsx	/users	List and search all partner users
users/advocates.tsx	/users/advocates	Manage advocate accounts
users/confirm.tsx	/users/confirm	Confirm a newly invited user
users/terms.tsx	/users/terms	Terms of service acceptance

Admin pages (/admin)

File	Route	Description
admin/index.tsx	/admin	System administration dashboard

Settings pages (/settings)

Settings pages are only visible when the settings feature flag is enabled.

File	Route	Description
settings/index.tsx	/settings	Jurisdiction settings overview
settings/preferences.tsx	/settings/preferences	Manage listing preferences
settings/properties.tsx	/settings/properties	Manage property records
settings/multiselectquestions/preferences.tsx	/settings/multiselectquestions/preferences	Manage multiselect question sets

Running locally

1. Install dependencies

   From the monorepo root:

   yarn install
   
2. Configure environment variables

   Copy the template and set values for your local environment:

   cp sites/partners/.env.template sites/partners/.env
   

   Edit sites/partners/.env as needed. See the environment variables section below for details on each variable.

3. Start the backend and partners app

   From the monorepo root, this starts the backend on port 3100 and the partners portal on port 3001:

   yarn dev:all
   

   Alternatively, start only the partners portal from within sites/partners:

   yarn dev
   
4. Sign in

   Navigate to http://localhost:3001 and sign in with the default local development credentials:

   • Email: [e-mail]
   • Password: abcdef

The backend must be running on port 3100 before starting the partners portal. Sign-in and all data operations require an active API connection.

Environment variables

Copy .env.template to .env inside sites/partners/. The following variables control the app’s behavior:

API and backend

Variable	Default	Description
BACKEND_API_BASE	http://localhost:3100	Base URL for the backend API
BACKEND_PROXY_BASE	(empty)	If set, routes API calls through this proxy
LISTINGS_QUERY	/listings	Path appended to backend base to query listings
API_PASS_KEY	some-key-here	Shared passkey; must match the backend’s configured value

Application behavior

Variable	Default	Description
NEXTJS_PORT	3001	Port the Next.js app listens on
LOTTERY_DAYS_TILL_EXPIRY	45	Number of days after which lottery data is considered expired
ALLOW_SEO_INDEXING	FALSE	Set to TRUE in production only; enables search engine indexing

Third-party integrations

Variable	Default	Description
MAPBOX_TOKEN	(empty)	Mapbox API token for property map views
CLOUDINARY_CLOUD_NAME	exygy	Cloudinary cloud name for image uploads
CLOUDINARY_KEY	abcxyz	Cloudinary API key for signed uploads
CLOUDINARY_SIGNED_PRESET	test123	Cloudinary signed upload preset
RECAPTCHA_KEY	(empty)	Google reCAPTCHA site key
AXE_DEVELOPER_HUB_API_KEY	(empty)	Axe DevHub API key for automated accessibility reporting

Feature flags

Variable	Default	Description
SHOW_LOTTERY	FALSE	Enables lottery management UI within listing pages
SHOW_SMS_MFA	TRUE	Enables SMS-based multi-factor authentication (on by default)
APPLICATION_EXPORT_AS_SPREADSHEET	FALSE	Exports applications as a spreadsheet (.xlsx) instead of CSV
USE_SECURE_DOWNLOAD_PATHWAY	TRUE	Downloads exported files through a secure S3 private bucket pathway
LIMIT_CLOSED_LISTING_ACTIONS	FALSE	Restricts edit, republish, and reopen actions on closed listings
RUN_ACCESSIBILITY_E2E_TESTS	(empty)	Enables accessibility checks in the Cypress E2E suite

Testing

The partners portal has two test suites.

Cypress (E2E)

Run the full end-to-end test suite against a running instance of the app:

yarn test

Run from within sites/partners/ with the app already running on port 3001 and the backend running on port 3100.

Set RUN_ACCESSIBILITY_E2E_TESTS=TRUE in .env to also run axe-based accessibility checks during the Cypress suite.

Jest (unit/integration)

Run unit and integration tests:

yarn test:unit

Run with coverage reports:

yarn test:unit:coverage

Both commands run from within sites/partners/.