Design & Build Response

What this document is

Your developer pack specified the product. This document reports back against it: what exists today, what does not yet exist, the reasoning behind the choices that were made along the way, and what is required before anything can be deployed to a real broker.

It follows the same convention as the rest of the pack and is numbered into it as CF-DOC-06. The direction is simply reversed — your documents were prepared for the development team; this one is prepared for you.

What changed in this version

Version 1.0 reported the state of the build. It was accurate but thin in one respect: it showed you what had been decided without showing you why, and a design you are being asked to freeze cannot be assessed on its appearance alone. Approving a screen means approving the reasoning underneath it, and that reasoning was largely undocumented.

Version 2.0 therefore adds four appendices. Appendix A takes the call script line by line and gives the legal or commercial reason for each phrase — including the phrases that are locked and cannot be edited by a broker. Appendix B does the same for the broker-facing copy. Appendix C documents the compliance lint rule by rule, with the reasoning for each rule’s severity. Appendix D is a decision register showing what each open decision blocks and what it costs to defer.

The ten original sections are unchanged in numbering, so any reference already made to “§6.2” or “§9” remains valid. Their content has been deepened, and four substantive changes have been made to Version 1.0 — three corrections and one new finding. They are listed at §11 rather than made silently. One of them withdraws a claim Version 1.0 made about your pack, and is set out at §6 as well as in the log.

Every link in this document is private and requires access. They are not public URLs and will not resolve for anyone outside this project.

A note on sourcing

Every factual claim in this document about what the system does is drawn from the system itself rather than from intention. Where a claim rests on a specific piece of the build, the file is cited — for example, the three-attempt retry limit at §6.3 is db/migrations/0004_spec_gaps.sql, and the wording rules in Appendix C are apps/api/src/modules/scripts/script-lint.ts. This matters because the difference between “the system prevents that” and “we intended the system to prevent that” is the difference between a defensible position and an expensive surprise.

Against the success definition

CF-DOC-01 §1 sets a single test for whether this product works:

“A broker logs in on Monday, sees five verified appointments in their calendar for the week, listens to the recordings, and walks into the meetings prepared.”

CF-DOC-01 §1 — Definition of success

That sentence was treated as the design brief rather than an aspiration, and it drove a screen of its own. “Your week” is the Monday prep sheet: the first thing a broker sees when they log in at the start of the week, built to be read in the order that sentence implies.

Why the brief sits above the recording

The sequencing is a deliberate decision and worth defending, because the obvious alternative — leading with the audio, which is the more impressive artefact — is worse.

The brief comes first: who the person is, what they hold now, what they said they wanted, what the AI committed to on the call. The recording sits underneath it. A broker about to walk into a meeting needs the summary, and reaches for the audio only when a specific detail is worth checking. Put the player first and you force them to listen to six minutes to recover thirty seconds of substance — which, on a Monday with five appointments, is half an hour spent to learn what a paragraph would have told them.

The recording is not decoration, though, and it is not buried. It is the evidence behind the brief, and its presence is what makes the brief trustworthy: a summary with the source attached can be checked, and a summary that cannot be checked is just an assertion. The design gives the broker the fast path by default and the slow path on demand.

Why “verified” is a claim with evidence, not a badge

Every appointment carries its verification alongside it — how the appointment was confirmed, when, and by what means. This is the product’s central claim and it is the one most easily hollowed out, so it is worth being precise about what it means.

“Verified” is not a status the system awards itself for having placed a call. It means the appointment was confirmed twice: once on the call, in the client’s own words on a recording that is retained, and once by SMS, where the client replied to a message that named the broker, the date and the time. Both artefacts are stored and both are shown. The screen displays the evidence rather than asserting the conclusion.

That was a deliberate response to the pack’s emphasis on brokers not wasting mornings on appointments that were never real, and it is also what makes the commercial model defensible: a broker pays per verified appointment, so “verified” is the definition of a billable event. A billing trigger that the platform can award itself without evidence is a dispute waiting to happen. Appendix B.3 covers the wording of this claim in the public copy, where it has to survive contact with a sceptical reader.

