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 |
Page structure
All pages live undersites/partners/src/pages/.
Authentication 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)
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)
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)
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)
Admin pages (/admin)
| File | Route | Description |
|---|---|---|
admin/index.tsx | /admin | System administration dashboard |
Settings pages (/settings)
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
Configure environment variables
Copy the template and set values for your local environment:Edit
sites/partners/.env as needed. See the environment variables section below for details on each variable.Start the backend and partners app
From the monorepo root, this starts the backend on port 3100 and the partners portal on port 3001:Alternatively, start only the partners portal from within
sites/partners:Sign in
Navigate to http://localhost:3001 and sign in with the default local development credentials:
- Email:
[email protected] - 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
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
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
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
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)
- Jest (unit/integration)
Run the full end-to-end test suite against a running instance of the app: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.