Qejaverse Project User Guide

Who this is for: QA, product, support, anyone new to QejaVerse.
What it's for: understanding what a project is and what should happen — so that when you test, you can tell the difference between "working as designed" and "something's wrong here."

You don't need to know anything technical to read this. There's a companion document, PROJECT_ANATOMY.md, for when you need field names and file paths — but read this one first.

1. The one-minute version

A project is a property development that a developer is selling — an apartment block, a gated community, an office tower.

On QejaVerse, a developer signs up, proves who they are, then builds out their project: what it's called, where it is, what it looks like, how many units, what they cost, what the legal paperwork says, who's on the sales team. Once it's complete enough and properly documented, they publish it — which opens it to QejaVerse's agents. Separately, they can put individual home types into the public marketplace, where ordinary buyers browse.

Everything in this document is one of those pieces.

2. The cast

One person can wear more than one hat — a developer can also be an agent elsewhere on the platform.

3. Before a project can exist at all

A developer can't just log in and start creating projects. Four things must be true first. If any is missing, they get stopped — and the stop should be clear and helpful, not a crash.

1. They have a developer profile. They signed up as a developer, not just as an agent or buyer.
2. Their profile is activated. Activation is the moment they become a real, verified developer on the platform — they've completed their company details and accepted the platform agreement. Before this, the project wizard should refuse to open and send them back to finish their profile.
3. Their company exists. Activation creates their company record automatically. This is the legal entity that will appear on contracts.
4. They have a free project slot. Their subscription plan limits how many projects they can have.

⚠️ Important for testing: on the free plan a developer can create one project only. If you're testing project creation repeatedly, you'll hit "Subscription Limit Reached" on your second one. Use a fresh developer account per project, or ask an admin to raise the limit. This is expected behaviour, not a bug.

4. Setting up a project — the guided journey

Project setup is a wizard: eight steps, one screen at a time, with a progress bar.

Two things about how it should feel:

• You can jump around. Click any step in the bar at the top. It's not locked into a straight line.
• It saves as you go. You should never lose work by clicking away or refreshing. If you refresh on step 5 and your step 2 answers are gone, that's a bug.

The project is created the moment you finish step 1. Everything after that is filling in an existing project.

The eight steps

Step 1 — Basics. The name, what kind of development it is, a description, budget, land size, timeline, and the shared facilities (pool, gym, security). The name must be unique within that developer's company — a different developer can use the same name.

This step also asks whether the project is sold under the developer's main company or under its own separate company. Big developers often set up a separate registered company per project. Whatever's chosen here ends up on the contracts buyers sign.

Step 2 — Due Diligence. The legal paperwork proving the project is real and permitted: title deed, approved building plans, environmental licence, construction permit, county permission, land search, company registration, tax compliance. Some expire and need renewal dates.

Which documents are required depends on what kind of project it is. This is the step that stops someone listing a development that doesn't legally exist.

Step 3 — Location. Address, city, county, and map coordinates. More important than it looks — buyers search by location, and a project with no city can never reach the public marketplace.

Step 4 — Media. Cover photo, logo, brochure, video, virtual tour, and a photo gallery. This is what makes a listing attractive. All optional, but a project with no images will look empty to buyers.

Step 5 — Structure. How the development is physically laid out. See section 5 below — this is the part people find most confusing.

Step 6 — Units. Creating the actual homes and pricing them.

Step 7 — Financials. What agents earn, when they earn it, payment terms, and the extra costs a buyer pays on top of the purchase price.

Step 8 — Review and Publish. A summary, a completeness score, and the button that makes it live.

The completeness score

There's a percentage at the top that climbs as the project is filled in. It's a weighted score across six areas:

As it climbs, the project moves through labels: Draft → Basic Setup → Structured → Ready for Review → Published.

⚠️ A trap worth knowing: at 100% the label says "Published" — but that's just the score label. It does not mean the project is actually live. A project is only live when someone clicks the Publish button. The two are completely separate. If you see a project labelled "Published" that isn't visible to agents, check whether it was ever actually published before raising it.

5. How a development is physically organised

This is the bit that trips everyone up. Four levels, nested inside each other.