The screen answers your success test as written. What it cannot yet do is answer it with a real broker’s real appointments, because the portal that would serve it is not built — see §4.

The three-month diary in §3.5 is the same information at a different altitude: the week answers “what am I doing now”, the diary answers “is the pipeline actually filling”. Both were needed; neither substitutes for the other.

The screens

Seven screens were designed and built as prototypes. Each is shown below with what it is, the specification area it answers, and the reasoning behind its structure. They share one design language, one palette and one set of components, so they read as a single product rather than seven pages.

Public landing page

The marketing face of the product — the page a broker reaches before they have an account. It carries the approved wording from CF-DOC-05 verbatim rather than paraphrased, so the claims made in public are the claims that were signed off, and the positioning, the objection handling and the compliance language are the ones you approved.

Structurally it answers the question a sceptical broker actually asks, which is not “what is AI” but “what lands in my diary and how do I know it is real”. The verification story is therefore load-bearing on this page rather than a footnote.

Two of your own copy decisions do a lot of work here and are analysed in Appendix B: the headline sells the outcome rather than the technology, and the pricing language commits to paying for verified appointments only. Both are defensible under the Consumer Protection Act’s rules on marketing claims precisely because the QA gate makes them literally true rather than aspirational.

Onboarding wizard

This screen exists to satisfy the first acceptance criterion in CF-DOC-01 §17: a broker registers, connects a calendar, tops up their wallet, builds a campaign and gets a script approved — unaided. No support call, no walkthrough, no hand-holding.

The wizard is therefore built as a single guided path with the state visible at every step, validation at the point of entry rather than on submit, and a cost estimate that updates as the campaign is defined so the broker understands what they are committing to before they commit.

The script step includes the compliance lint: prohibited wording is flagged as it is typed, with the rule that was broken named, so a broker learns the constraint rather than being rejected by a reviewer later. The lint is advisory rather than blocking for advice-like phrasing, and that is a deliberate design decision with a real argument behind it — Appendix C.4 sets it out. In short: a hard gate trains brokers to phrase around the wordlist rather than to write compliant copy, and it teaches the human reviewer to stop reading. Only a missing or tampered mandatory disclosure blocks submission outright.

One structural point that is invisible on paper: the mandatory disclosures are not lint rules at all. They live in locked blocks outside the editable body, so they cannot be edited away in the first place. The lint checks them as a tamper detector, not as the primary control. Appendix A explains what is in those blocks and why each clause is there.

This is the screen that most needs to be opened rather than read. On paper it is a form; in use it is the acceptance criterion.

Broker dashboard

The operational home screen: campaign state, wallet balance and burn, call outcomes, and the appointments that resulted. It answers the pack’s requirement that a broker can see at a glance whether the engine is working and what it is costing, without assembling that picture from four different screens.

The design bias here is towards outcomes over activity. Call volume is present but subordinate; appointments booked, appointments verified and cost per appointment are the figures given prominence, because those are the numbers a broker renews on. A dashboard that leads with dials placed would be flattering the platform rather than informing the customer — and under a pay-per-appointment model, dials are precisely the thing the broker is not paying for.

Your week

The Monday prep sheet described in §2. Briefs first, recordings underneath, verification attached to each appointment. This is the screen the success definition asks for, and it is deliberately the plainest screen in the product — it is read at speed, often on a phone, frequently in a car park before a meeting. Visual restraint here is a functional requirement, not a stylistic preference.

The figure for this screen appears in §2, where it answers the success test directly.

Three-month diary

The pipeline view. Where “Your week” is immediate, the diary is the horizon: appointments across a rolling quarter, so a broker can see density, gaps and whether the campaign is producing a pipeline or a spike. It answers the pack’s scheduling and capacity requirements — a broker cannot be booked into a week they cannot service, and the diary is where that becomes visible before it becomes a problem.

The quarter horizon is not arbitrary. It is long enough to show whether a campaign is sustaining a pipeline rather than front-loading it, and short enough that every appointment shown is one the broker can still prepare for or move.

