Read me first

If you have just come across this project and you are wondering what it is, this page is the place to start. It assumes no technical background. There is no code here and no jargon that is not explained.

---

1. Who this is for

This software is built for the people who decide who gets to rent a home:

• Independent landlords with a handful of properties, who currently either pay a lot per applicant or make decisions on gut feel.
• Small and mid-sized property management companies running a leasing team across a portfolio, who need every agent to apply the same standards.
• Property technology companies who want screening built into a product they already sell to landlords, rather than sending customers off to a separate service.

If you rent homes to people, employ people who do, or build software for people who do, you are in the intended audience.

You do not need to be technical to read this document. You will need technical help to install and run the software, and you will find guidance on that further down.

---

2. What it does

When someone applies to rent a property, a landlord has to answer one question: is this a person I can rent to with confidence? Answering it responsibly means gathering information — credit history, criminal records, past evictions, income — weighing it consistently, and, if the answer is no, telling the applicant in a specific way that the law requires.

This software runs that entire process. It invites applicants to apply, collects their permission to run checks, gathers the reports, scores the application against rules you have set, and records every step as it happens. If the decision is a refusal, it walks you through the legally required notification process rather than leaving you to remember it.

The point of the product is not just the decision. It is being able to show, afterwards, exactly how the decision was reached.

---

3. The domain: renting, and the rules around it

Tenant screening in the United States is heavily regulated, and the regulation is the reason this software exists in the shape it does. Three things shape everything:

Credit reporting law. When you use a credit report or a background check to refuse someone housing, federal law — the Fair Credit Reporting Act, usually shortened to FCRA — treats that as a serious action with a required procedure. You must tell the applicant before you finalise the refusal, give them a copy of the information you relied on and a statement of their rights, then wait a defined period so they can dispute anything wrong, and only then send the final refusal. Skipping or reordering those steps is a common and expensive mistake.

Fair housing law. You may not discriminate, and that includes discriminating by accident. A rule that looks neutral but in practice excludes a protected group can still be unlawful. Federal housing guidance has been explicit that blanket bans on anyone with a criminal record are a problem, and that records should be assessed individually — considering what happened, how long ago, and whether it is relevant to being a tenant.

Local variation. On top of the federal rules, cities and states add their own: limits on when you may ask about criminal history at all, requirements to accept housing vouchers as income, and rules requiring you to accept a screening report the applicant already paid for rather than making them buy another.

The result is a job that is easy to do carelessly and hard to do well. The software exists to make the careful version the default.

---

4. Where it fits

The people who use it. Inside a landlord or management company, the day-to-day users are leasing staff processing applications, a manager or owner setting the rules and handling exceptions, and — occasionally but importantly — whoever answers when a decision is questioned.

The people it touches. Applicants never get an account. They receive an invitation link, fill in an application, and give their permission through that link. This is deliberate: a prospective renter should not have to create a login to apply for a home.

The systems around it. The software is designed to sit alongside services you already use, rather than replace them:

• Credit bureaus and background check providers supply the underlying reports.
• Bank-connection services verify income directly from the applicant's bank rather than from uploaded pay slips, which are easy to fake.
• Identity verification services confirm the applicant is who they say they are.
• Your existing property management system, if you have one, holds your properties, units and leases; screening is intended to be a step within your workflow rather than an island.

An interface for other software to connect to is included, which is how a property technology company would embed screening inside its own product.

---

5. Your first run

The quickest way to understand the product is to look at it with realistic information already in it.

A self-contained preview version is available that runs on one computer and needs nothing else — no separate database to install, no accounts to create. It starts up already populated: a fictional management company, a dozen applications spread across every stage of the process, two screening policies, and a compliance history. You can click through the whole thing without touching real data or real people.

Do this first, before anything else. Ask whoever is helping you technically to run the preview (preview/README.md has the instructions). Then walk through the screens in the order used in the guided tour: the dashboard, the application list, one application in detail, the screening criteria, and the compliance log.

Once you have seen it working, getting-started.md covers setting up a real installation.

---

6. Setting up your environment

Moving from "I have seen it" to "we are using it" involves four things.

Prepare a real system. A fresh installation starts empty and has to be initialised: your organisation, your first administrator account, and the baseline settings. This step wipes whatever is in the database, so it is done once, deliberately, at the start. production-initialization.md covers it, including the confirmation prompts that exist to stop anyone doing it by accident later.

Connect the data providers. The reports come from outside services, and you will need commercial accounts with them. Credentials are stored encrypted and are never displayed back on screen once saved.

Add your properties. The buildings and units you are letting, so an application can be attached to the specific home it is for.

Write your screening rules — carefully. This is the step worth slowing down for. Your minimum credit score, the income you require relative to the rent, how far back you look at criminal history, and how you treat what you find. These rules will be applied to every applicant identically, which is exactly the point: consistency is both the fairest approach and the easiest one to defend if a decision is ever challenged. When you save a policy, it is checked against the rules of the places you have said it applies in, before it is ever used on a person.

---

7. Day to day

For the people processing applications, an ordinary day looks like this.

Invite an applicant. They receive a link. They complete the application and give permission for the checks in the same place.