Think of a housing estate:

The estate is the project.
It's being built in stages — Phase 1 and Phase 2.
Phase 1 has three blocks: Block A, Block B, Block C.
Block A has five floors.
Each floor has four apartments.
The apartment is what somebody actually buys.

In the system those are called:

Things that should happen automatically:

• Every new project gets a "Phase 1" created for it straight away. A developer building a single block never has to think about phases.
• If you tell the system a building has 8 floors, it creates those 8 floors for you.
• If you ask for 3 buildings without naming them, it names them Building A, B, C — and it won't reuse a letter that's already taken.

Things that should be protected:

• You can't delete a phase that still has buildings in it.
• You can't delete a building that still has units in it.
• You can't delete a unit that's been sold, reserved or booked.

Creating units in bulk is common — a 200-unit tower isn't typed in by hand. If you ask for 20 or more at once, the work moves to the background: you get told the job started and it finishes while you carry on. Fewer than 20 happens immediately.

6. Home types vs actual homes

Another common confusion, and worth being precise about.

A home type (the system calls it a unit type template) is the kind of home — "2 Bed Type A, 95 square metres, two bathrooms, one parking space, from KES 8.5 million." It's what you'd see in a brochure.

A unit is a specific home — "Apartment 304 in Block A" — which is either available, reserved, or sold.

You create the home type once, then apply it to fifty actual apartments so they all inherit the same size, layout and price.

The public marketplace shows home types, not individual apartments. A buyer browsing sees "2 Bed Type A, from KES 8.5M — 12 available." They don't see a list of 12 apartment numbers.

7. The money

Agent commission. What an agent earns for selling a unit — either a percentage or a fixed amount — and when they earn it: on sale, on deposit, once a percentage is paid, on full payment, or on handover.

How the project is sold. Two modes, and this shapes everything else:

• Marketplace (the default) — QejaVerse generates leads and passes them to the developer, who closes the sale themselves, offline. Commission is always paid on sale.
• Full — the entire sale happens on the platform: reservations, offer letters, digital signatures, payment schedules, a client portal. This requires the developer to have the full CRM enabled. If they don't, switching should be refused with a clear explanation.

Payment plans. How a buyer pays: cash, mortgage, 50/50, construction-linked, post-handover, and so on. A plan has a deposit percentage, a number of instalments, how often they fall due, and optionally a set of milestones ("30% on booking, 40% at roofing, 30% on handover").

Transaction fees. The extra costs a buyer pays on top of the purchase price — stamp duty, legal fees, registration. The standard Kenyan set is added automatically when a project is created, and the developer can adjust it. Some are paid to the developer, some to outside bodies like the Ministry of Lands.

Once a buyer is actually attached to a unit, their fees are frozen — later edits to the project's fee list must not change a deal already in progress.

8. The paperwork

Due diligence documents (step 2) prove the project is legitimate. Some are mandatory, some optional, and which is which depends on the type of project. All the mandatory ones must be uploaded before the project can go live.

Documents that expire — licences, permits, tax certificates — carry an expiry date. An expired document should be flagged as expired, not quietly accepted.

Document templates are different. These are the developer's own contract templates — offer letters and sale agreements — written once and reused for every buyer. They contain placeholders like buyer's name, unit number, final price, which get filled in automatically when a real offer is generated. The developer also controls what appears under each signature block.

9. The people

Every project has a team. The person who created it is automatically the project manager.

Others get added by invitation. Invite someone who already has an account and they're added straight away. Invite a new email address and they get a registration link, which expires after about a week.

Roles determine what each person sees: Owner and Project Manager see everything, Sales Manager can look but not change, Agent gets a read-only view of units, pricing and payment plans.

⚠️ A caveat you need to know before testing permissions: these roles only control what's shown on screen. They are not enforced behind the scenes. So a hidden button means "this person shouldn't do this", not "this person can't do this". Don't treat a missing tab as proof that an action is blocked.

Agents can also request access to a published project, which the developer approves or declines. A developer can require agents to sign a contract before getting access at all.

10. Going live — and why it's two switches, not one

This is the single most misunderstood part of the product, so read it twice.