Admin console

The operator’s side of the product, and the largest single screen. It carries the QA review queue, script review and approval, the cost centre, data-subject requests and the audit log.

Three parts of it are worth drawing out, because each answers a specific obligation rather than a convenience.

The QA review queue is keyboard-driven by design. A reviewer working through a queue of calls should never need the mouse, because the volume is the whole difficulty: every appointment must be reviewed before it is billed, so review throughput is the constraint on the business model. A queue that takes six seconds per item instead of two does not merely annoy the reviewer — it sets the ceiling on how many appointments can be sold in a day.

Data-subject requests are a first-class screen rather than a mailbox, because POPIA gives data subjects rights on a clock. A request that sits unlogged in someone’s inbox is a missed deadline that becomes a reportable failure, and “we did action it, we just cannot show you when” is not a defence. The screen exists so the clock is visible and the response is recorded.

The audit log exists because every claim this product makes about consent, verification and approval has to be provable after the fact, to a regulator, without reconstructing it from application logs. Appointment status changes are written by a database trigger rather than by application code (§8.1), which means no code path can change a status without leaving evidence — including a code path written in a hurry two years from now.

The portal

All of the above assembled behind one navigation, so the product can be walked end to end as a broker would actually experience it, rather than as seven separate pages. If only one link is opened, this is the one — it contains the others.

What is built, and what is not

The honest position, component by component. Where something is not built, it is stated as not built. The column that matters most is the third one, because “built” without a statement of what was verified is a claim rather than a report.

The five decisions only you can make

Five decisions are outstanding. None of them are technical, none can be answered by the development side, and each blocks work that cannot sensibly start without it. They are listed in the order they unblock the most. Appendix D sets out the same five as a register, with what each one blocks and what deferring it costs.

The South African compliance position

Two compliance findings emerged during the build. Both are material and one bears directly on the commercial model rather than merely on paperwork. A third item follows from them: a place where the system as specified and built conflicts with the legal reading, set out at §6.3.

Direct marketers must register with the National Consumer Commission

The Consumer Protection Act Amendment Regulations came into force on 15 April 2026, with no transitional period. There was no grace window and no phase-in; the obligations applied on the day.

This is the one finding genuinely absent from the pack — the National Consumer Commission, the registration requirement and the cleansing fee are not mentioned in any of CF-DOC-00 through CF-DOC-05. It is raised here as a gap rather than as news, and the practical consequence is the same either way: the obligation has been live since April and is not waiting for launch.

Three obligations follow for any direct marketer:

• Registration with the National Consumer Commission, renewed annually.
• Monthly database cleansing against the national opt-out registry — not on campaign launch, not quarterly, monthly.
• A fee charged per record, per month for that cleansing.

The third point is the one with commercial teeth. The fee scales with database size and recurs every month regardless of whether a record is ever called. At 100,000 records the cleansing cost is in the region of R12,000 per month. That is a standing cost of operating, and it belongs in the price before the price is set — which is a direct input into decision B1.

There is a second-order effect worth naming: because the fee is charged per record held rather than per record called, holding a large unworked lead database is now expensive by itself. A strategy of acquiring volume and working through it slowly is penalised monthly. This argues for smaller, better-qualified lead sets, which happens to align with the direction §6.2 pushes for independent reasons.

Marketing calls are opt-in, not opt-out — as your pack already recognised

This is not a new finding, and Version 1.0 was wrong to present it as one. Your own specification states the position precisely:

“The Information Regulator’s Guidance Note on Direct Marketing (December 2024) treats outbound marketing calls as electronic communication requiring prior consent — the platform is built consent-first: no provable consent, no dial.”

CF-DOC-01 §13 — Compliance

CF-DOC-04’s risk register says the same thing in the mitigation column: “consent-first design already assumes the strict reading; monitor Information Regulator; kill-switch per campaign.” The instruction was correct and the build followed it — the consent gate at §8.1 is that instruction expressed in the database.