Let the checks run. Reports are gathered from the connected providers. Nothing is requested until permission has been recorded — the software will refuse.

Review what came back. Each application shows the reports gathered, the score against your criteria, and the reasoning behind it.

Decide. Approve, ask the applicant for more information, or refuse.

If refusing, follow the process. The software will not let a refusal be finalised in one step. It starts the required sequence: the advance notice, the waiting period, and only then the final notice. This is the single most valuable thing the product does for you.

Handle disputes as they arrive. If an applicant challenges something in a report, that is a normal part of the process and there is a place to record and work through it.

---

8. Ongoing care

A few things need attention beyond the daily work.

Records are kept for five years. That is aligned with the retention expectations around credit reporting. It is automatic, but you should know it is happening, and know that the compliance record is designed to be added to and never edited.

Review your rules periodically. Local rules change. So do the buildings in your portfolio. A policy written three years ago for one city may no longer be appropriate.

Watch for patterns, not just cases. The product can look at the aggregate effect of a proposed rule change before you adopt it. Reviewing this occasionally is a genuinely good habit, because a policy can be perfectly neutral in wording and still fall unevenly in practice.

Keep backups, and check them. As with any system holding sensitive personal information, the backup you have never tested is the one that will fail you.

Keep provider credentials current. Expired credentials mean checks stop returning, and the first sign is usually a report that never arrives.

---

What is actually built today

Being straightforward about this matters more than a longer feature list.

This is a core build: the functionality is real and working, but it is deliberately plain. There is no company branding, no logo, no styling. The screens show internal reference numbers in places where a finished product would show a person's name and a unit number.

The working screens are the dashboard, the application list, an individual application, the screening criteria, the compliance log, and the applicant's own application form. A number of capabilities — fraud detection on submitted documents, income verification through bank connections, disparate impact analysis, dispute handling, applicant data access and erasure — exist and work underneath, but are reachable through the programming interface rather than through a screen. Those screens are exactly the sort of thing that gets added when the product is adapted for a specific business.

---

The words people use

• Adverse action — refusing an application based on information in a report, and the formal notification process that must accompany it.
• Pre-adverse action notice — the advance warning sent before a refusal is final, giving the applicant a chance to correct wrong information.
• FCRA — the Fair Credit Reporting Act, the federal law governing the use of credit and background reports.
• Fair housing — the body of law prohibiting discrimination in housing.
• Disparate impact — when a neutral-sounding rule falls more heavily on a protected group in practice.
• Individualised assessment — considering the circumstances of a specific criminal record rather than applying a blanket exclusion.
• Ban-the-box — local rules restricting when criminal history may be asked about.
• Source of income protection — rules requiring housing vouchers to be treated as valid income.
• Portable report — a screening report the applicant already paid for, which in some places you are required to accept.
• Consent — the applicant's recorded permission to run checks. Nothing happens without it.
• Screening criteria — your written rules, applied identically to every applicant.
• Compliance chain — the record of everything done to one application, in order.

---

The other documents here

Document	What it is for
getting-started.md	Installing and running a real instance.
production-initialization.md	Preparing a live system for first use, and the safeguards around it.
useful-commands.md	Everyday operational commands.
testing.md	How the software is tested, and how to run those tests.
api-reference.md and openapi.yaml	The programming interface, for embedding or integrating.
website/	Public-facing material describing the product.
../preview/README.md	Running the self-contained preview.
../docs/walkthrough-screenshots/	The guided tour: screenshots and narration.

---

Who can do what

Four roles are available: owner, administrator, leasing agent, and viewer. The intent is that leasing agents process applications, administrators configure rules and providers, viewers can look but not act, and owners can do everything. Assign the narrowest role that lets someone do their job — particularly for viewer access, which is a good fit for anyone who needs oversight without the ability to change outcomes.

---

About the sample data

The preview arrives with invented information: a fictional property company, invented applicants, and a history of decisions that never happened. None of it refers to real people.

It exists so that every screen looks like a system in use rather than an empty shell. It is not a starting point for real work. When you set up a genuine installation you start from empty and initialise it properly — the two are separate paths on purpose, so demonstration records can never be mistaken for real applicants.

---

Common questions

Does this decide who gets the property? No. It gathers information, applies the rules you wrote, and shows you the reasoning. A person approves or refuses. That is a deliberate design choice, not a limitation.

Can I refuse someone in one click? No, and this is intentional. Refusals based on report information require a legally defined sequence, so the software starts that sequence rather than closing the case.

Do applicants need an account? No. They apply through a link and give permission in the same place.

Will this keep me legally compliant? It is built to make the compliant path the easy one, and it keeps the evidence you would need if a decision were challenged. It is not legal advice, and it does not replace a lawyer who knows your jurisdiction.

Why does it look so plain? Because it is a core build, on purpose. See "What is actually built today" above.

Can it be changed to fit how we work? Yes — that is the intended path. The software was AI-generated, which makes adapting it far quicker and cheaper than traditional development.

---

Where to get help

The community behind this project is at wbsp.ai. Go there to ask questions, suggest improvements, look at other versions of this and other applications that community members have built, or find someone who can adapt this into a product shaped around your business.