Switch one: Publish

Publishing opens the project to QejaVerse's agents. It does not put it in front of the public.

To publish, all of these must be true:

1. Every mandatory due-diligence document is uploaded
2. The completeness score is at least 70%
3. The person clicking is the creator, a team member, or an admin
4. The project has a company attached
5. For marketplace projects: the developer has ticked the accuracy declaration — confirming the listing details are true
6. For marketplace projects: the developer has signed the current platform agreement, which sets out the commission terms

If any fails, the refusal should say exactly which one and what to do about it. A vague "could not publish" is a bug.

The Publish button also stays disabled until the developer's own profile is published. A project can't go live under a developer who isn't live themselves.

Switch two: Marketplace listing

Publishing isn't enough for the public to see anything. Each home type is listed separately, and only if seven things are all true:

1. The project is published
2. The developer's profile is published
3. The project has a city
4. The home type is active
5. It has a price
6. It has a name
7. At least one actual unit of that type is available

The system shows this as a checklist, so a developer can see exactly what's blocking them. Removing something from the marketplace always works instantly — the checks only apply when switching it on.

That last condition has a consequence worth knowing: when the final available unit of a type sells, that home type disappears from the marketplace automatically. That's correct behaviour, not a fault.

Unpublishing

Reverses it. The project goes back to being visible only to its own team, and anything of it in the public marketplace disappears.

11. Running the project after go-live

Once live, the developer manages it through a set of tabs: Units, Buildings, Phases, Media, External Links, Compliance, Due Diligence, Document Templates, Home Types, Payment Plans, Financials, Company, Team, Settings.

Some things lock once a project is live or has buyers — deliberately:

• A mandatory document can't be removed from a published project
• The company can't be swapped once the project is published or has buyers
• The company's legal identity — name, registration number, tax number — freezes once there are buyers, because it's already on signed contracts
• The developer who owns the project can never be changed

Compliance tracks the post-construction clearances a developer must obtain — land rent, land rates, sectional plan registration — before ownership can transfer to buyers. There's a counter showing how many buyers are waiting on these.

12. The special case: units sold before joining QejaVerse

A developer who joins mid-build has already sold homes. Those sales need to exist in the system, but they mustn't behave like live ones.

The developer declares how many were already sold, signs a legally-binding declaration confirming it, then records each historic sale through a short wizard.

Those historic units are marked as backfilled, which switches off all the automatic behaviour: no payment reminders, no overdue chasers, no reservation expiry, no signature requests. If a QA sees a historic sale generating reminder emails, that's a real bug.

13. How to tell when something's off

You won't have a spec for every screen. These are the smells worth trusting.

Numbers that disagree with each other. The header says 40 units, the list shows 38. The project says 12 available, but you count 9. Counts are calculated from the same underlying data and should always agree.

A success message where nothing happened. "Saved!" — then you refresh and your change is gone. This is the most common and most damaging class of bug, because the user walks away believing it worked.

Silence. You click something and get neither a confirmation nor an error. Either it worked and didn't say so, or it failed and didn't say so. Both are bugs.

A lock that doesn't hold. Anything section 11 says should be frozen — try to change it anyway. If it lets you, that's serious, because it means signed contracts can be contradicted after the fact.

Money that moves after a buyer is attached. A buyer's fees, prices and payment schedule should be settled the moment they commit. If editing the project changes what an existing buyer owes, that's a serious bug.

Something public that shouldn't be. Unpublish a project and check the public marketplace. Delist a home type and check again. Anything still visible is a problem. Allow a few minutes — public pages are cached — but not indefinitely.

Error messages written for programmers. Anything with a file path, a table name, or a wall of code is a bug in its own right, even when the underlying behaviour is correct. Users should get a sentence they can act on.

A gate that's easy to walk around. If publishing needs six conditions, try publishing with each one missing. Every one should refuse, and say which.

Vagueness where there should be specifics. "Cannot publish" is much worse than "Cannot publish: 2 mandatory documents missing — NEMA EIA Licence, Land Search Certificate."

14. Things that are already known to be odd

Don't spend time raising these — they're logged.

15. Vocabulary