What is worth restating is the consequence, because it is sharper than “get consent first” suggests. A telephone call is an electronic communication under POPIA s69. Under that reading, approaching a person who is not already a customer is constrained to one approach, and that approach may only be made to request consent. Consent must be read aloud on the call and the recording retained as the record of it. There is no second attempt if consent is not given.

That last sentence is where the pack and the build diverge, and it is the genuinely new material in this section — see §6.3.

Consistent with that, your copy in CF-DOC-05 already assumes the warmer model. The homepage says CallForge “phones consented prospects”, the proof strip says “consented data only”, and one of your three tagline options is “Appointments, not cold calls.” The approved public wording needs no revision — which is not luck but the same consent-first reading applied to the marketing, and is analysed in Appendix B.1.

Where the built system conflicts with this reading

This is the genuinely new material in this section, and the most actionable. It was not stated in Version 1.0. Unlike §6.1 and §6.2 it is not a question of what the law says — it is a conflict between two parts of your own pack that only became visible once both were built.

CF-DOC-01 §6.4 specifies a retry pattern, and it is built as specified: a lead that does not answer or asks to be called back is retried, with attempts spread across different days and different parts of the calling window. The platform default is three attempts per lead per campaign (db/migrations/0004_spec_gaps.sql), and the objection-handling branch in your own script at CF-DOC-05 §6.1 offers to “call back tomorrow morning or afternoon”.

Against the one-approach reading of s69, that is three approaches where the law appears to permit one, for any person who is not already a customer of the brokerage.

The conflict is not fatal, and it does not require abandoning the retry pattern. It requires the retry limit to become conditional on the lawful basis of the lead rather than a single platform-wide default:

• Existing customers called under the s69(3) similar-products exception — the retry pattern stands as specified and built. There is an established relationship; repeat contact with a working opt-out is the ordinary case the exception contemplates.
• Leads carrying recorded consent to be contacted — retries are defensible to the extent the consent wording covers being contacted more than once. This is a drafting question for D1, and it should be settled in the consent wording at source rather than argued afterwards.
• Everyone else — one approach, consent-only, no retry. A no-answer is not a permission to try again.

Mechanically this is a small change: the attempt cap moves from one platform-wide number to a value resolved per lead from its consent record, and the scheduler already reads the cap from configuration rather than hard-coding it. It is called out here because it is exactly the kind of item that is cheap now and expensive after launch — and because it is a case where the system does what your specification asked for, and the specification predates the guidance. It is flagged, not fixed, because the correct values depend on D1.

The immediate effect on §5 is that D1 moves from important to blocking. Where platform leads come from, and the exact wording under which those people consented, is now the question that determines whether the calling model stands up. It cannot be settled after launch.

Recommendation: a POPIA-literate attorney should review the calling flow before launch — specifically the consent script, the s69(3) reliance where existing customers are called, the retry policy set out above, the retention of consent recordings, and the opt-out mechanism. This is a review of the flow itself, not only of the published documents.

Legal documents

A Privacy Policy and Terms of Service exist as attorney-ready drafts. They are drafts in a specific sense: the structure is correct, the factual content is accurate because it was drawn from the actual system rather than from a template, and every point that depends on an unmade decision is marked as an explicit blank rather than filled with a plausible guess.

32 attorney notes are raised across the two documents, each flagging a point that needs legal judgement rather than drafting.

They cannot be finalised yet, for two reasons. The first is §5: several clauses depend directly on the five open decisions, and cannot be written until those land. The second is more important — a published policy binds whoever publishes it. A Privacy Policy is a statement of fact about what a system does with personal information, and publishing one that overstates or understates the position creates liability rather than covering it. These need an attorney’s review before they go live, not after.

Special personal information: the race field

The database carries a race field on the lead record. Under POPIA s26 that is special personal information, which requires a higher lawful basis to process and attracts materially greater obligations and exposure.

Three controls govern it, and all three are built:

• It is discarded at the door unless consent covers it. On lead import, the value is written only where the lead’s consent record explicitly covers special personal information; otherwise it is dropped at ingest rather than stored and filtered later (apps/api/src/modules/leads/leads.service.ts). The distinction matters: data that was never stored cannot leak through a future query written by someone who did not know the rule.
• It is not broker-selectable. Race is absent from campaign targeting by design rather than by oversight, and your own specification is the reason — CF-DOC-01 §4.2 states it is “not broker-selectable … kept out of the broker wizard entirely on legal-risk review”. The build honours that.
• Any admin-side use is gated and logged. Special-category matching is a separate path, permitted only where the consent record carries the flag, and audit-logged when used.

So the position is better than Version 1.0 described: the field is consent-gated, excluded from the broker-facing product, and audited. Your own pack anticipated the risk and the build implements what it asked for.

The recommendation nonetheless stands: consider removing the column entirely. The argument is no longer “it is unused and therefore pointless” but something narrower and more practical — the controls above are correct, but they are controls that must go on being correct through every future change, migration and query. Special personal information that delivers no identified product benefit is a permanent compliance surface maintained for no return. Removing it retires that surface completely rather than defending it indefinitely.

If there is a business reason to retain it that has not surfaced on the development side — a reporting obligation, a carrier requirement, a targeting use you intend later — that reason needs to be stated, so the lawful basis can be documented properly and the field can be justified rather than merely defended. This is a question for you and the attorney together; it is not a decision the development side should take alone in either direction.

Technology, briefly

The full reasoning is its own document — Technology stack, and why. In summary: a NestJS/TypeScript API, PostgreSQL with row-level security, a Next.js portal, a Python voice agent, running on AWS Cape Town, provisioned by Terraform.

Two architectural arguments are worth making here rather than leaving to the appendix, because both are commercial rather than technical.

The database enforces the rules, not the application code

Three rules in this system would end the business if broken. Each is enforced one layer below where bugs happen. Your own START_HERE document names two of them as non-negotiables, and the build takes them literally.

• Tenant isolation is row-level security. One brokerage must never see another’s leads, calls or customers. That is enforced by the database, not by remembering to add a filter to every query — so a bug that forgets the filter still cannot return another brokerage’s data. It returns nothing.
• Money is an append-only ledger. Balances are computed from rows rather than stored as a number that gets edited. The database physically refuses updates and deletes on ledger rows; a correction is posted as a compensating entry, so the original movement remains visible. A wallet balance cannot be quietly adjusted, because there is nothing to adjust — there are only entries, and every entry stays. Disputes about what a broker was charged are answerable from the record, and an appointment can be charged exactly once because a unique index says so.
• A lead without consent is unreachable by the dialler. Not flagged as off-limits and relied upon to be respected — unreachable. The scheduler selects from a view that joins consent and excludes the do-not-call list, and that view is the single definition of “may we call this person”. Given §6.2, this is the constraint that most needs to hold under pressure, and it holds structurally.

The commercial framing is straightforward: these are the failures that would be existential rather than embarrassing, so they are placed where application bugs cannot reach them. It costs more to build this way. It costs considerably less than a cross-tenant data leak reported to the Information Regulator, or a billing dispute that cannot be answered from the record.

There is a second benefit that matters for what comes next. The portal is the largest remaining piece of work (§4), and it will be built at pace. Rules that live in the database do not weaken because a screen was built quickly.

Every external service sits behind an interface with a mock

Telephony, AI providers, payments, email — each is accessed through an interface, with a mock implementation used in testing. This is why the 55 tests in §4 can run against a live database without placing a single real call or charging a single real card.

It also has a concrete payoff already realised: swapping Twilio for Utility Connect touched no business logic. The campaign rules, wallet arithmetic, consent checks and scheduling did not change, because none of them ever knew which supplier was carrying the call. The new work is confined to the telephony layer — which, per §4, is real work, but it is contained rather than spread through the system.

This is worth registering as evidence rather than as a design preference. The supplier change was not anticipated when the interfaces were drawn, and it still cost nothing in the core of the system. That is the return on the extra cost noted above, collected once already, before launch.

What “frozen” can and cannot mean

You have asked that the design be perfected now and held unchanged until deployment. The intent behind that is right — a design that keeps moving never ships, and a build that chases a moving target wastes effort. It is worth being precise about what can be locked and what genuinely cannot, so that “frozen” means the same thing on both sides.

What can be frozen, and should be

• The design language — typography, spacing, component behaviour, the whole visual system.
• The palette and brand voice — settled, consistent across all seven screens and both legal documents.
• The information architecture — what lives on which screen, and in what order a broker meets it.
• The verification story — how an appointment proves it is real, and how that proof is presented. This is the product’s central claim and it should not move.
• The compliance rules as encoded in the flows — the consent gate, the script lint, the audit trail.
• The locked script blocks — the mandatory disclosures at Appendix A.1. These are the most stable text in the product, because they are set by law rather than by preference.

That is the majority of the design, and it is genuinely stable. It can be signed off today. Version 2.0’s appendices exist partly to make that sign-off meaningful: approving wording whose reasoning is documented is a decision, where approving wording on sight is a hope.

What cannot be frozen, honestly

Anything downstream of the five open decisions. The price alone is instructive: B1 touches the wizard’s cost estimate, the wallet and top-up screens, the pricing section of the landing page and a clause in the Terms. Freezing screens that contain a placeholder number does not freeze them — it defers the change to a less convenient moment.

The legal position, which is still settling. The Information Regulator’s guidance on s69 dates from December 2024, but how strictly it is applied to voice calls is being worked out now, and the NCC regime at §6.1 has been in force only since April. §6.3 is a live example of what that produces: a retry pattern built exactly to CF-DOC-01 §6.4 needs a condition on it that follows from CF-DOC-01 §13 — two parts of the same pack, consistent on their own and in tension once built. If the consent model tightens further, the screens that carry consent move with it. That is outside anyone’s control here.

Whatever the first pilot broker surfaces. No amount of review substitutes for one real user with their own leads, their own book and their own way of working. They will find something — a step that reads clearly to us and not to them, a field that matters more than we assumed, a workflow that does not match how they actually run their week. That is the point of a pilot, and a design that cannot absorb it was frozen too early.

What is needed to proceed

Four things, in the order they unblock the most.

The five decisions

B1, D1, A1, D3 and D2, per §5 and Appendix D. These are the constraint on nearly everything else in this list. D1 is now the most urgent of them for the reasons given in §6.2 and §6.3 — it determines whether the calling model is cold or warm, it sets the retry policy, and that determines what the product is.

Start the long-lead items now

Three items take calendar time that cannot be compressed and should be started in parallel with everything else:

• NCC registration. This is not a launch task — it is already legally required of any direct marketer, and has been since 15 April 2026. It depends on D3, because it registers a specific legal entity.
• Google’s OAuth app review, needed for calendar integration. Two to six weeks, and it cannot begin until the domain is registered and verified — so A1 gates it. Every week the domain is not registered is a week added to the end.
• Utility Connect trunk provisioning. Supplier lead time, plus the SIP and RTP work described in §4 that follows it.

An attorney briefed

A POPIA-literate attorney, briefed on the calling flow as well as the documents. The scope is: the s69 position and whether the intended model relies on s69(3) or on recorded consent; the retry policy at §6.3; the consent script and how it is captured on the call; the retention of consent recordings; the race column at §7.1; and the 32 notes raised across the two drafts. Appendix A is written to be handed to them directly — it sets out each clause of the script and the reason it is worded as it is, which is the form a review is cheapest to run against.

This should happen before launch, not at it.

A first pilot broker chosen

The build has to target someone specific. Which broker is chosen changes what gets built first — and per §6.2, whether that broker has an existing customer book materially changes which calling model the first deployment can actually use. This is D2, and it is the decision that turns a specification into a plan.

Revision log

This document is numbered into your pack and will be revised as decisions land. Changes are recorded here rather than made silently, so that a version you approved can be distinguished from a version you have not yet read.

Substantive changes in Version 2.0

Three corrections and one new finding. They are called out individually because each changes something you might act on.

Everything else in Versions 1.0 and 2.0 agrees. Section numbering is unchanged, so references made against Version 1.0 remain valid.