DEV Community: mobius-crypt

Building South Africa’s Procurement Data Infrastructure With a Public API

mobius-crypt — Fri, 29 May 2026 08:39:10 +0000

Most South African tender platforms are still operating like classified ad websites.

Search page.
PDF upload.
Email alerts.
Maybe a spreadsheet export.

That model breaks the moment developers, analysts, or enterprises need structured procurement intelligence at scale.

At Tenders SA, we started approaching the problem differently:

What if procurement data was treated like infrastructure instead of content?

That question led to the development of the Tenders SA API platform.

The Problem With South African Tender Data

If you've ever worked with procurement data in South Africa, you already know the pain points:

fragmented publishing standards
inconsistent tender formats
scanned PDFs with unusable text
missing metadata
duplicate tenders
difficult supplier tracking
no standardized API access
no reliable machine-readable structure

Most integrations end up relying on:

scraping HTML pages
parsing broken PDFs
manual cleanup pipelines
brittle automation

That architecture does not scale.

Especially if you're building:

procurement intelligence platforms
ERP integrations
supplier analytics
AI procurement tools
bid recommendation systems
compliance dashboards
tender monitoring services _ We wanted something developers could actually build on top of._

Treating Procurement Data Like Infrastructure

Instead of exposing the same frontend database through a thin API layer, the Tenders SA API runs on its own dedicated infrastructure stack.

That separation matters.

The API platform has:

its own database layer
dedicated indexing systems
structured procurement normalization
enrichment pipelines
rate limiting
independent scaling
AI extraction services

The goal was simple:

Provide procurement data that is already normalized, structured, and usable before it reaches the developer.

The Real Problem Is Not "Finding Tenders"

The real problem is understanding procurement activity at scale.

There is a massive difference between:

“Here is a tender PDF”

and

“Here is structured procurement intelligence.”

That difference is where most platforms fail.

Raw documents are not enough anymore.

Developers need:

searchable metadata
supplier tracking
standardized entities
award visibility
category classification
province-level segmentation
organization normalization
machine-readable procurement timelines

That is what modern procurement systems require.

OCR Alone Is Not Enough

One of the biggest misconceptions in govtech is that OCR solves procurement digitization.

It doesn’t.

OCR only extracts text.

The actual challenge starts after extraction:

entity detection
normalization
deduplication
classification
metadata inference
document structuring
tender lifecycle tracking

A scanned municipal PDF with inconsistent formatting is not useful to software systems until it becomes structured data.

That processing pipeline is where most of the engineering complexity exists.

Building the API Around Real Developer Workflows

Most government APIs are designed around bureaucracy.

We designed this one around implementation reality.

The API supports:

pagination
filtering
structured search
procurement metadata access
supplier information
organization-level data
normalized tender entities
machine-readable responses

The goal is reducing the amount of cleanup developers must do themselves.

Because every hour spent fixing procurement data is an hour not spent building actual products.

What Developers Can Actually Build

The interesting part is not the API itself.

The interesting part is what becomes possible once procurement data is accessible programmatically.

Some examples:

Supplier Intelligence Platforms

Track:

competitors
procurement history
award patterns
regional activity
sector specialization
Bid Recommendation Systems

Use procurement history and category data to surface:

relevant tenders
supplier fit
geographic opportunities
estimated competition
AI Procurement Assistants

Structured procurement data enables:

semantic search
automated summarization
tender classification
supplier matching
compliance analysis
Municipal Analytics Dashboards

Analyze:

spending trends
procurement activity
department-level behavior
provincial procurement movement
ERP and Internal Procurement Integrations

Instead of manually checking portals, companies can ingest procurement activity directly into internal systems.

That changes procurement monitoring from reactive to automated.

Why Public Developer Infrastructure Matters

South Africa’s procurement ecosystem has historically lacked developer-grade infrastructure.

That slows down innovation across the entire sector.

Developers should not need to:

scrape procurement websites
reverse engineer PDFs
maintain fragile parsers
manually normalize data

Good infrastructure compounds innovation.

Once APIs, SDKs, widgets, and documentation exist, entire ecosystems can emerge around them.

That is how mature developer platforms evolve.

The Ecosystem Layer

The API is only one part of the system.

The broader Tenders SA developer ecosystem also includes:

frontend widgets
SDK packages
public documentation
GitHub repositories
embeddable procurement components

The objective is making procurement data easier to integrate into:

SaaS platforms
dashboards
analytics systems
enterprise software
AI workflows

without requiring every team to rebuild procurement infrastructure from scratch.

Government Data Should Be Easier To Build On

South Africa produces enormous amounts of procurement data every year.

The problem has never been lack of information.

The problem has been accessibility, structure, and usability.

There is still a huge amount of work remaining:

better normalization
deeper entity resolution
improved award tracking
procurement graph relationships
AI enrichment
historical analytics

But procurement technology in South Africa is finally starting to move beyond static portals and toward programmable infrastructure.

And honestly, that transition is overdue.

Developer Resources

Developer Portal:
https://www.tenders-sa.org/developers

API Documentation:
https://www.tenders-sa.org/documentation/api/tenders

GitHub Organization:

Tenders SA · GitHub

Tenders SA , is South Africa's Tender Matching and Application Assistance Portal - Tenders SA

github.com

NPM Organization:

npmjs.com

Main Platform:

Tenders SA - AI-Powered Tender Matching for South African Tenders

Find and win South African tenders with AI-powered matching. Browse government contracts, municipal RFQs, and state-owned enterprise opportunities.

tenders-sa.org

We Built Embeddable Procurement Intelligence Widgets for South African Publishers

mobius-crypt — Wed, 27 May 2026 15:35:39 +0000

South African government procurement data is technically public.

But if you’ve ever tried to work with it, you already know the reality:

fragmented portals,
inconsistent award records,
unstructured PDFs,
broken search experiences,
and almost no tooling for publishers or developers.

Most procurement reporting still looks like screenshots pasted into articles or manually maintained spreadsheets that go stale within days.

We wanted to solve that properly.

So we built a free publisher platform that lets blogs, media sites, and developers embed live procurement intelligence widgets directly into their websites.

No API keys.
No backend integration.
No database maintenance.

Just copy, paste, and publish.

The Problem With South African Procurement Data

South Africa publishes thousands of tender opportunities and contract awards every month through multiple government procurement systems.

The raw data exists, but using it at scale is painful.

Even basic editorial questions are difficult to answer:

Which companies are winning contracts?
Which provinces are spending the most?
Which sectors are seeing procurement growth?
Which suppliers dominate specific industries?

Most publishers do not have:

data engineering teams,
procurement analysts,
ETL pipelines,
or infrastructure to continuously process OCDS-style datasets.

That means procurement journalism often becomes static and reactive instead of live and data-driven.

We thought procurement intelligence should behave more like embeddable web infrastructure.

The Publisher Platform

We built the Tenders SA Publishers Hub to expose live procurement data through embeddable widgets and public APIs.

The widgets update automatically from our procurement aggregation pipeline and can be embedded into:

WordPress,
Ghost,
Webflow,
Shopify,
Next.js,
React,
or plain HTML websites.

The system currently exposes:

Winners Feed Widget
Sector Trends Widget
Top Companies Leaderboard
Provincial Heatmap

The widgets are powered by the same OCDS-aligned procurement database used internally across the Tenders SA platform.

Winners Feed Widget

This became the most requested widget almost immediately.

It renders a live stream of recently awarded government contracts including:

supplier names,
award values,
provinces,
sectors,
and awarding entities.

Instead of manually updating procurement tables, publishers can embed a real-time award feed directly into articles or sidebars.

The data refreshes automatically every hour.

Example use cases:

investigative journalism,
procurement monitoring,
regional business news,
industry-specific contract tracking.

A construction publication can filter for construction awards only.
A provincial portal can track local government spending.
An ICT publication can surface software and cybersecurity contracts.

Sector Trends Widget

The Sector Trends Widget is designed more like a lightweight procurement analytics layer.

It visualises:

sector-level procurement activity,
rolling award values,
and market movement across industries.

For editorial teams, this solves a major problem:
most procurement reporting talks about “increased spending” without actual data visualisation.

Now an article discussing infrastructure growth can embed live procurement trend charts directly beside the analysis.

The widget supports filtering by:

province,
category,
and sector.

The data updates continuously from the underlying procurement aggregation pipeline.

Top Companies Leaderboard

This widget surfaces which suppliers are capturing the most government procurement value.

It ranks companies by:

total award value,
contract activity,
province,
and category.

This became surprisingly useful for:

economic development portals,
local business publications,
procurement consultants,
and supplier intelligence tracking.

Instead of manually building leaderboards from spreadsheets, publishers can embed live rankings directly into their sites.

The API Layer

The widgets themselves are powered by a public REST API.

Endpoints currently include:

/api/widgets/winners-feed
/api/widgets/top-companies
/api/widgets/sector-trends

The API is intentionally simple:

JSON responses,
no OAuth,
no API keys for basic usage,
and lightweight enough for direct frontend integration.

Example:

fetch('https://www.tenders-sa.org/api/widgets/top-companies?province=gauteng&limit=5')
.then(res => res.json())
.then(data => console.log(data))

We wanted publishers and developers to integrate procurement intelligence without building an entire procurement platform themselves.

Why We Avoided “Enterprise Procurement Software” Complexity

A lot of procurement tooling collapses under its own complexity.

Heavy dashboards.
Complex onboarding.
Locked APIs.
Enterprise sales cycles.
Mandatory integrations.

That approach excludes:

independent publishers,
small media teams,
niche industry blogs,
and local developer communities.

Our goal was different:
make procurement data as embeddable as a YouTube video.

That heavily influenced the architecture:

iframe embeds,
lightweight JS widgets,
edge caching,
CDN delivery,
zero-auth public endpoints,
and no-code configuration.
OCDS Matters More Than Most People Realise

One of the hardest parts was not the frontend widgets.

It was standardising procurement data.

Government procurement records are messy:

supplier names vary,
categories are inconsistent,
notices arrive in different formats,
and award structures differ between entities.

The platform normalises this data into a structured model aligned with OCDS principles before it reaches the widget layer.

Without that normalisation layer, live procurement widgets would become unreliable very quickly.

The Unexpected Outcome: Procurement Syndication

The original idea was just embeddable widgets.

What emerged instead was a procurement syndication network.

Publishers started embedding live procurement intelligence into:

local business portals,
sector-specific blogs,
procurement newsletters,
municipal information sites,
and trade publications.

Instead of procurement data living only inside government portals, it now flows through the broader South African web ecosystem.

That distribution effect matters more than the widgets themselves.

Developer Experience Was a Core Requirement

Most government-adjacent tooling has terrible developer experience.

We wanted:

simple embeds,
predictable APIs,
lightweight integration,
and framework compatibility.

The widgets work with:

React,
Next.js,
Vue,
WordPress,
Ghost,
Shopify,
Webflow,
and static HTML.

No vendor lock-in.
No proprietary CMS requirements.

Repositories & Developer Resources

Main platform:
https://www.tenders-sa.org

Publishers Hub:
https://www.tenders-sa.org/publishers

Developer API docs:
https://www.tenders-sa.org/publishers/developers

Example widget integrations and SDK snippets are available throughout the developer portal.

Final Thoughts

South African procurement data should not require a data engineering team to understand.

Publishers should be able to:

embed it,
analyse it,
visualise it,
and distribute it easily.

That was the core idea behind the publisher platform.

The widgets are not the product.

The real product is turning fragmented public procurement data into infrastructure developers and publishers can actually build on top of.

Company Tender Intelligence Reports: What Tenders-SA Knows About Your Competitors (And How to Use It)

mobius-crypt — Tue, 24 Feb 2026 06:28:31 +0000

*Part of the ongoing Tenders-SA engineering series. Previous articles covered the

The Question Every Serious Bidder Asks

Before submitting a tender, experienced procurement officers ask one thing first: who else is likely to be bidding, and what do they know that we don't?

Until recently, answering that meant hours of manual searching across OCDS portals, government gazette archives, and eTender records — extracting award data company by company, building spreadsheets by hand, and still ending up with an incomplete picture.

The Company Tender Intelligence Hub on Tenders-SA automates this entirely. Here's how it works, what's inside the reports, and why the underlying data model makes it more powerful than a simple award lookup.

The Data Foundation: 28,000+ Award Records and Growing

The platform's company intelligence features are built on a continuously updated awards database sourced directly from South Africa's Open Contracting Data Standard (OCDS) feeds. At the time of writing, the database contains:

28,179 tender awards with full structured metadata
30,186 individual tender reports linked to issuing authorities
Award values, dates, provinces, categories, and winning entity names

This isn't scraped or estimated data. It comes from official government procurement disclosures, normalized into a consistent schema so that a construction award from the Eastern Cape and an IT services contract from Gauteng can be compared directly.

What a Company Intelligence Report Contains

When you search a company in the hub, the platform generates a structured report across five dimensions:

1. Full Award History

Every government contract the company appears in as an award recipient, sorted by date. Each entry shows the issuing authority, tender category, disclosed value, province, and original reference number.

This is the baseline — but it's the starting point, not the conclusion.

2. Win Rate Analysis

The system calculates how often a company appears as a winner relative to how often the same tenders (by category and province) attracted multiple disclosures. Where OCDS data includes competing bid counts, the platform surfaces an estimated win rate.

For a company evaluating whether to enter a new sector, knowing that a competitor converts 1 in 3 bids in that category (vs. 1 in 12 for the market average) is a significant strategic signal.

3. Sector and Geographic Concentration

A breakdown of where the company wins — which provinces, which categories, which issuing authorities appear most frequently. The visualization shows whether the company is a generalist or a specialist, and whether their success is geographically concentrated.

Award Distribution Example:
├── Gauteng: 61%
│   ├── IT Services: 40%
│   └── Professional Services: 21%
├── Western Cape: 28%
│   └── Construction: 28%
└── National: 11%

This matters enormously when deciding which tenders to target. If you're a KZN-based firm bidding against a company with zero KZN award history, that context changes your pricing and confidence level.

4. Award Value Trends

A time-series view of contract values over rolling periods (12 months, 3 years, all-time). This reveals whether a company's government revenue is growing, shrinking, or clustered around specific procurement cycles.

Companies that understand their competitor's contract cadence can anticipate when incumbents are likely to face re-tender situations — and position accordingly.

5. Issuing Authority Relationships

Which government departments, municipalities, and state-owned enterprises appear most frequently as the awarding entity. This highlights established supplier relationships and can reveal where entry barriers may be higher (incumbent advantage) or lower (new procurement officer, new IDMS period).

The Leaderboard: Province and Sector Rankings

The Tender Leaderboards feature surfaces the top award recipients for any combination of province and category. It answers the question: who dominates government procurement in my space?

The leaderboard is fully filterable and updates as new OCDS award records are ingested. It's particularly useful for:

Market entry decisions (is this sector consolidated or fragmented?)
Partnership targeting (who are the established players worth approaching for JVs?)
Competitive benchmarking (how does our award count compare to market leaders?)

The Value Estimator: Historical Pricing Intelligence

Separate from but closely related to company intelligence, the Tender Value Estimator uses the awards database to generate pricing intelligence for specific tender types:

Median, minimum, and maximum historical award values by category and province
Distribution of contract sizes (useful for spotting whether small businesses can compete or if awards are dominated by large contracts)
Trend direction (are contracts in this sector getting larger or smaller?)

This is the feature that directly addresses one of the most common failure modes in tender bidding: pricing too high and losing, or pricing too low and winning unprofitably.

The Readiness Assessment: Turning Intelligence Into Action

The intelligence reports become most valuable when combined with the Readiness Assessment tool. After reviewing a competitor's profile, a company can run its own compliance check to understand:

Which specific requirements they meet for tenders in that category
Which documentation gaps need to be addressed before bidding
A personalized action plan prioritized by impact

The AI deep scan checks for non-obvious disqualifiers — things like CIDB grade mismatches, expired CSD registration windows, and B-BBEE level thresholds that are often buried in tender specifications.

How the AI Layer Interprets the Data

Raw award records tell you what happened. The AI reasoning layer tells you what it means.

When a user opens a company report, the platform runs an LLM-assisted analysis that produces natural language commentary on the patterns in the data:

"This company has won 14 contracts with the City of Johannesburg since 2022, concentrated in facilities management. Their contract values have increased year-on-year, suggesting a deepening supplier relationship. No recorded awards in KwaZulu-Natal — likely not a direct competitor for your KZN bid."

This interpretation layer is the same reasoning engine described in the original matching engine article, now applied in the opposite direction: instead of finding tenders for companies, it finds meaning in company data for bidders.

Who Uses Company Intelligence

Three distinct user groups have emerged:

SMEs preparing to bid use it to understand the competitive landscape before committing resources to a complex application. Knowing you're competing against a company with a decade of awards from the same municipality calibrates expectations and helps decide whether to bid at all.

Business development teams at larger firms use it for partnership targeting — identifying companies with complementary geographic and sector footprints for joint venture proposals.

Procurement consultants and advisors use it to benchmark client performance against market peers and identify sectors where their clients have an underexploited advantage.

Accessing the Hub

The Company Intelligence Hub is available at tenders-sa.org/tools/company-intelligence. Basic company searches are available on all plans including the free trial. Full historical reports, value trend analysis, and the leaderboard with advanced filters are included in Professional and Enterprise tiers.

The Tender Leaderboards are available publicly at tenders-sa.org/tools/company-intelligence/leaderboard — no account required.

What's Coming Next

The team is working on two additions to the intelligence layer:

Predictive re-tender alerts — notifying companies when a contract is approaching its typical award cycle end date, based on historical contract durations in the awards data.

Joint Venture compatibility scoring — analyzing two companies' award histories to calculate how complementary they are for a specific tender category, accounting for combined CIDB grade, geographic spread, and sector overlap.

Both are expected to roll out to Professional and Enterprise users in Q2 2026.

*The full Tenders-SA engineering series covers

The Tender Matching engine,
Publisher Ecosystem,
Company Tender intelligence platform.

more articles on tenders sa at tenders-sa.org/blog.*

Learn How AI Powered Tender Matching Works

How Tenders-SA Is Turning Procurement Data Into a Publisher Superpower

mobius-crypt — Tue, 24 Feb 2026 06:14:05 +0000

— what's new, what's live, and why it matters for every South African content

Tenders SA is a South African AI Based Tender Matching & Application Assistant Platform

The Problem Nobody Talks About

There are hundreds of South African portals — news sites, industry blogs, municipal websites, procurement newsletters — that cover government spending. Yet almost all of them link out to dated PDFs or static pages that go stale within days.

The procurement data exists. Making it live, filterable, and embeddable is the hard part. That's exactly what the new Tenders-SA Publisher Ecosystem solves.

What the Publisher Program Actually Is

When we built the core matching engine (covered in the previous article), we noticed something: most of the traffic finding tenders wasn't coming from companies searching — it was landing from third-party content sites.

That insight led to a formal publisher program. The goal: let any South African website embed live, accurate procurement data for free, while Tenders-SA handles data freshness, compliance, and uptime.

The program currently has 850 verified publishers and serves over 1.2 million monthly impressions from embedded widgets.

The Widget Suite: Three Embeds That Do the Heavy Lifting

1. Winners Feed Widget

The most requested feature from publishers. It renders a live, auto-refreshing table of recent tender award announcements — company name, value, province, and sector — all pulled directly from the OCDS-integrated awards database (28,000+ records and growing).

Publishers on procurement-adjacent sites embed this in sidebars or below articles to give readers a real-time pulse on who is winning government contracts. The data refreshes automatically. No cron jobs. No API keys for basic use.

<!-- Drop this anywhere in your HTML -->
<script src="https://cdn.tenders-sa.org/widgets/v1/winners-feed.js"
        data-province="gauteng"
        data-limit="10"
        data-theme="light">
</script>

Parameters supported: province, category, limit, theme (light/dark/auto), and lang (English by default, Zulu and Afrikaans in beta).

2. Sector Trends Widget

A chart widget that visualizes award activity by industry sector over a rolling 90-day window. Built for editors who write market analysis — embed it alongside a construction sector roundup and it pulls actual contract values, not estimates.

Under the hood, this widget hits a cached analytics endpoint that aggregates award data server-side so the client payload stays under 8 KB even with full historical context.

3. Top Companies Widget

Surfaces the top 10 award recipients for a given province or category. This is particularly popular with regional news sites covering economic development — readers can see which local firms are capturing the most government spending without leaving the article.

RSS Feeds: The CMS-Agnostic Route

Not every publisher wants JavaScript embeds. For WordPress, Ghost, or any RSS-capable CMS, Tenders-SA exposes a structured feed network:

All active tenders: https://www.tenders-sa.org/rss/tenders/all
By province: /rss/tenders/province/gauteng (all nine provinces available)
By category: /rss/tenders/category/construction

Each feed item includes the tender title, issuing authority, closing date, estimated value where disclosed, and a direct link to the full listing. They are updated continuously as new tenders are ingested — not once a day at midnight.

For publishers running editorial newsletters, the feed can be piped directly into Mailchimp, Beehiiv, or any email platform that accepts RSS sources.

The SDK for Developers

Publishers with development capacity get access to a lightweight JavaScript SDK that goes beyond static widgets:
for more information see our publishers github repository
tenders-sa-publishers

The github repo is a complete resource for everything tenders sa publishers may need to embed tenders & tender awards data directly into their website , blog, and cms.

Partner Analytics Dashboard

Verified publishers get access to a lightweight analytics dashboard showing:

Widget impression counts
Click-through rates to tender listings
Top-performing widget configurations
Geographic breakdown of reader interest

This helps content teams understand which procurement sectors their audience actually cares about — which in turn improves editorial decisions about what to cover.

Why This Is Different From a Standard API

Most government data APIs are pull-only: you query, you get data, you build everything yourself. The Tenders-SA publisher toolkit is push-first: widgets self-update, feeds push new entries as they arrive, and the SDK abstracts all the complexity of the OCDS data schema.

For a civic tech blog or a regional chamber of commerce website, the difference between "requires a developer" and "paste one script tag" is often the difference between shipping and not shipping.

Getting Started

Publishers can get their embed code at tenders-sa.org/publishers. Verification is fast — the program is open to any South African media outlet, municipal communications team, industry association, or blog.

The developer documentation and SDK reference live at tenders-sa.org/publishers/developers.

Zero cost. POPIA compliant. No data sharing of reader information.

Next in this series: Company Tender Intelligence Reports — how Tenders-SA turns 28,000+ award records into actionable competitive intelligence for bidding companies.

Learn How AI Powered Tender Matching Works

Embed Live South African Tender Data on Any Site — Free Widgets & JS SDK

mobius-crypt — Sat, 21 Feb 2026 02:41:21 +0000

You've probably embedded a GitHub stats card, a Wakatime badge, or a live crypto ticker on a personal project at some point. The idea is simple: pull live external data into your UI without owning the backend. Good DX, zero maintenance, real value.

Tenders SA just shipped exactly that — but for South African government procurement data. Four embeddable widgets, a JavaScript SDK, iFrame support, no API key, no account, no rate limits on the embed layer. Free forever.

Here's what's available, how to drop it in, and why it's actually interesting from a data-and-web perspective.

What Data Are We Talking About?

Tenders SA aggregates live tender data from South African government entities, municipalities, state-owned enterprises, and public procurement portals across all nine provinces. The platform normalises this into structured intelligence: active tenders, awarded contracts, sector breakdowns, company leaderboards, and provincial heatmaps.

The widgets expose a read-only slice of that data as embeddable UI components. Data refreshes every hour automatically.

The Four Widgets

Widget	Best For	Data Shown
Live Heatmap	Portals, dashboards	Tender density by province, real-time
Award Winners Feed	News sites, feeds	Scrolling recent contract award announcements
Top Companies Leaderboard	Market intelligence tools	Company rankings by sector award volume
Sector Trends	Data journalism, analytics	Tender volume + value charts by industry

All four are filterable by province (all 9 SA provinces supported) and sector (construction, ICT, professional services, electrical, civil engineering, and more).

Drop-In: iFrame Embed

The fastest possible integration. One tag, done.

<iframe
  src="https://tenders-sa.org/embed/heatmap"
  width="100%"
  height="400"
  frameborder="0"
  loading="lazy"
  title="TenderSA Intelligence Widget">
</iframe>

You can swap heatmap for winners-feed, leaderboard, or sector-trends depending on which widget you want. Query params handle filtering — e.g.:

<iframe
  src="https://tenders-sa.org/embed/leaderboard?sector=construction&province=gauteng&theme=dark"
  width="100%"
  height="500"
  frameborder="0"
  loading="lazy"
  title="TenderSA Construction Leaderboard — Gauteng">
</iframe>

Supports theme=light (default) and theme=dark. Works in any HTML environment: static sites, CMS embed blocks, email templates with webview links, you name it.

JavaScript SDK Embed

If you need tighter layout control or want to avoid iFrame sizing headaches, use the data-attribute SDK approach instead.

Step 1 — Add the script tag once, before </body>:

<script src="https://tenders-sa.org/tendersa-widget.js" async defer></script>

Step 2 — Place the <div> wherever you want the widget to render:

<div
  data-tendersa-widget
  data-type="heatmap"
  data-province="western-cape"
  data-theme="dark">
</div>

Available data-type values:

heatmap | winners-feed | leaderboard | sector-trends

Available data-province values:

eastern-cape | free-state | gauteng | kwazulu-natal |
limpopo | mpumalanga | northern-cape | north-west | western-cape

You can drop multiple <div> instances on the same page with different configurations — the single script handles all of them.

WordPress Integration

If you're building on WP, paste the JS snippet into your theme's functions.php to enqueue the script:

function tendersa_enqueue_widget() {
    wp_enqueue_script(
        'tendersa-widget',
        'https://tenders-sa.org/tendersa-widget.js',
        [],
        null,
        true // load in footer
    );
}
add_action( 'wp_enqueue_scripts', 'tendersa_enqueue_widget' );

Then in any post, page, or block template:

<div
  data-tendersa-widget
  data-type="sector-trends"
  data-sector="construction"
  data-theme="light">
</div>

Or use the iFrame embed inside a Custom HTML block in the Gutenberg editor — no theme edits required.

Shopify / Liquid

Add the script to your theme.liquid layout file before </body>:

<script src="https://tenders-sa.org/tendersa-widget.js" async defer></script>

Then in any Section or Block .liquid file:

<div
  data-tendersa-widget
  data-type="winners-feed"
  data-province="{{ section.settings.province }}"
  data-theme="{{ section.settings.theme }}">
</div>

You can wire province and theme to Shopify's Section Schema settings to make them editable in the Theme Customizer — no code changes needed per deployment.

React / Next.js

Since the SDK works via DOM data attributes, the cleanest React pattern is to load the script once (e.g. in _document.js or via next/script) and render the div as a standard component:

// components/TenderWidget.jsx
export default function TenderWidget({ type, province, sector, theme = 'light' }) {
  return (
    <div
      data-tendersa-widget
      data-type={type}
      data-province={province}
      data-sector={sector}
      data-theme={theme}
    />
  );
}

// Load script once in _app.js or layout.js
import Script from 'next/script';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://tenders-sa.org/tendersa-widget.js"
        strategy="lazyOnload"
      />
      <Component {...pageProps} />
    </>
  );
}

Then use it anywhere:

<TenderWidget type="leaderboard" sector="ict" province="gauteng" theme="dark" />

RSS Feeds (Bonus)

If widgets are overkill for your use case and you just need a data feed, Tenders SA also publishes RSS feeds — filterable by province and category:

https://tenders-sa.org/rss/tenders/all
https://tenders-sa.org/rss/tenders/province/gauteng
https://tenders-sa.org/rss/tenders/category/construction

Pipe these into your feed reader, n8n workflow, Zapier automation, or any RSS-capable aggregator.

Who Is This Actually Useful For?

South African tech bloggers covering procurement, GovTech, or public sector innovation — add live context to editorial content
Developer portfolio sites — if you work in the SA public sector space, this signals relevant domain knowledge
Industry news portals — construction, ICT, agriculture, engineering publications that want live market data without a data team
Side projects — building a SA business intelligence tool? This is free real-time procurement data to layer into your MVP

No Account. No Key. Just Paste.

There's no OAuth flow, no API key provisioning, no usage dashboard to log into. The widget builder at tenders-sa.org/publishers is a live configurator — pick your options, preview the output, copy the code.

If you need raw API access or more advanced customisation than the embeds allow, the Tenders SA team is contactable for that conversation.

Worth bookmarking if you're building anything in the SA public procurement or GovTech space. The free embed layer removes the usual "I need to scrape and host this myself" overhead entirely.

Built by Custom Logic Pty Ltd — South Africa 🇿🇦

From 8s to 47ms: Optimizing PostgreSQL for a Government Tender Search Platform

mobius-crypt — Sat, 14 Feb 2026 16:23:54 +0000

From 8s to 47ms: Optimizing PostgreSQL for a Government Tender Search Platform

When search takes 8 seconds, users leave. Here's how we made it instant.

Six months ago, our tender search was unusably slow. Users searching for "construction Gauteng" would wait 8+ seconds for results. Our database had only 5,000 tenders. How would we handle 50,000?

The team suggested Elasticsearch. "PostgreSQL can't handle this," they said. "We need a real search engine."

I disagreed. Not because Elasticsearch isn't great—it is. But because I suspected our problem wasn't PostgreSQL's capability. It was our usage of it.

Today, we serve 50,000+ tenders with search response times under 50ms at p95. We did it with PostgreSQL, some smart indexing, and a lot of query optimization.

This is that story.

The Slow Query That Started Everything

Let me show you what we had:

-- ❌ The original, terrible query
SELECT 
  t.*,
  c.name as category_name,
  p.name as province_name,
  org.name as organization_name
FROM tenders t
  LEFT JOIN categories c ON t.category_id = c.id
  LEFT JOIN provinces p ON t.province_id = p.id
  LEFT JOIN organizations org ON t.organization_id = org.id
WHERE 
  t.status = 'ACTIVE'
  AND (
    t.title ILIKE '%construction%' 
    OR t.description ILIKE '%construction%'
  )
  AND (
    p.name ILIKE '%gauteng%' 
    OR org.province ILIKE '%gauteng%'
  )
ORDER BY t.published_at DESC
LIMIT 20;

Query time: 8,247ms for 5,000 rows

What's wrong with this query? Everything.

Let's break down the problems:

Problem 1: ILIKE with Leading Wildcards

WHERE title ILIKE '%construction%'

This can't use indexes. PostgreSQL has to scan every row and do pattern matching. With 5,000 rows, that's 5,000 regex operations.

Problem 2: Multiple OR Conditions

WHERE (title ILIKE '%term%' OR description ILIKE '%term%')
  AND (province ILIKE '%term%' OR org.province ILIKE '%term%')

Even if we could index one condition, the OR forces a full scan anyway. Indexes become useless.

Problem 3: Unnecessary Joins

We're joining three tables (categories, provinces, organizations) just to get names. For display. In a search query.

Problem 4: No Pagination Optimization

ORDER BY published_at DESC LIMIT 20

Sorting all results before taking 20 is expensive. And users rarely go past page 3.

Let's fix these problems systematically.

Optimization 1: Full-Text Search Instead of ILIKE

PostgreSQL has built-in full-text search that's fast and powerful. We just weren't using it.

Adding tsvector Columns

-- Add tsvector columns for full-text search
ALTER TABLE tenders
  ADD COLUMN title_search tsvector
  GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, ''))) STORED;

ALTER TABLE tenders
  ADD COLUMN description_search tsvector
  GENERATED ALWAYS AS (to_tsvector('english', coalesce(description, ''))) STORED;

ALTER TABLE tenders
  ADD COLUMN combined_search tsvector
  GENERATED ALWAYS AS (
    to_tsvector('english', coalesce(title, '')) ||
    to_tsvector('english', coalesce(description, ''))
  ) STORED;

The GENERATED ALWAYS AS ... STORED is key here. PostgreSQL maintains these columns automatically when the source data changes.

Creating GIN Indexes

-- GIN indexes for fast full-text search
CREATE INDEX idx_tenders_title_search 
  ON tenders USING GIN (title_search);

CREATE INDEX idx_tenders_description_search 
  ON tenders USING GIN (description_search);

CREATE INDEX idx_tenders_combined_search 
  ON tenders USING GIN (combined_search);

GIN (Generalized Inverted Index) is perfect for full-text search. It's like having an index on every word.

The New Query

-- ✅ Much better with full-text search
SELECT t.*
FROM tenders t
WHERE 
  t.status = 'ACTIVE'
  AND t.combined_search @@ to_tsquery('english', 'construction')
ORDER BY t.published_at DESC
LIMIT 20;

Query time: 247ms (down from 8,247ms - a 33x improvement!)

But we can do better.

Optimization 2: Composite Indexes

We're filtering by status every time. And we're sorting by published_at. Let's optimize that.

The Composite Index

-- Composite index for status + published_at
CREATE INDEX idx_tenders_status_published 
  ON tenders (status, published_at DESC);

This index serves two purposes:

Filters by status efficiently
Pre-sorts by published_at

PostgreSQL can use this index to skip the sort entirely!

The Impact

EXPLAIN ANALYZE
SELECT t.*
FROM tenders t
WHERE 
  t.status = 'ACTIVE'
  AND t.combined_search @@ to_tsquery('english', 'construction')
ORDER BY t.published_at DESC
LIMIT 20;

-- Index Scan using idx_tenders_status_published
-- Rows Removed by Filter: 234
-- Execution Time: 47ms

Query time: 47ms (down from 247ms - another 5x improvement!)

We're now 175x faster than the original query.

Optimization 3: Denormalization for Joins

Remember those three joins we were doing? Let's eliminate them.

-- Add denormalized columns
ALTER TABLE tenders
  ADD COLUMN category_name TEXT,
  ADD COLUMN province_name TEXT,
  ADD COLUMN organization_name TEXT;

-- Create a trigger to maintain them
CREATE OR REPLACE FUNCTION update_tender_denormalized_fields()
RETURNS TRIGGER AS $$
BEGIN
  SELECT c.name INTO NEW.category_name
  FROM categories c WHERE c.id = NEW.category_id;

  SELECT p.name INTO NEW.province_name
  FROM provinces p WHERE p.id = NEW.province_id;

  SELECT o.name INTO NEW.organization_name
  FROM organizations o WHERE o.id = NEW.organization_id;

  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trigger_update_tender_denormalized
  BEFORE INSERT OR UPDATE ON tenders
  FOR EACH ROW
  EXECUTE FUNCTION update_tender_denormalized_fields();

Now our query needs no joins:

-- ✅ No joins needed!
SELECT 
  t.id,
  t.title,
  t.description,
  t.category_name,
  t.province_name,
  t.organization_name,
  t.published_at,
  t.closing_at,
  t.estimated_value
FROM tenders t
WHERE 
  t.status = 'ACTIVE'
  AND t.combined_search @@ to_tsquery('english', 'construction')
  AND t.province_name = 'Gauteng'
ORDER BY t.published_at DESC
LIMIT 20;

Query time: 23ms (down from 47ms)

We've now achieved 359x improvement from the original.

Optimization 4: Smart Search Query Parsing

User searches aren't always simple. They might search for:

"construction AND Gauteng"
"building OR renovation"
"software -hardware"

Let's handle this properly:

// lib/search/query-parser.ts
export function parseSearchQuery(query: string): string {
  // Handle boolean operators
  let tsQuery = query
    .trim()
    .toLowerCase()
    // Handle AND
    .replace(/\band\b/gi, '&')
    // Handle OR
    .replace(/\bor\b/gi, '|')
    // Handle NOT
    .replace(/\bnot\b/gi, '!')
    .replace(/-(\w+)/g, '!$1')
    // Handle phrases
    .replace(/"([^"]+)"/g, (_, phrase) => {
      return phrase.split(' ').join('<->');
    })
    // Clean up
    .replace(/[^\w\s&|!<>-]/g, '')
    // Join remaining words with &
    .split(/\s+/)
    .filter(Boolean)
    .join(' & ');

  return tsQuery;
}

// Usage
const userQuery = 'construction AND Gauteng -maintenance';
const tsQuery = parseSearchQuery(userQuery); 
// Result: 'construction & gauteng & !maintenance'

const result = await db.$queryRaw`
  SELECT * FROM tenders
  WHERE combined_search @@ to_tsquery('english', ${tsQuery})
`;

This gives users powerful search without needing to know tsquery syntax.

Optimization 5: Partial Indexes for Common Queries

Not all tenders are equal. Active tenders are queried constantly. Closed tenders? Rarely.

-- Partial index for active tenders only
CREATE INDEX idx_tenders_active_search 
  ON tenders USING GIN (combined_search)
  WHERE status = 'ACTIVE';

CREATE INDEX idx_tenders_active_published
  ON tenders (published_at DESC)
  WHERE status = 'ACTIVE';

Partial indexes are smaller and faster because they only index the rows you actually query.

Impact:

Index size: 890MB → 340MB (62% smaller)
Query time: 23ms → 18ms (22% faster)

Optimization 6: Connection Pooling

At scale, connection overhead matters. We use Prisma with PgBouncer:

// lib/db.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = global as unknown as {
  prisma: PrismaClient | undefined;
};

export const db = globalForPrisma.prisma ?? new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL, // Points to PgBouncer
    },
  },
  log: process.env.NODE_ENV === 'development' 
    ? ['query', 'error', 'warn'] 
    : ['error'],
});

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = db;
}

PgBouncer configuration:

[databases]
tendersa = host=localhost port=5432 dbname=tendersa

[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20
reserve_pool_size = 5

Connection pooling gave us:

40% reduction in connection overhead
Ability to handle 10x more concurrent requests
Predictable performance under load

Optimization 7: Query Result Caching

Some queries are requested repeatedly. Let's cache them:

// lib/cache/query-cache.ts
import { redis } from '@/lib/redis';

export async function getCachedQuery<T>(
  key: string,
  queryFn: () => Promise<T>,
  ttl: number = 300 // 5 minutes default
): Promise<T> {
  // Check cache
  const cached = await redis.get(key);
  if (cached) {
    return JSON.parse(cached);
  }

  // Execute query
  const result = await queryFn();

  // Cache result
  await redis.setex(key, ttl, JSON.stringify(result));

  return result;
}

// Usage
export async function searchTenders(query: string) {
  const cacheKey = `search:${hashQuery(query)}`;

  return await getCachedQuery(
    cacheKey,
    async () => {
      return await db.tender.findMany({
        where: {
          status: 'ACTIVE',
          combined_search: {
            search: parseSearchQuery(query),
          },
        },
        take: 20,
        orderBy: { published_at: 'desc' },
      });
    },
    300 // 5 minutes
  );
}

Cache hit rate: 67%

Effective query time: 18ms × (1 - 0.67) = 6ms average

The Complete Architecture

Here's our final search implementation:

// app/api/search/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const searchSchema = z.object({
  query: z.string().min(1).max(200),
  category: z.string().optional(),
  province: z.string().optional(),
  minValue: z.number().optional(),
  maxValue: z.number().optional(),
  page: z.number().min(1).default(1),
  limit: z.number().min(1).max(100).default(20),
});

export async function GET(request: NextRequest) {
  try {
    // Parse and validate
    const params = Object.fromEntries(request.nextUrl.searchParams);
    const validated = searchSchema.parse({
      ...params,
      page: parseInt(params.page || '1'),
      limit: parseInt(params.limit || '20'),
    });

    // Build cache key
    const cacheKey = `search:${JSON.stringify(validated)}`;

    // Get cached or execute
    const results = await getCachedQuery(
      cacheKey,
      async () => {
        const offset = (validated.page - 1) * validated.limit;

        // Parse search query
        const tsQuery = parseSearchQuery(validated.query);

        // Build WHERE conditions
        const where = {
          status: 'ACTIVE',
          combined_search: {
            search: tsQuery,
          },
          ...(validated.category && { category_name: validated.category }),
          ...(validated.province && { province_name: validated.province }),
          ...(validated.minValue && { 
            estimated_value: { gte: validated.minValue } 
          }),
          ...(validated.maxValue && { 
            estimated_value: { lte: validated.maxValue } 
          }),
        };

        // Execute query
        const [tenders, total] = await Promise.all([
          db.tender.findMany({
            where,
            take: validated.limit,
            skip: offset,
            orderBy: { published_at: 'desc' },
            select: {
              id: true,
              title: true,
              description: true,
              category_name: true,
              province_name: true,
              organization_name: true,
              published_at: true,
              closing_at: true,
              estimated_value: true,
            },
          }),
          db.tender.count({ where }),
        ]);

        return {
          tenders,
          pagination: {
            page: validated.page,
            limit: validated.limit,
            total,
            pages: Math.ceil(total / validated.limit),
          },
        };
      },
      300 // 5 minutes TTL
    );

    return NextResponse.json(results);
  } catch (error) {
    console.error('Search error:', error);
    return NextResponse.json(
      { error: 'Search failed' },
      { status: 500 }
    );
  }
}

Performance Testing Results

We ran load tests simulating 1,000 concurrent users:

Before optimization:

Requests: 10,000
Duration: 82 seconds
Success rate: 94% (6% timeout)
Average response: 8,200ms
p50: 7,800ms
p95: 12,400ms
p99: 15,200ms

After optimization:

Requests: 10,000
Duration: 8 seconds
Success rate: 100%
Average response: 6ms (cached) / 21ms (uncached)
p50: 18ms
p95: 47ms
p99: 89ms

Improvement:

10x more throughput
391x faster average response
100% success rate (no timeouts)
262x faster p95

Monitoring and Observability

We track query performance continuously:

// lib/monitoring/query-monitor.ts
import { performance } from 'perf_hooks';

export async function monitorQuery<T>(
  queryName: string,
  queryFn: () => Promise<T>
): Promise<T> {
  const start = performance.now();

  try {
    const result = await queryFn();
    const duration = performance.now() - start;

    // Log slow queries
    if (duration > 100) {
      console.warn(`Slow query: ${queryName} took ${duration}ms`);

      await analytics.track('slow_query', {
        name: queryName,
        duration,
        threshold: 100,
      });
    }

    // Track all queries
    await metrics.histogram('query_duration', duration, {
      query: queryName,
    });

    return result;
  } catch (error) {
    await analytics.track('query_error', {
      name: queryName,
      error: error.message,
    });
    throw error;
  }
}

// Usage
const results = await monitorQuery(
  'search_tenders',
  () => searchTenders(query)
);

Database Maintenance

Fast queries require database health:

-- Weekly maintenance script
-- 1. Update statistics
ANALYZE tenders;

-- 2. Reindex if needed
REINDEX INDEX CONCURRENTLY idx_tenders_combined_search;

-- 3. Vacuum
VACUUM ANALYZE tenders;

-- 4. Check index bloat
SELECT 
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename) - pg_relation_size(schemaname||'.'||tablename)) AS index_size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

Lessons Learned

1. Profile Before Optimizing

Use EXPLAIN ANALYZE:

EXPLAIN (ANALYZE, BUFFERS, VERBOSE)
SELECT * FROM tenders
WHERE combined_search @@ to_tsquery('construction');

This shows you:

Query plan
Actual execution time
Index usage
Buffer hits vs misses

2. Indexes Are Not Free

Every index:

Takes disk space
Slows down writes
Needs maintenance

We started with 23 indexes. After analysis, we removed 8 that were rarely used.

Impact:

340MB disk saved
15% faster inserts
12% faster updates

3. Denormalization Is OK

Normalized databases are beautiful. But joins are expensive.

We denormalized:

Category names
Province names
Organization names

Trade-off:

Slower writes (triggers)
Faster reads (no joins)

For a read-heavy application (99% reads), this was the right choice.

4. Cache Invalidation Is Hard

We cache search results for 5 minutes. But what if a tender closes?

Solution: Event-driven invalidation:

// After tender update
await redis.del(`tender:${tenderId}`);
await redis.del('search:*'); // Invalidate all searches

// Better: Selective invalidation
const affectedKeys = await redis.keys(`search:*${province}*`);
await redis.del(...affectedKeys);

5. Monitor in Production

Load tests are great. Production is different.

We found:

Queries slow down during backup windows
Connection pool exhaustion during traffic spikes
Some query patterns we never tested

Solution: Continuous monitoring with alerts.

When to Actually Use Elasticsearch

PostgreSQL full-text search is great for many cases. But there are limits:

Use Elasticsearch when:

You need typo tolerance
You want relevance tuning
You need faceted search
You're doing complex aggregations
Scale exceeds PostgreSQL capabilities (millions of documents)

Stick with PostgreSQL when:

Your data is relational
You need ACID transactions
Scale is manageable (<1M documents)
Team knows SQL better than Elasticsearch
You want to avoid operational complexity

For us, PostgreSQL + smart optimization was the right choice.

The Results: By the Numbers

Database:

Rows: 5,000 → 50,000 (10x growth)
Index size: 890MB → 340MB (62% smaller)
Query time: 8,247ms → 18ms (458x faster)
Throughput: 12 req/s → 1,250 req/s (104x more)

Infrastructure costs:

Before: $240/month (8x oversized to compensate for slow queries)
After: $45/month (right-sized, efficient queries)
Savings: $2,340/year

User experience:

Search bounce rate: 34% → 3%
Average search depth: 1.2 pages → 3.7 pages
Conversion to bid: 2.1% → 8.4%

Conclusion: PostgreSQL Is Enough (Usually)

We didn't need Elasticsearch. We needed better SQL.

The optimizations:

Full-text search with tsvector
Composite indexes
Denormalization
Query result caching
Connection pooling
Partial indexes
Smart query parsing

Took us from 8s to 18ms at 10x the scale.

Before adding new infrastructure, optimize what you have. You might be surprised.

Want the code? Full implementation examples available in our docs.

Questions? Drop them in the comments!

Follow for more articles on:

Database optimization
PostgreSQL best practices
Full-text search
Performance engineering

Building Tenders SA - South Africa's fastest government tender search platform. 50,000+ tenders, 18ms p95 response time, PostgreSQL.

How We Cut AI Costs by 73% While Improving Quality: Building Cost-Effective LLM Features

mobius-crypt — Sat, 14 Feb 2026 16:10:10 +0000

Our AI proposal generator was hemorrhaging money. In month two of operation, our OpenAI bill hit $3,200 while generating only $1,800 in revenue. Our gross margin was negative 78%.

Something had to change, fast.

Six months later, we're processing 10x the volume at 27% of the original cost per request. Our margins are now healthy (+62%), response quality improved (4.3/5 → 4.6/5), and we've learned some expensive lessons about production AI.

This is the story of how we optimized our AI features without sacrificing quality—and the specific technical strategies you can use to do the same.

The Naive Implementation: When AI Looks Easy

Here's what our original AI proposal generator looked like:

// ❌ The expensive, naive approach
async function generateProposal(request: ProposalRequest): Promise<string> {
  const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

  const completion = await client.chat.completions.create({
    model: "gpt-4-turbo-preview", // Expensive!
    messages: [
      {
        role: "system",
        content: `You are an expert tender response writer for South African government procurement...
        [3,200 tokens of system prompt]`
      },
      {
        role: "user",
        content: `Tender: ${request.tenderTitle}
        Description: ${request.tenderDescription}
        Company: ${request.companyProfile}
        Requirements: ${request.requirements}
        [Often 2,000+ tokens]`
      }
    ],
    temperature: 0.7,
    max_tokens: 2000, // Expensive!
  });

  return completion.choices[0].message.content;
}

This looks clean and simple. Ship it, right?

The costs (per request):

Input tokens: ~5,200 tokens (system prompt + user input)
Output tokens: ~2,000 tokens (response)
Model: GPT-4 Turbo ($0.01/1K input, $0.03/1K output)
Cost per request: $0.112

We were generating 200-300 proposals per day. Monthly cost at 250 proposals/day:

250 requests/day × 30 days × $0.112 = $840/month

Except that's the average calculation. In reality:

Some users regenerated 3-4 times (multiply by 4)
Some prompts were much longer (2-3x tokens)
Peak usage hours hit rate limits (wasted requests)

Actual monthly cost: $3,200

For a feature that generated $1,800 in premium subscriptions. Oops.

Strategy 1: Aggressive Caching (Saved 40% Immediately)

The first low-hanging fruit: identical requests.

Analysis showed that 37% of our requests were semantically identical or near-identical. Why? Because users would:

Generate proposal for tender X
Regenerate because they didn't like the tone
Generate again with slight wording changes

Each regeneration cost us money, but the tender specification was the same.

Implementation: Content-Addressed Caching

import { createHash } from 'crypto';
import { redis } from '@/lib/redis';

async function generateProposal(request: ProposalRequest): Promise<string> {
  // Generate cache key from request content
  const cacheKey = generateCacheKey(request);

  // Check cache
  const cached = await redis.get(cacheKey);
  if (cached) {
    console.log('Cache hit, saved $0.112');
    return cached;
  }

  // Generate new
  const result = await callOpenAI(request);

  // Cache for 7 days
  await redis.setex(cacheKey, 604800, result);

  return result;
}

function generateCacheKey(request: ProposalRequest): string {
  // Normalize to handle minor variations
  const normalized = {
    tenderTitle: request.tenderTitle.toLowerCase().trim(),
    description: request.tenderDescription.toLowerCase().trim(),
    type: request.documentType,
    // Don't include user-specific data
  };

  const content = JSON.stringify(normalized);
  return `proposal:${createHash('sha256').update(content).digest('hex')}`;
}

Impact:

Cache hit rate: 42% (better than expected!)
Cost reduction: 42% × $0.112 = $0.047 saved per cached request
Monthly savings: ~$530
New monthly cost: $2,670

We were no longer losing money, but still not profitable. We needed more optimization.

Strategy 2: Prompt Compression (Saved 25% More)

Our 3,200-token system prompt was absurdly long. Did we really need all that context?

We analyzed the impact of system prompt length on output quality:

// Testing framework
async function testPromptVariations() {
  const prompts = [
    { name: 'Full (3200 tokens)', content: fullPrompt },
    { name: 'Medium (1200 tokens)', content: mediumPrompt },
    { name: 'Minimal (400 tokens)', content: minimalPrompt },
  ];

  const testCases = loadTestCases(10); // Real tender requests

  for (const prompt of prompts) {
    for (const testCase of testCases) {
      const output = await generate(prompt.content, testCase);
      const quality = await evaluateQuality(output);

      console.log({
        prompt: prompt.name,
        quality: quality.score,
        cost: calculateCost(prompt.content, output),
      });
    }
  }
}

Results:

Full prompt (3,200 tokens): Quality 4.3/5, Cost $0.112
Medium prompt (1,200 tokens): Quality 4.2/5, Cost $0.079
Minimal prompt (400 tokens): Quality 3.8/5, Cost $0.048

The medium prompt offered the best quality-cost tradeoff. We were willing to sacrifice 0.1 quality points for 29% cost reduction.

The Optimized Prompt

// ✅ Compressed but effective
const SYSTEM_PROMPT = `Expert SA govt tender writer. Generate ${documentType}.

Rules:
- SBD/MBD compliant
- Professional tone
- Address requirements explicitly
- 1-2 pages max
- No placeholders

Context: ${industryContext}`;

From 3,200 tokens to 80-120 tokens (depending on document type). 27x compression!

Impact:

Input cost: $0.052 → $0.012 (77% reduction)
Quality: 4.3/5 → 4.2/5 (acceptable trade-off)
Monthly savings: ~$450
New monthly cost: $2,220

We were getting close to profitability, but not there yet.

Strategy 3: Model Routing (Saved Another 35%)

GPT-4 is powerful but expensive. Do we always need it?

We analyzed our requests by complexity:

interface RequestComplexity {
  documentType: 'cover-letter' | 'executive-summary' | 'capability-statement';
  tenderLength: number; // tokens
  requirementsCount: number;
  complexity: 'simple' | 'medium' | 'complex';
}

function assessComplexity(request: ProposalRequest): RequestComplexity {
  const tenderLength = estimateTokens(request.tenderDescription);
  const requirementsCount = request.requirements?.length || 0;

  let complexity: 'simple' | 'medium' | 'complex';

  if (request.documentType === 'cover-letter' && tenderLength < 500) {
    complexity = 'simple';
  } else if (requirementsCount > 10 || tenderLength > 2000) {
    complexity = 'complex';
  } else {
    complexity = 'medium';
  }

  return { documentType: request.documentType, tenderLength, requirementsCount, complexity };
}

Distribution:

Simple: 45% (cover letters, short tenders)
Medium: 40% (standard proposals)
Complex: 15% (detailed technical responses)

We could route simple requests to cheaper models!

The Routing Logic

async function generateProposal(request: ProposalRequest): Promise<string> {
  const complexity = assessComplexity(request);

  let model: string;

  switch (complexity.complexity) {
    case 'simple':
      model = 'gpt-3.5-turbo'; // $0.0015/1K in, $0.002/1K out
      break;
    case 'medium':
      model = 'gpt-4-turbo-preview'; // $0.01/1K in, $0.03/1K out
      break;
    case 'complex':
      model = 'gpt-4-turbo-preview';
      break;
  }

  console.log(`Routing to ${model} for ${complexity.complexity} request`);

  return await callOpenAI(request, model);
}

Cost Comparison:

Simple (GPT-3.5): $0.008 per request
Medium (GPT-4): $0.079 per request
Complex (GPT-4): $0.112 per request

Blended cost:

45% × $0.008 = $0.0036
40% × $0.079 = $0.0316
15% × $0.112 = $0.0168
Average: $0.052 per request

Down from $0.112! That's a 53% reduction with minimal quality impact.

Impact:

Monthly cost: $2,220 → $1,450
Quality: Still 4.2/5 average
Margin: Now profitable!

But we weren't done optimizing.

Strategy 4: Smart Regeneration (Prevent Waste)

Users regenerating proposals 3-4 times was killing our margins. Why were they regenerating?

We added feedback tracking:

interface RegenerationFeedback {
  reason: 'tone' | 'length' | 'content' | 'format' | 'other';
  previousVersion: string;
  userComment?: string;
}

async function regenerateProposal(
  request: ProposalRequest,
  feedback: RegenerationFeedback
): Promise<string> {
  // Don't just regenerate blindly—modify the prompt
  const modifiedRequest = applyFeedback(request, feedback);

  return await generateProposal(modifiedRequest);
}

Regeneration reasons:

Tone (too formal/informal): 38%
Length (too long/short): 27%
Content (missing points): 22%
Format (structure issues): 13%

We could address these without regenerating!

Smart Edits Instead of Regeneration

async function improveProposal(
  original: string,
  feedback: RegenerationFeedback
): Promise<string> {
  // For simple changes, use cheaper edit operations
  if (feedback.reason === 'tone' || feedback.reason === 'length') {
    return await editProposal(original, feedback);
  }

  // Only regenerate for content issues
  return await regenerateProposal(request, feedback);
}

async function editProposal(
  original: string,
  feedback: RegenerationFeedback
): Promise<string> {
  const editPrompt = `Original proposal:\n${original}\n\nModify to: ${feedback.reason}`;

  // Use GPT-3.5 for edits (cheaper)
  const completion = await openai.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: [{ role: 'user', content: editPrompt }],
    max_tokens: 500, // Edits are shorter
  });

  return completion.choices[0].message.content;
}

Impact:

65% of regenerations now use edit mode (much cheaper)
Edit cost: $0.004 vs $0.052 regeneration
Saved regeneration costs: ~$180/month
New monthly cost: $1,270

Now we were solidly profitable.

Strategy 5: Prompt Versioning and A/B Testing

We weren't satisfied with 4.2/5 quality. Could we improve quality without increasing costs?

We implemented prompt versioning with A/B testing:

interface PromptVersion {
  version: string;
  prompt: string;
  modelConfig: {
    temperature: number;
    topP?: number;
    frequencyPenalty?: number;
  };
  activePercentage: number; // For A/B testing
}

const PROMPT_VERSIONS: PromptVersion[] = [
  {
    version: 'v1-baseline',
    prompt: COMPRESSED_PROMPT,
    modelConfig: { temperature: 0.7 },
    activePercentage: 50,
  },
  {
    version: 'v2-structured',
    prompt: STRUCTURED_PROMPT_V2,
    modelConfig: { temperature: 0.6, frequencyPenalty: 0.3 },
    activePercentage: 50,
  },
];

async function generateProposal(request: ProposalRequest): Promise<string> {
  const promptVersion = selectPromptVersion();

  const result = await callOpenAI(request, promptVersion);

  // Track performance
  await trackGeneration({
    version: promptVersion.version,
    requestId: request.id,
    cost: calculateCost(result),
  });

  return result;
}

function selectPromptVersion(): PromptVersion {
  const rand = Math.random() * 100;
  let cumulative = 0;

  for (const version of PROMPT_VERSIONS) {
    cumulative += version.activePercentage;
    if (rand < cumulative) return version;
  }

  return PROMPT_VERSIONS[0];
}

After 2 weeks of A/B testing with 500+ generations:

// Results
{
  'v1-baseline': {
    avgQuality: 4.2,
    avgCost: $0.052,
    userRating: 4.2,
  },
  'v2-structured': {
    avgQuality: 4.6,
    avgCost: $0.054,
    userRating: 4.6,
  }
}

v2 was slightly more expensive (+4%) but significantly better quality (+9.5%). We made it the default.

Impact:

Quality: 4.2/5 → 4.6/5
Cost increase: +4% ($1,270 → $1,320)
Worth it! Better product = more users = more revenue

The Final Architecture

Here's what our production system looks like now:

// ✅ Optimized production implementation
async function generateProposal(request: ProposalRequest): Promise<string> {
  // 1. Cache check
  const cacheKey = generateCacheKey(request);
  const cached = await redis.get(cacheKey);
  if (cached) {
    await analytics.track('cache_hit');
    return cached;
  }

  // 2. Assess complexity
  const complexity = assessComplexity(request);

  // 3. Select model
  const model = routeToModel(complexity);

  // 4. Get prompt version
  const promptVersion = selectPromptVersion();

  // 5. Generate
  const result = await callOpenAI({
    model,
    prompt: promptVersion.prompt,
    request,
    config: promptVersion.modelConfig,
  });

  // 6. Cache
  await redis.setex(cacheKey, 604800, result);

  // 7. Track
  await analytics.track('generation', {
    complexity,
    model,
    promptVersion: promptVersion.version,
    cost: calculateCost(result),
  });

  return result;
}

The Results: By the Numbers

Month 2 (Before Optimization):

Requests: 7,500
Average cost per request: $0.112
Total cost: $3,200
Revenue: $1,800
Margin: -78%

Month 8 (After Optimization):

Requests: 78,000 (10x growth!)
Average cost per request: $0.030
Total cost: $2,340
Revenue: $14,400 (8x growth)
Margin: +84%

Cost Breakdown:

Caching saved: 42%
Prompt compression saved: 27%
Model routing saved: 35%
Smart regeneration saved: 12%
Total reduction: 73%

(Yes, these add up to >100% because they compound)

Key Lessons Learned

1. Cache Everything You Can

Our cache hit rate is 42%. That's 42% of requests costing us literally nothing (Redis is cheap).

Pro tip: Use semantic hashing for cache keys. Minor wording differences shouldn't break cache hits:

function semanticHash(text: string): string {
  // Normalize
  const normalized = text
    .toLowerCase()
    .replace(/\s+/g, ' ')
    .trim();

  // Hash
  return createHash('sha256').update(normalized).digest('hex');
}

2. Test Model Performance Rigorously

Don't assume GPT-4 is always necessary. We found:

GPT-3.5 works great for 45% of requests
GPT-4 only needed for complex tasks
User satisfaction barely changed

Create a test suite:

// tests/ai/model-comparison.test.ts
describe('Model Quality Comparison', () => {
  const testCases = loadRealTenderRequests(50);

  it('should compare GPT-3.5 vs GPT-4 on simple requests', async () => {
    for (const testCase of testCases.filter(isSimple)) {
      const gpt35 = await generate(testCase, 'gpt-3.5-turbo');
      const gpt4 = await generate(testCase, 'gpt-4-turbo');

      const quality35 = await evaluateQuality(gpt35);
      const quality4 = await evaluateQuality(gpt4);

      console.log({
        quality35,
        quality4,
        costDiff: calculateCost(gpt4) - calculateCost(gpt35),
        qualityDiff: quality4 - quality35,
      });
    }
  });
});

3. Prompt Engineering Matters More Than Model Selection

We got bigger wins from better prompts than from better models.

Bad prompt (high cost, mediocre quality):

You are an expert tender response writer with 20 years of experience in South African government procurement. You have deep knowledge of PFMA, MFMA, PPPFA regulations, and all relevant compliance requirements. You understand the nuances of different government departments and their evaluation criteria...
[3,000 more tokens of background]

Good prompt (low cost, high quality):

SA tender expert. Generate ${type}.
Must: SBD format, professional tone, 1-2 pages.
Context: ${industry}

The second prompt is 30x shorter and produces comparable quality.

4. User Feedback > Your Assumptions

We thought users wanted longer, more detailed responses. They actually wanted shorter, more scannable content.

We discovered this by asking—not assuming:

async function collectFeedback(generationId: string) {
  return await showUserSurvey({
    questions: [
      'How would you rate the quality?',
      'Was the length appropriate?',
      'Did it address your needs?',
    ],
  });
}

5. Measure Everything

You can't optimize what you don't measure. We track:

interface GenerationMetrics {
  requestId: string;
  model: string;
  promptVersion: string;
  inputTokens: number;
  outputTokens: number;
  cost: number;
  latency: number;
  cacheHit: boolean;
  complexity: string;
  userRating?: number;
  regenerationCount: number;
}

await analytics.track('generation', metrics);

This data drove every optimization decision.

What's Next: Future Optimizations

We're not done. Here's what we're working on:

1. Fine-Tuned Models

Instead of using general-purpose GPT models, we're fine-tuning on our domain:

// Fine-tuning on our successful generations
const trainingData = await db.generation.findMany({
  where: { userRating: { gte: 4 } },
  select: { input, output },
  take: 10000,
});

const fineTuned = await openai.fineTuning.create({
  model: 'gpt-3.5-turbo',
  training_file: prepareTrainingFile(trainingData),
});

Expected: 20-30% cost reduction with comparable quality.

2. Local Model for Simple Tasks

For the simplest tasks (cover letters for short tenders), we're experimenting with locally-hosted models:

Mistral 7B for simple generation
Zero API costs
Higher latency (acceptable for async jobs)

3. Streaming Responses

Better UX and perceived performance:

async function* streamProposal(request: ProposalRequest) {
  const stream = await openai.chat.completions.create({
    model,
    messages,
    stream: true,
  });

  for await (const chunk of stream) {
    yield chunk.choices[0]?.delta?.content || '';
  }
}

4. Intelligent Pre-fetching

Predict likely regenerations and pre-generate alternatives:

async function generateWithVariations(request: ProposalRequest) {
  const [base, formal, casual] = await Promise.all([
    generate(request, { tone: 'balanced' }),
    generate(request, { tone: 'formal' }),
    generate(request, { tone: 'casual' }),
  ]);

  // Cache all versions
  // User can switch tone without regenerating
}

Tools and Resources

Here are the tools that made optimization possible:

Cost Tracking:

OpenAI usage dashboard (built-in)
Custom analytics with Mixpanel
Real-time cost alerts via Slack

Quality Evaluation:

// Automated quality scoring
import { HumanEval } from '@anthropic-ai/eval';

async function evaluateQuality(output: string): Promise<number> {
  const criteria = [
    'addresses_requirements',
    'professional_tone',
    'appropriate_length',
    'sbd_compliance',
  ];

  const scores = await Promise.all(
    criteria.map(c => HumanEval.score(output, c))
  );

  return scores.reduce((a, b) => a + b) / scores.length;
}

Prompt Management:

Version control in Git
Feature flags for A/B testing
Automated performance tracking

Conclusion: AI Can Be Profitable

When we started, AI features seemed like a necessary loss leader. We'd subsidize them with other revenue and hope to break even eventually.

But with systematic optimization:

73% cost reduction
10x volume growth
+84% margins

AI features can be profitable and high-quality.

The key is treating AI like any other infrastructure: measure, optimize, iterate.

Final cost comparison:

Naive implementation: $0.112/request
Optimized implementation: $0.030/request
73% reduction while improving quality from 4.3/5 to 4.6/5

If you're building AI features and struggling with costs, start with these strategies:

Cache aggressively (42% savings for us)
Compress your prompts (27% savings)
Route to cheaper models when possible (35% savings)
Prevent unnecessary regenerations (12% savings)
A/B test everything (improved quality)

The math works. AI can be profitable.

Questions? Want to share your AI optimization strategies?

Drop them in the comments! I'm always learning better approaches.

Follow for more articles on:

Building cost-effective AI features
Production LLM best practices
Scaling developer tools
South African tech startup journey

Check out our platform: tenders-sa.org

Currently building Tenders SA - South Africa's AI-powered government tender platform. We generate 2,500+ AI proposals monthly at profitable margins.

Building an AI-Powered Tender Tools Suite: Calculators, Planners, and Intelligence

mobius-crypt — Fri, 13 Feb 2026 11:37:19 +0000

How we built 10+ specialized tools for government tender preparation including CIDB grading, B-BBEE calculators, JV analysis, and AI proposal generation

Building an AI-Powered Tender Tools Suite: From Calculators to AI Proposal Generation

After building our professional services platform, we realized businesses needed more than just compliance help—they needed strategic tools to make better bidding decisions.

This is the technical story of how we built a comprehensive toolkit including:

📊 CIDB Grade Calculator
🎯 B-BBEE Points Estimator
📅 Tender Preparation Planner
🤝 Joint Venture Suite with fronting risk detection
🤖 AI Proposal Generator
📈 Tender Value Estimator with historical data analysis
🗺️ Provincial Tender Heatmap

Let's dive into the architecture, algorithms, and lessons learned.

The Philosophy: Tools, Not Black Boxes

We wanted users to understand their calculations, not just trust them. This meant:

interface ToolOutput<T> {
  result: T;
  confidence: number;
  reasoning: string[];
  sources?: string[];
  suggestions?: string[];
}

Every tool returns not just a number, but why that number and how to improve it.

Architecture: Shared Tool Infrastructure

Rather than building each tool from scratch, we created a shared framework:

// lib/tools/base-tool.ts
export abstract class BaseTool<TInput, TOutput> {
  abstract name: string;
  abstract description: string;

  // Validation
  abstract validateInput(input: TInput): ValidationResult;

  // Calculation
  abstract calculate(input: TInput): Promise<TOutput>;

  // Explanation
  abstract explain(input: TInput, output: TOutput): string[];

  // Optional: Save to profile
  async saveToProfile?(userId: string, result: TOutput): Promise<void>;
}

This gave us:

✅ Consistent input validation
✅ Built-in error handling
✅ Automatic explanation generation
✅ Optional profile integration

Tool #1: CIDB Grade Calculator

The Construction Industry Development Board (CIDB) uses financial and project history to determine contractor grades (1-9). Higher grades = bigger contract values.

The Algorithm

// lib/tools/cidb-calculator.ts
interface CidbInput {
  classOfWorks: CidbClass; // e.g., "GB" (General Building)
  bestTurnover: number;
  availableCapital: number;
  largestContract: number;
}

interface CidbOutput {
  grade: number;
  maxContractValue: number;
  nextGrade?: {
    grade: number;
    shortfall: {
      turnover: number;
      capital: number;
      contract: number;
    };
  };
  reason: string;
}

export function calculateCidbGrade(input: CidbInput): CidbOutput {
  const { bestTurnover, availableCapital, largestContract } = input;

  // CIDB uses the LOWEST qualifying metric
  const gradeByTurnover = getGradeFromTurnover(bestTurnover);
  const gradeByCapital = getGradeFromCapital(availableCapital);
  const gradeByContract = getGradeFromContract(largestContract);

  const grade = Math.min(gradeByTurnover, gradeByCapital, gradeByContract);

  // Calculate shortfall for next grade
  const nextGrade = grade < 9 ? grade + 1 : undefined;
  const nextGradeData = nextGrade ? {
    grade: nextGrade,
    shortfall: {
      turnover: Math.max(0, TURNOVER_THRESHOLDS[nextGrade] - bestTurnover),
      capital: Math.max(0, CAPITAL_THRESHOLDS[nextGrade] - availableCapital),
      contract: Math.max(0, CONTRACT_THRESHOLDS[nextGrade] - largestContract),
    },
  } : undefined;

  return {
    grade,
    maxContractValue: MAX_CONTRACT_VALUES[grade],
    nextGrade: nextGradeData,
    reason: explainGrade(grade, gradeByTurnover, gradeByCapital, gradeByContract),
  };
}

The key insight: identify the limiting factor. If turnover qualifies for Grade 7 but capital only qualifies for Grade 5, the contractor gets Grade 5.

Thresholds as Lookup Tables

// CIDB Practice Note 21 thresholds (simplified)
const TURNOVER_THRESHOLDS: Record<number, number> = {
  1: 200_000,
  2: 500_000,
  3: 2_000_000,
  4: 4_000_000,
  5: 6_500_000,
  6: 13_000_000,
  7: 40_000_000,
  8: 130_000_000,
  9: Infinity,
};

const MAX_CONTRACT_VALUES: Record<number, number> = {
  1: 200_000,
  2: 650_000,
  3: 2_000_000,
  4: 4_000_000,
  5: 6_500_000,
  6: 13_000_000,
  7: 40_000_000,
  8: 130_000_000,
  9: Infinity,
};

The UI Component

We built an interactive form with instant feedback:

// components/tools/cidb/GradeForm.tsx
'use client';

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";

export function GradeForm({ onCalculate }: GradeFormProps) {
  const form = useForm<CidbInput>({
    resolver: zodResolver(cidbSchema),
    defaultValues: {
      classOfWorks: "",
      bestTurnover: 0,
      availableCapital: 0,
      largestContract: 0,
    },
  });

  function onSubmit(values: CidbInput) {
    const result = calculateCidbGrade(values);
    onCalculate(result);
  }

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <Select name="classOfWorks">
        <SelectItem value="GB">General Building</SelectItem>
        <SelectItem value="CE">Civil Engineering</SelectItem>
        {/* ... */}
      </Select>

      <Input 
        type="number" 
        placeholder="Best Annual Turnover (R)"
        {...form.register("bestTurnover", { valueAsNumber: true })}
      />

      <Button type="submit">Calculate Grade</Button>
    </form>
  );
}

Result Display with Upgrade Path

The magic is in showing users exactly what they need to reach the next grade:

// components/tools/cidb/GradeResult.tsx
export function GradeResult({ result }: { result: CidbOutput }) {
  return (
    <div>
      <div className="text-center">
        <Badge>Grade {result.grade}</Badge>
        <p>Max Contract Value: {formatCurrency(result.maxContractValue)}</p>
      </div>

      {result.nextGrade && (
        <div className="border-t mt-6 pt-6">
          <h3>Path to Grade {result.nextGrade.grade}</h3>

          {result.nextGrade.shortfall.turnover > 0 && (
            <div className="flex justify-between">
              <span>Additional Turnover Needed:</span>
              <span className="font-bold">
                {formatCurrency(result.nextGrade.shortfall.turnover)}
              </span>
            </div>
          )}

          {/* Show capital and contract shortfalls similarly */}
        </div>
      )}
    </div>
  );
}

Tool #2: B-BBEE Points Calculator

B-BBEE (Broad-Based Black Economic Empowerment) is complex. Companies score points across 5 pillars:

interface BbbeeInput {
  // Ownership (25 points)
  blackOwnership: number;
  blackWomenOwnership: number;

  // Management (19 points)
  blackExecutives: number;
  blackSeniorManagers: number;

  // Skills Development (20 points + 5 bonus)
  skillsSpend: number;
  targetSkillsSpend: number;

  // Enterprise Development (40 points + 4 bonus)
  procurementSpend: number;
  bbbeeCompliantSpend: number;

  // Socio-Economic Development (5 points)
  sedContributions: number;
}

interface BbbeeOutput {
  totalScore: number;
  level: number; // 1-8
  procurementRecognition: number; // e.g., 135% for Level 1
  breakdown: {
    ownership: number;
    management: number;
    skills: number;
    enterprise: number;
    sed: number;
  };
  gaps: {
    element: string;
    current: number;
    target: number;
    impact: string;
  }[];
}

The Calculation Engine

export function calculateBbbee(input: BbbeeInput): BbbeeOutput {
  const scores = {
    ownership: calculateOwnershipScore(input),
    management: calculateManagementScore(input),
    skills: calculateSkillsScore(input),
    enterprise: calculateEnterpriseScore(input),
    sed: calculateSedScore(input),
  };

  const totalScore = Object.values(scores).reduce((sum, s) => sum + s, 0);

  // Determine level (requires 40% on priority elements)
  const level = determineBbbeeLevel(totalScore, scores);

  // Calculate procurement recognition
  const procurementRecognition = RECOGNITION_LEVELS[level];

  // Identify improvement opportunities
  const gaps = identifyGaps(input, scores);

  return {
    totalScore,
    level,
    procurementRecognition,
    breakdown: scores,
    gaps,
  };
}

Gap Analysis: The Secret Sauce

function identifyGaps(
  input: BbbeeInput, 
  scores: BbbeeScores
): Gap[] {
  const gaps: Gap[] = [];

  // Check each element
  if (scores.ownership < OWNERSHIP_TARGET) {
    const shortfall = OWNERSHIP_TARGET - scores.ownership;
    gaps.push({
      element: "Ownership",
      current: scores.ownership,
      target: OWNERSHIP_TARGET,
      impact: `${shortfall} additional points could improve your level`,
    });
  }

  // Priority elements must hit 40% threshold
  const priorityElements = ['ownership', 'skills', 'enterprise'];
  for (const element of priorityElements) {
    const score = scores[element];
    const maxScore = MAX_SCORES[element];
    const threshold = maxScore * 0.4;

    if (score < threshold) {
      gaps.push({
        element: capitalize(element),
        current: score,
        target: threshold,
        impact: "CRITICAL: Priority element not meeting 40% threshold",
      });
    }
  }

  return gaps.sort((a, b) => 
    (b.target - b.current) - (a.target - a.current)
  );
}

Users don't just see their level—they see exactly where to invest for maximum B-BBEE improvement.

Tool #3: Joint Venture Calculator Suite

This was our most complex tool. Joint Ventures (JVs) allow companies to combine for larger tenders, but the B-BBEE and CIDB calculations are intricate.

The Data Model

// lib/store/useJvStore.ts
interface Partner {
  id: string;
  name: string;
  type: 'Lead' | 'Partner';

  // Equity
  equityShare: number; // % ownership

  // B-BBEE
  bbbeeLevel: number;
  bbbeeScore: number;

  // CIDB
  cidbGrade?: number;
  cidbClass?: string;

  // Work allocation
  workShare: number; // % of actual work
  profitShare: number; // % of profit
}

interface JvAnalysis {
  bbbeeResult: {
    consolidatedLevel: number;
    consolidatedScore: number;
    frontingRisk: 'LOW' | 'MEDIUM' | 'HIGH';
    riskReason?: string;
  };

  cidbResult: {
    grade: number;
    reason: string;
  };
}

Consolidated B-BBEE Calculation

export function calculateConsolidatedBbbee(
  partners: Partner[]
): BbbeeResult {
  // Weighted average by equity share
  const totalScore = partners.reduce((sum, p) => {
    return sum + (p.bbbeeScore * (p.equityShare / 100));
  }, 0);

  const consolidatedLevel = scoreToLevel(totalScore);

  // Fronting risk detection
  const frontingRisk = detectFrontingRisk(partners);

  return {
    consolidatedLevel,
    consolidatedScore: totalScore,
    frontingRisk: frontingRisk.level,
    riskReason: frontingRisk.reason,
  };
}

function detectFrontingRisk(partners: Partner[]): FrontingRisk {
  // Red flag: High equity but low work share
  for (const partner of partners) {
    const equityToWorkRatio = partner.equityShare / partner.workShare;

    if (equityToWorkRatio > 1.5) {
      return {
        level: 'HIGH',
        reason: `${partner.name} has ${partner.equityShare}% equity but only ${partner.workShare}% work allocation. This may trigger fronting scrutiny.`,
      };
    }
  }

  // Warning: Profit share doesn't match work share
  for (const partner of partners) {
    const workToProfitRatio = partner.workShare / partner.profitShare;

    if (Math.abs(workToProfitRatio - 1) > 0.3) {
      return {
        level: 'MEDIUM',
        reason: `Work share (${partner.workShare}%) and profit share (${partner.profitShare}%) variance detected for ${partner.name}.`,
      };
    }
  }

  return { level: 'LOW' };
}

CIDB JV Grade Upgrade Logic

CIDB allows JVs to tender one grade higher:

export function calculateJvCidbGrade(partners: Partner[]): CidbResult {
  const leadPartner = partners.find(p => p.type === 'Lead');
  const otherPartners = partners.filter(p => p.type !== 'Lead');

  if (!leadPartner?.cidbGrade) {
    return { grade: 0, reason: "Lead partner CIDB grade required" };
  }

  // Standard upgrade: Two Grade N = Grade N+1
  const allSameGrade = otherPartners.every(
    p => p.cidbGrade === leadPartner.cidbGrade
  );

  if (allSameGrade && partners.length >= 2) {
    return {
      grade: leadPartner.cidbGrade + 1,
      reason: `Upgraded from Grade ${leadPartner.cidbGrade} (two or more partners)`,
    };
  }

  // Alternative: Lead at N, two partners at N-1
  const partnersOneBelowLead = otherPartners.filter(
    p => p.cidbGrade === leadPartner.cidbGrade - 1
  );

  if (partnersOneBelowLead.length >= 2) {
    return {
      grade: leadPartner.cidbGrade + 1,
      reason: `Upgraded from Grade ${leadPartner.cidbGrade} (lead at N, two partners at N-1)`,
    };
  }

  // No upgrade
  return {
    grade: leadPartner.cidbGrade,
    reason: "No upgrade criteria met",
  };
}

State Management with Zustand

We used Zustand for client-side JV state:

// lib/store/useJvStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface JvStore {
  partners: Partner[];
  bbbeeResult: BbbeeResult | null;
  cidbResult: CidbResult | null;

  // Actions
  addPartner: (partner: Partner) => void;
  updatePartner: (id: string, updates: Partial<Partner>) => void;
  removePartner: (id: string) => void;
  runAnalysis: () => void;
}

export const useJvStore = create<JvStore>()(
  persist(
    (set, get) => ({
      partners: [],
      bbbeeResult: null,
      cidbResult: null,

      addPartner: (partner) => 
        set((state) => ({ partners: [...state.partners, partner] })),

      updatePartner: (id, updates) =>
        set((state) => ({
          partners: state.partners.map(p => 
            p.id === id ? { ...p, ...updates } : p
          ),
        })),

      removePartner: (id) =>
        set((state) => ({
          partners: state.partners.filter(p => p.id !== id),
        })),

      runAnalysis: () => {
        const { partners } = get();

        if (partners.length === 0) return;

        const bbbeeResult = calculateConsolidatedBbbee(partners);
        const cidbResult = calculateJvCidbGrade(partners);

        set({ bbbeeResult, cidbResult });
      },
    }),
    { name: 'jv-store' }
  )
);

This persists JV data across sessions, so users can build complex JV structures over time.

Tool #4: AI Proposal Generator

This was our first foray into generative AI for tender documents.

The Architecture

// lib/ai/proposal-generator.ts
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

interface ProposalRequest {
  tenderTitle: string;
  tenderDescription: string;
  companyName: string;
  companyProfile: string;
  documentType: 'cover-letter' | 'executive-summary' | 'capability-statement';
}

export async function generateProposal(
  request: ProposalRequest
): Promise<string> {
  const systemPrompt = getSystemPrompt(request.documentType);
  const userPrompt = buildUserPrompt(request);

  const message = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 2000,
    system: systemPrompt,
    messages: [{
      role: 'user',
      content: userPrompt,
    }],
  });

  return message.content[0].text;
}

The Prompts: Domain-Specific Instructions

function getSystemPrompt(documentType: string): string {
  const prompts = {
    'cover-letter': `You are an expert tender response writer for South African government procurement.

Generate a professional cover letter that:
- Addresses the tender requirements explicitly
- Demonstrates understanding of government procurement regulations (PPPFA, PFMA)
- Highlights B-BBEE compliance
- Uses formal business language
- Includes standard SBD references
- Is exactly 1 page (300-400 words)

Do NOT use placeholder text. Use the company information provided.`,

    'executive-summary': `You are creating an executive summary for a tender response.

The summary must:
- Open with a strong value proposition
- Outline the proposed solution/approach
- Highlight company strengths and differentiators
- Reference relevant experience
- Be 2-3 pages (600-800 words)
- Use bullet points for key advantages
- Maintain professional tone

Focus on BENEFITS, not just features.`,

    'capability-statement': `You are writing a capability statement for a tender.

Include:
- Company overview and history
- Core competencies
- Relevant project experience (3-5 case studies)
- Team qualifications
- Quality assurance processes
- Health and safety commitments
- B-BBEE status and transformation credentials

Length: 3-4 pages (900-1200 words)`,
  };

  return prompts[documentType];
}

Streaming for Better UX

We implemented streaming to show content as it's generated:

// components/tools/template-generator/TemplateTool.tsx
'use client';

import { useState } from 'react';

export function TemplateTool() {
  const [content, setContent] = useState('');
  const [isGenerating, setIsGenerating] = useState(false);

  async function handleGenerate(data: ProposalRequest) {
    setIsGenerating(true);
    setContent('');

    const response = await fetch('/api/tools/generate-proposal', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });

    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader!.read();
      if (done) break;

      const chunk = decoder.decode(value);
      setContent(prev => prev + chunk);
    }

    setIsGenerating(false);
  }

  return (
    <div>
      <ProposalForm onSubmit={handleGenerate} />

      {isGenerating && (
        <div className="flex items-center gap-2">
          <Loader2 className="animate-spin" />
          <span>Generating...</span>
        </div>
      )}

      {content && (
        <div className="prose max-w-none">
          <ReactMarkdown>{content}</ReactMarkdown>
          <Button onClick={() => copyToClipboard(content)}>
            Copy to Clipboard
          </Button>
        </div>
      )}
    </div>
  );
}

Cost Optimization

AI calls can get expensive. We implemented caching:

import { createHash } from 'crypto';
import { redis } from '@/lib/redis';

async function generateProposal(
  request: ProposalRequest
): Promise<string> {
  // Generate cache key from request
  const cacheKey = `proposal:${hashRequest(request)}`;

  // Check cache
  const cached = await redis.get(cacheKey);
  if (cached) {
    return cached;
  }

  // Generate new
  const result = await callAnthropicAPI(request);

  // Cache for 7 days
  await redis.setex(cacheKey, 604800, result);

  return result;
}

function hashRequest(request: ProposalRequest): string {
  const content = JSON.stringify(request);
  return createHash('sha256').update(content).digest('hex');
}

This reduced our AI costs by ~60% for similar tender requests.

Tool #5: Tender Value Estimator

This tool uses historical award data to predict tender values.

The Data Pipeline

We scrape OCDS (Open Contracting Data Standard) feeds:

// scripts/import-ocds-data.ts
interface OcdsRelease {
  id: string;
  tender: {
    title: string;
    description: string;
    value: {
      amount: number;
      currency: string;
    };
  };
  awards?: Array<{
    value: {
      amount: number;
      currency: string;
    };
    date: string;
  }>;
}

async function importOcdsData() {
  const releases = await fetchOcdsReleases();

  for (const release of releases) {
    // Extract and normalize
    const award = release.awards?.[0];
    if (!award) continue;

    await db.historicalAward.create({
      data: {
        ocdsId: release.id,
        title: release.tender.title,
        description: release.tender.description,
        estimatedValue: release.tender.value.amount,
        awardValue: award.value.amount,
        currency: award.value.currency,
        awardDate: new Date(award.date),
        category: classifyTender(release.tender.title),
        province: extractProvince(release.tender.title),
      },
    });
  }
}

The Estimation Algorithm

// lib/tools/value-estimator.ts
interface EstimationInput {
  title: string;
  description: string;
  category: string;
  province: string;
}

interface EstimationOutput {
  estimatedMin: number;
  estimatedMax: number;
  estimatedMedian: number;
  confidenceScore: number;
  sampleSize: number;
  comparables: HistoricalAward[];
}

export async function estimateTenderValue(
  input: EstimationInput
): Promise<EstimationOutput> {
  // Find similar tenders
  const comparables = await findComparables(input);

  if (comparables.length < 3) {
    return {
      estimatedMin: 0,
      estimatedMax: 0,
      estimatedMedian: 0,
      confidenceScore: 0,
      sampleSize: 0,
      comparables: [],
    };
  }

  // Calculate statistics
  const values = comparables.map(c => c.awardValue).sort((a, b) => a - b);

  const estimatedMin = percentile(values, 25);
  const estimatedMedian = percentile(values, 50);
  const estimatedMax = percentile(values, 75);

  // Confidence based on sample size and variance
  const confidenceScore = calculateConfidence(values);

  return {
    estimatedMin,
    estimatedMax,
    estimatedMedian,
    confidenceScore,
    sampleSize: values.length,
    comparables: comparables.slice(0, 10), // Top 10 most similar
  };
}

Similarity Matching with Embeddings

We use OpenAI embeddings for semantic similarity:

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function findComparables(
  input: EstimationInput
): Promise<HistoricalAward[]> {
  // Generate embedding for input
  const inputText = `${input.title} ${input.description}`;
  const inputEmbedding = await generateEmbedding(inputText);

  // Find similar awards using vector similarity
  const results = await db.$queryRaw`
    SELECT *,
      1 - (embedding <=> ${inputEmbedding}::vector) AS similarity
    FROM historical_awards
    WHERE category = ${input.category}
      AND province = ${input.province}
      AND 1 - (embedding <=> ${inputEmbedding}::vector) > 0.7
    ORDER BY similarity DESC
    LIMIT 50
  `;

  return results;
}

async function generateEmbedding(text: string): Promise<number[]> {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: text,
  });

  return response.data[0].embedding;
}

This gives much better results than keyword matching alone.

Tool #6: Provincial Tender Heatmap

Interactive data visualization using Recharts:

// components/analytics/heatmap-dashboard.tsx
'use client';

import { useState, useEffect } from 'react';
import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from 'recharts';

interface ProvinceData {
  province: string;
  tenderCount: number;
  totalValue: number;
}

export function HeatmapDashboard() {
  const [data, setData] = useState<ProvinceData[]>([]);
  const [timeRange, setTimeRange] = useState<'7d' | '30d' | '90d'>('30d');

  useEffect(() => {
    loadHeatmapData(timeRange).then(setData);
  }, [timeRange]);

  return (
    <div className="space-y-6">
      <div className="flex justify-between items-center">
        <h1>Provincial Tender Heatmap</h1>
        <Select value={timeRange} onValueChange={setTimeRange}>
          <SelectItem value="7d">Last 7 Days</SelectItem>
          <SelectItem value="30d">Last 30 Days</SelectItem>
          <SelectItem value="90d">Last 90 Days</SelectItem>
        </Select>
      </div>

      <ResponsiveContainer width="100%" height={400}>
        <BarChart data={data}>
          <XAxis dataKey="province" />
          <YAxis />
          <Tooltip />
          <Bar 
            dataKey="tenderCount" 
            fill="hsl(var(--primary))"
            radius={[8, 8, 0, 0]}
          />
        </BarChart>
      </ResponsiveContainer>

      <ProvinceGrid data={data} />
    </div>
  );
}

Data Aggregation

// lib/analytics/heatmap.ts
export async function loadHeatmapData(
  timeRange: string
): Promise<ProvinceData[]> {
  const days = timeRange === '7d' ? 7 : timeRange === '30d' ? 30 : 90;
  const startDate = new Date();
  startDate.setDate(startDate.getDate() - days);

  const data = await db.tender.groupBy({
    by: ['province'],
    where: {
      publishedAt: { gte: startDate },
      status: 'ACTIVE',
    },
    _count: { id: true },
    _sum: { estimatedValue: true },
  });

  return data.map(d => ({
    province: d.province,
    tenderCount: d._count.id,
    totalValue: d._sum.estimatedValue || 0,
  }));
}

Performance Optimizations

1. Memoization for Expensive Calculations

import { useMemo } from 'react';

function BbbeeCalculator({ input }: { input: BbbeeInput }) {
  const result = useMemo(() => {
    return calculateBbbee(input);
  }, [input]);

  return <BbbeeResult result={result} />;
}

2. Web Workers for Heavy Computations

// lib/workers/calculations.worker.ts
self.addEventListener('message', (e) => {
  const { type, data } = e.data;

  switch (type) {
    case 'CALCULATE_CIDB':
      const result = calculateCidbGrade(data);
      self.postMessage({ type: 'CIDB_RESULT', result });
      break;

    case 'CALCULATE_BBBEE':
      const bbbeeResult = calculateBbbee(data);
      self.postMessage({ type: 'BBBEE_RESULT', result: bbbeeResult });
      break;
  }
});

Usage:

const worker = new Worker('/workers/calculations.worker.js');

worker.postMessage({ type: 'CALCULATE_CIDB', data: input });

worker.addEventListener('message', (e) => {
  if (e.data.type === 'CIDB_RESULT') {
    setResult(e.data.result);
  }
});

3. Database Indexes

model HistoricalAward {
  id          String   @id @default(cuid())
  category    String
  province    String
  awardValue  Float
  awardDate   DateTime
  embedding   Unsupported("vector(1536)")?

  @@index([category, province])
  @@index([awardDate])
}

Testing: Validation Against Real Data

We validated our calculators against real government tenders:

// tests/cidb-calculator.test.ts
import { calculateCidbGrade } from '@/lib/tools/cidb-calculator';

describe('CIDB Calculator', () => {
  it('should calculate Grade 5 for typical mid-size contractor', () => {
    const input = {
      classOfWorks: 'GB',
      bestTurnover: 7_000_000,
      availableCapital: 1_500_000,
      largestContract: 3_000_000,
    };

    const result = calculateCidbGrade(input);

    expect(result.grade).toBe(5);
    expect(result.maxContractValue).toBe(6_500_000);
  });

  it('should identify capital as limiting factor', () => {
    const input = {
      classOfWorks: 'CE',
      bestTurnover: 50_000_000, // Qualifies for Grade 7
      availableCapital: 500_000, // Only qualifies for Grade 2
      largestContract: 10_000_000, // Qualifies for Grade 6
    };

    const result = calculateCidbGrade(input);

    expect(result.grade).toBe(2);
    expect(result.reason).toContain('capital');
  });
});

User Feedback Loop

We added feedback collection to improve accuracy:

export function ToolResult({ result }: { result: ToolOutput }) {
  const [feedback, setFeedback] = useState<'helpful' | 'not-helpful' | null>(null);

  async function submitFeedback(rating: 'helpful' | 'not-helpful') {
    setFeedback(rating);

    await fetch('/api/tools/feedback', {
      method: 'POST',
      body: JSON.stringify({
        toolName: 'cidb-calculator',
        input: result.input,
        output: result.output,
        rating,
      }),
    });
  }

  return (
    <div>
      <ResultDisplay result={result} />

      <div className="mt-4 flex gap-2">
        <Button
          variant={feedback === 'helpful' ? 'default' : 'outline'}
          onClick={() => submitFeedback('helpful')}
        >
          👍 Helpful
        </Button>
        <Button
          variant={feedback === 'not-helpful' ? 'default' : 'outline'}
          onClick={() => submitFeedback('not-helpful')}
        >
          👎 Not Helpful
        </Button>
      </div>
    </div>
  );
}

This feedback helps us refine algorithms and prompts.

Lessons Learned

1. Explain Everything

Users don't just want answers—they want to understand the logic:

// Good: Explains the "why"
{
  grade: 5,
  reason: "Your grade is limited by available capital (R1.5M). Turnover and contract history qualify for Grade 6, but capital only meets Grade 5 threshold (R6.5M required for Grade 6)."
}

// Bad: Just the number
{
  grade: 5
}

2. Progressive Enhancement for Calculators

Start simple, add complexity:

// v1: Basic calculator
function calculateBbbee(ownership: number): number {
  return ownership * 0.25; // Simplified
}

// v2: Add all elements
function calculateBbbee(input: BbbeeInput): BbbeeOutput {
  // Full scorecard calculation
}

// v3: Add gap analysis
function calculateBbbee(input: BbbeeInput): BbbeeOutput {
  const result = calculate(input);
  result.gaps = identifyGaps(input);
  return result;
}

3. Cache Aggressively for AI Tools

const CACHE_DURATION = {
  'proposal-generation': 7 * 24 * 60 * 60, // 7 days
  'value-estimation': 24 * 60 * 60, // 1 day
  'historical-data': 30 * 24 * 60 * 60, // 30 days
};

4. Real-Time Validation > Post-Submit Errors

<Input
  type="number"
  {...register("blackOwnership", {
    validate: (value) => {
      if (value < 0) return "Cannot be negative";
      if (value > 100) return "Cannot exceed 100%";
      return true;
    }
  })}
/>

What's Next?

We're working on:

ML-powered tender matching - Recommend tenders based on company capabilities
Automated compliance checking - Scan uploaded documents for completeness
Real-time collaboration - Multiple team members work on JV analysis together
Mobile apps - Tools on the go
API access - Let accounting firms integrate our calculators

Open Source Plans

We're planning to open source:

✅ CIDB calculation library
✅ B-BBEE calculator component
✅ South African public holiday data (2025-2030)
🔄 JV fronting risk detection algorithm
🔄 Tender classification ML model

Would this be useful for your projects? Let me know!

Conclusion

Building these tools taught us that good tools educate while they calculate. Users shouldn't just get an answer—they should understand the regulations, see where they stand, and learn what to improve.

The South African tender market is worth R500+ billion annually. By providing free, high-quality tools, we're helping businesses make data-driven decisions about which opportunities to pursue.

If you're building similar calculation-heavy applications, I hope this deep dive helps. Questions? Drop them in the comments!

Tech Stack:

Next.js 14 + TypeScript
Zustand for state management
Recharts for data viz
Anthropic Claude for AI generation
OpenAI embeddings for similarity
PostgreSQL + Prisma
Redis for caching

Try the tools: tenders-sa.org/tools

What tools would help your business win more work? Share your ideas below!

Building a Professional Services Platform for Government Tender Compliance

mobius-crypt — Fri, 13 Feb 2026 11:32:39 +0000

Building a Professional Services Platform for Government Tender Compliance

When we set out to build Tenders SA, we knew that matching businesses with government tenders was only half the battle. The real barrier preventing capable companies from accessing billions in procurement opportunities wasn't finding tenders—it was compliance documentation.

This is the story of how we built a full-stack professional services platform that handles B-BBEE registrations, CSD applications, company formations, and CIDB grading—all while maintaining a seamless user experience and reliable payment processing.

The Problem: Compliance is Complicated

In South Africa, bidding on government tenders requires a maze of registrations:

B-BBEE (Broad-Based Black Economic Empowerment) certification
CSD (Central Supplier Database) registration with National Treasury
CIPC company registration
CIDB grading for construction businesses
Tax compliance certificates
Insurance documentation
And more...

Each registration has its own portal, requirements, and quirks. DIY registration typically takes 6-12 weeks and involves multiple submission attempts. We wanted to compress this to 7-10 days with professional handling.

Tech Stack: Why We Chose What We Chose

// Our core stack
const techStack = {
  framework: "Next.js 14 (App Router)",
  language: "TypeScript",
  database: "PostgreSQL + Prisma ORM",
  auth: "Custom JWT + Session management",
  payments: "PayPal REST API",
  storage: "AWS S3 for document uploads",
  deployment: "Vercel",
};

Why Next.js App Router?

The App Router's server components gave us some huge wins:

Server-side data fetching - No loading spinners for service listings
Streaming - Progressive rendering for document-heavy pages
Route handlers - Clean API routes that live alongside components
Type safety - Full TypeScript support from DB to UI

Architecture: Service Request System

The core of our platform is a flexible service request system. Here's the Prisma schema:

model ServiceType {
  id          String   @id @default(cuid())
  name        String
  slug        String   @unique
  description String
  price       Decimal  @db.Decimal(10, 2)
  currency    String   @default("ZAR")
  isActive    Boolean  @default(true)

  requests    ServiceRequest[]

  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model ServiceRequest {
  id              String        @id @default(cuid())
  userId          String
  serviceTypeId   String

  // Flexible JSON storage for form data
  formData        Json

  // Document storage keys
  uploadedFiles   Json?

  // State management
  status          RequestStatus @default(PENDING)
  paymentStatus   PaymentStatus @default(PENDING)

  // PayPal integration
  paypalOrderId   String?       @unique

  // Relationships
  user            User          @relation(fields: [userId], references: [id])
  serviceType     ServiceType   @relation(fields: [serviceTypeId], references: [id])

  createdAt       DateTime      @default(now())
  updatedAt       DateTime      @updatedAt

  @@index([userId])
  @@index([status])
}

enum RequestStatus {
  DRAFT
  PENDING
  PROCESSING
  COMPLETED
  REJECTED
}

enum PaymentStatus {
  PENDING
  PAID
  FAILED
  REFUNDED
}

The key insight here was using JSON fields for form data. Each service has different requirements:

B-BBEE needs turnover figures and ownership percentages
CSD needs CIPC numbers and tax references
Business registration needs director details and company names

Rather than creating separate tables for each service type, we use a polymorphic approach with type-safe validation.

Form Handling: Dynamic, Type-Safe Forms

Each service has its own form component with Zod validation. Here's the B-BBEE registration schema:

// lib/schemas/professional-services.ts
import { z } from "zod";

export const beeRegistrationSchema = z.object({
  companyName: z.string().min(2, "Company name required"),
  registrationNumber: z.string().min(10, "Valid registration number required"),

  // Turnover determines if you need affidavit or certificate
  annualTurnover: z.coerce.number().min(0),

  // Ownership structure
  blackOwnership: z.coerce.number().min(0).max(100),
  blackWomenOwnership: z.coerce.number().min(0).max(100),

  // Supporting documents
  cipcDocumentKey: z.string().min(1, "CIPC document required"),
  financialStatementsKey: z.string().optional(),
});

export type BeeRegistrationInput = z.infer<typeof beeRegistrationSchema>;

The form component uses React Hook Form for optimal UX:

// components/services/forms/BeeRegistrationForm.tsx
'use client';

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

export function BeeRegistrationForm() {
  const form = useForm<BeeRegistrationInput>({
    resolver: zodResolver(beeRegistrationSchema),
    defaultValues: {
      blackOwnership: 0,
      blackWomenOwnership: 0,
    },
  });

  async function onSubmit(data: BeeRegistrationInput) {
    const result = await submitBeeRegistration(data);

    if (result.success) {
      // Redirect to payment
      window.location.href = `/services/bee-registration/review/${result.data.requestId}`;
    }
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        {/* Form fields */}
      </form>
    </Form>
  );
}

File Uploads: S3 with Presigned URLs

Handling documents securely was critical. We use presigned S3 URLs for direct client-to-S3 uploads:

// app/api/v1/upload/route.ts
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3Client = new S3Client({
  region: process.env.AWS_REGION!,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

export async function POST(request: Request) {
  const { filename, contentType } = await request.json();

  const key = `uploads/${Date.now()}-${filename}`;

  const command = new PutObjectCommand({
    Bucket: process.env.AWS_S3_BUCKET!,
    Key: key,
    ContentType: contentType,
  });

  // Generate presigned URL valid for 5 minutes
  const uploadUrl = await getSignedUrl(s3Client, command, {
    expiresIn: 300,
  });

  return Response.json({ uploadUrl, key });
}

This approach:

✅ Keeps file uploads off our server
✅ Provides better upload speeds (direct to S3)
✅ Handles large files gracefully
✅ Maintains security with expiring URLs

Payment Integration: PayPal REST API

Processing payments was tricky. South African businesses needed local payment options but also international flexibility. PayPal's REST API gave us both.

// lib/paypal.ts
interface PayPalOrder {
  id: string;
  status: string;
  purchase_units: Array<{
    amount: {
      currency_code: string;
      value: string;
    };
  }>;
}

export async function createPayPalOrder(
  amount: number,
  currency: string,
  requestId: string
): Promise<PayPalOrder> {
  const accessToken = await getPayPalAccessToken();

  const response = await fetch(`${PAYPAL_API}/v2/checkout/orders`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      intent: "CAPTURE",
      purchase_units: [{
        amount: {
          currency_code: currency,
          value: amount.toFixed(2),
        },
        reference_id: requestId,
      }],
      application_context: {
        brand_name: "Tenders SA",
        landing_page: "NO_PREFERENCE",
        user_action: "PAY_NOW",
        return_url: `${process.env.NEXT_PUBLIC_BASE_URL}/services/payment/success`,
        cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/services/payment/cancel`,
      },
    }),
  });

  return response.json();
}

The payment flow:

Create Order - Generate PayPal order with service request ID
User Redirects - PayPal handles the payment UI
Capture Payment - On return, we capture and verify
Update Status - Mark request as PAID and trigger processing

// app/actions/payment.ts
'use server';

export async function captureServicePayment(token: string) {
  const accessToken = await getPayPalAccessToken();

  // Capture the payment
  const response = await fetch(
    `${PAYPAL_API}/v2/checkout/orders/${token}/capture`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
      },
    }
  );

  const data = await response.json();

  if (data.status === "COMPLETED") {
    // Extract reference_id (our request ID)
    const requestId = data.purchase_units[0].reference_id;

    // Update database
    await db.serviceRequest.update({
      where: { id: requestId },
      data: {
        paymentStatus: "PAID",
        status: "PROCESSING",
        paypalOrderId: token,
      },
    });

    // Trigger notification to our team
    await notifyTeamOfNewRequest(requestId);

    return { success: true };
  }

  return { success: false, message: "Payment failed" };
}

Review Page: Pre-Payment Confirmation

We added a crucial step between form submission and payment—a review page:

// app/services/business-registration/review/[requestId]/page.tsx
export default async function ReviewRegistrationPage({ 
  params 
}: { 
  params: Promise<{ requestId: string }> 
}) {
  const user = await getCurrentUser();
  const { requestId } = await params;

  const request = await db.serviceRequest.findUnique({
    where: { id: requestId },
    include: { serviceType: true },
  });

  // Parse stored form data
  const formData = JSON.parse(request.formData as string);
  const servicePrice = request.serviceType.price.toNumber();

  return (
    <div className="container max-w-3xl py-10">
      <h1>Review Application</h1>

      {/* Display company names, directors, etc */}
      <CompanyDetailsCard data={formData} />
      <DirectorsCard directors={formData.directors} />

      {/* Payment section */}
      <PaymentCard
        requestId={requestId}
        amount={servicePrice}
        currency="ZAR"
      />
    </div>
  );
}

This reduced payment drop-off by 42% because users could verify their details before committing to payment.

Server Actions: The Secret Sauce

Next.js Server Actions made our forms feel instant while maintaining security:

// app/actions/professional-services.ts
'use server';

import { getCurrentUser } from "@/lib/session";
import { db } from "@/lib/db";

export async function submitBusinessRegistration(
  data: BusinessRegistrationInput
) {
  // Server-side auth check
  const user = await getCurrentUser();

  if (!user) {
    return {
      success: false,
      message: "Unauthorized. Please log in.",
    };
  }

  try {
    // Validate data server-side (double validation)
    const validated = businessRegistrationSchema.parse(data);

    // Create service request
    const request = await db.serviceRequest.create({
      data: {
        userId: user.id,
        serviceTypeId: "business-registration-id",
        formData: validated,
        status: "DRAFT",
        paymentStatus: "PENDING",
      },
    });

    return {
      success: true,
      data: { requestId: request.id },
    };
  } catch (error) {
    return {
      success: false,
      message: "Failed to submit application",
      errors: error instanceof z.ZodError ? error.errors : [],
    };
  }
}

Server Actions give us:

✅ No API route boilerplate
✅ Automatic revalidation
✅ Progressive enhancement
✅ Type-safe RPC-like calls

Dashboard: Service Request Management

Users needed visibility into their applications. We built a dashboard with real-time status updates:

// app/dashboard/services/page.tsx
export default async function ServicesPage() {
  const user = await getCurrentUser();

  const requests = await db.serviceRequest.findMany({
    where: { userId: user.id },
    include: { serviceType: true },
    orderBy: { createdAt: 'desc' },
  });

  return (
    <div className="space-y-6">
      <h1>My Service Requests</h1>

      <div className="grid gap-4">
        {requests.map(request => (
          <ServiceRequestCard
            key={request.id}
            request={request}
          />
        ))}
      </div>
    </div>
  );
}

Each request card shows:

Service type and price
Submission date
Current status (with color-coded badges)
Payment status
Action buttons (view details, pay now, download documents)

Lessons Learned

1. JSON Schema Validation is Your Friend

Using Zod for both client and server validation caught so many issues:

// This caught bugs we'd have missed
const schema = z.object({
  directors: z.array(
    z.object({
      idNumber: z.string()
        .length(13, "SA ID must be 13 digits")
        .regex(/^\d+$/, "ID must be numeric"),
    })
  ).min(1, "At least one director required"),
});

2. Type-Safe Form Data with Discriminated Unions

Different services need different forms, but we wanted type safety:

type ServiceFormData = 
  | { type: 'bee'; data: BeeRegistrationInput }
  | { type: 'csd'; data: CsdRegistrationInput }
  | { type: 'cidb'; data: CidbRegistrationInput };

function getFormComponent(serviceType: string) {
  switch (serviceType) {
    case 'bee-registration':
      return BeeRegistrationForm;
    case 'csd-registration':
      return CsdRegistrationForm;
    default:
      return GeneralServiceForm;
  }
}

3. Idempotent Payment Capture is Critical

We learned this the hard way when a user refreshed the payment success page:

export async function captureServicePayment(token: string) {
  // Check if already captured
  const existing = await db.serviceRequest.findUnique({
    where: { paypalOrderId: token },
  });

  if (existing?.paymentStatus === "PAID") {
    return { success: true, message: "Already processed" };
  }

  // Proceed with capture...
}

4. Progressive Enhancement with Server Components

Our forms work without JavaScript! Well, mostly:

export function ServiceForm({ serviceSlug }: { serviceSlug: string }) {
  // This renders on the server
  const FormComponent = getFormComponent(serviceSlug);

  return (
    <Suspense fallback={<FormSkeleton />}>
      <FormComponent />
    </Suspense>
  );
}

Performance Metrics

After 6 months of operation:

Average submission time: 3.2 minutes (down from 45+ minutes DIY)
Payment completion rate: 87% (industry average is 60%)
Processing time: 7-9 days (down from 21+ days DIY)
Error rate: <2% (mostly user-uploaded document issues)
P95 page load: 1.8s

What's Next?

We're working on:

Automatic document generation - Generate MOIs, shareholder agreements, etc.
Smart document validation - AI checks for common errors before submission
Status webhooks - Real-time updates via email/SMS
Bulk services - Handle multiple registrations at once
API access - Let accounting firms integrate our services

Open Source Opportunities

We're considering open-sourcing:

Our Zod schema collection for SA compliance documents
The PayPal integration wrapper (with better TypeScript types)
Document upload component with S3 presigned URLs

Would this be useful to you? Let me know in the comments!

Conclusion

Building this platform taught us that compliance doesn't have to be painful. With the right architecture—type-safe schemas, flexible data models, reliable payments—you can turn a 3-month bureaucratic nightmare into a 10-day professional service.

The South African government procurement market is worth R500+ billion annually. By removing the compliance barrier, we're helping thousands of capable businesses access opportunities they previously couldn't pursue.

If you're building similar document-heavy, payment-processing platforms, I hope this breakdown helps. Feel free to ask questions in the comments!

Tech Stack Summary:

Next.js 14 (App Router)
TypeScript
Prisma + PostgreSQL
React Hook Form + Zod
PayPal REST API
AWS S3
Vercel

GitHub: (Coming soon)
Website: tenders-sa.org

Read Next: Building a Tender Tools Suite with AI-Powered Calculators

Have you built similar compliance or document management platforms? What challenges did you face? Drop a comment below!

How We Moved Our Docs to the Edge (And Stopped Rebuilding for Typos)

mobius-crypt — Tue, 16 Dec 2025 13:03:27 +0000

At Tenders SA, we recently undertook a migration that sounds minor on paper but had a massive impact on our developer experience and site performance: we moved our entire documentation system from local file reads to the Cloudflare Edge.

Here is why we did it, how we architected it using Cloudflare Workers and KV, and the code that makes it work.

The Problem: The "Monolithic" Content Trap

Like many Next.js projects, our documentation started as a folder of JSON files living in our repo (data/docs/*.json).

Our app would read these files at runtime (or build time) using standard file system calls:

// The old way (src/lib/docs/load-documentation.ts)
import fs from 'fs';
import path from 'path';

export function getDoc(slug) {
  // 🚫 This couples content to the build artifact!
  const filePath = path.join(process.cwd(), 'data/docs', `${slug}.json`);
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
}

The issues with this approach:

Rebuilds for Typos: Correcting a spelling mistake in the docs required a full CI/CD pipeline run and redeployment of the main application.
Platform Limitations: As we looked to move certain services to edge runtimes (like Cloudflare Workers), we hit a wall. Edge workers generally cannot read from the local file system.

The Solution: Cloudflare KV + Workers

We decided to decouple the content from the application code.

Storage: Cloudflare KV (Key-Value storage). It is eventually consistent, extremely fast for reads, and perfect for text data like documentation.
Delivery: A lightweight Cloudflare Worker acting as the docs-api.

The Architecture

Instead of fs.readFile, our frontend now fetches data from an API.

Namespace: TENDERS_DOCS
Key Strategy:
- doc:{slug} -> Stores the full content of a specific page.
- docs:tree -> Stores the navigation structure (sidebar categories, order, etc.).

Step 1: The Migration Script (Seeding KV)

We couldn't just drag-and-drop files. We needed a script to transform our local JSON files into a format Cloudflare KV accepts for bulk uploading.

We created scripts/generate-docs-kv-data.ts:

// scripts/generate-docs-kv-data.ts
import fs from 'fs';
import path from 'path';

const DOCS_DIR = path.join(__dirname, '../data/docs');
const OUTPUT_FILE = path.join(__dirname, 'docs_kv_bulk.json');

const generateKVData = () => {
  const files = fs.readdirSync(DOCS_DIR);
  const kvPairs = [];
  const navigationTree = [];

  files.forEach(file => {
    if (!file.endsWith('.json')) return;

    const content = fs.readFileSync(path.join(DOCS_DIR, file), 'utf8');
    const docData = JSON.parse(content);
    const slug = file.replace('.json', '');

    // 1. Prepare the content key
    kvPairs.push({
      key: `doc:${slug}`,
      value: JSON.stringify(docData) // Store as string
    });

    // 2. Build the navigation tree metadata (simplified)
    navigationTree.push({
      title: docData.title,
      slug: slug,
      category: docData.category
    });
  });

  // 3. Add the tree key
  kvPairs.push({
    key: `docs:tree`,
    value: JSON.stringify(navigationTree)
  });

  fs.writeFileSync(OUTPUT_FILE, JSON.stringify(kvPairs, null, 2));
  console.log(`✅ Generated ${kvPairs.length} KV pairs.`);
};

generateKVData();

Once generated, we upload the data via Wrangler:

npx wrangler kv:bulk put --namespace-id <YOUR_KV_ID> scripts/docs_kv_bulk.json

Step 2: The Worker Logic

The Worker is incredibly simple. It sits on the edge, intercepts the request, and queries KV.

// worker.ts
export interface Env {
  TENDERS_DOCS: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    // 1. Handle Navigation Request
    if (url.pathname === '/docs/tree') {
      const tree = await env.TENDERS_DOCS.get('docs:tree', 'json');
      return new Response(JSON.stringify(tree), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    // 2. Handle Individual Pages
    // Pattern: /docs/{slug}
    const match = url.pathname.match(/^\/docs\/(.+)$/);
    if (match) {
      const slug = match[1];
      // Fetch directly from KV
      const doc = await env.TENDERS_DOCS.get(`doc:${slug}`, 'json');

      if (!doc) {
        return new Response('Doc not found', { status: 404 });
      }

      return new Response(JSON.stringify(doc), {
        headers: { 
          'Content-Type': 'application/json',
          'Cache-Control': 'public, max-age=3600' // Cache heavily!
        }
      });
    }

    return new Response('Not found', { status: 404 });
  },
};

Step 3: Decoupling the Frontend

Finally, we refactored our Next.js frontend components. Instead of importing a server-side file reader, we just fetch.

Before (Server Component):

const doc = await loadDocumentationData(slug); // ❌ Reads disk

After (Server Component):

const res = await fetch(`https://docs-api.tenders-sa.org/docs/${slug}`, {
  next: { revalidate: 3600 } 
});
const doc = await res.json(); // ✅ Fetches from Edge

The Benefits

Instant Content Updates: We can now update a specific KV key (via API or dashboard) and the documentation updates instantly without a redeploy.
Performance: Cloudflare KV is distributed globally. Our documentation data is now physically closer to the user than our origin server ever was.
Microservices Ready: Our documentation data is no longer trapped in the Next.js repo. Other services (like our chatbots or CLI tools) can hit the docs-api to retrieve the same standardized content.

Have you moved static content to the Edge? Let me know in the comments!

Tenders SA Documentations

# From Monolith to the Edge: Migrating Tenders SA's Blog to Cloudflare Workers

mobius-crypt — Tue, 16 Dec 2025 10:29:53 +0000

The Context

At Tenders SA, we are in the middle of a significant architectural shift. We are moving from a monolithic Next.js application to a microservices architecture. One of the first candidates for this migration was our blog.

You might ask, "Why move a simple blog?"

Our blog isn't just a list of markdown files. It powers a dynamic recommendation engine that matches tender listings with helpful guides. It calculates "Related Posts" on the fly based on tags and categories, and it serves "Featured" content based on specific SEO scoring rules.

Running this logic inside the Next.js main thread meant our monolithic app was doing heavy lifting it didn't need to do. We decided to move the entire blog backend to Cloudflare Workers and KV Storage.

Here is how we maintained exact feature parity—specifically our custom SEO scoring algorithms—while moving to the Edge.

The Architecture

The plan was straightforward but strict:

Data Source: Move from local JSON/Database to Cloudflare KV (Key-Value storage).
Compute: Replace src/lib/blog.ts (Next.js) with a Cloudflare Worker.
Constraint: We could not lose the dynamic "scoring" logic that helps our SEO.

KV Design

We opted for a flat structure in KV to ensure speed.

post:{slug}: Contains the full JSON content of a post.
list:all: A lightweight JSON array of all post metadata. This is what we iterate over for filtering and scoring.
categories: A pre-calculated array of category counts.

Porting the Logic: The "Scoring" Challenge

The most critical part of this migration was porting our internal matching algorithms. We didn't just want to serve files; we wanted to serve the right files.

1. The "Featured Posts" Algorithm

On our homepage, we don't just show the latest posts. We score them based on high-value keywords that convert users. We ported this logic directly into the Worker.

Here is the scoring logic we implemented in the GET /posts/featured endpoint:

// Inside our Cloudflare Worker
function scorePostForFeature(post) {
  let score = 0;
  const now = new Date();
  const postDate = new Date(post.date);

  // 1. Keyword Scoring (High Value)
  const title = post.title.toLowerCase();
  const excerpt = post.excerpt.toLowerCase();

  // "How-to" content is evergreen and high value
  if (["guide", "how to", "tips", "winning", "successful"].some(w => title.includes(w))) {
    score += 10;
  }

  // Domain specific keywords
  if (["tender", "procurement", "contract", "proposal"].some(w => title.includes(w) || excerpt.includes(w))) {
    score += 8;
  }

  // 2. Recency Boost
  // If published in the last 30 days, give it a bump
  const diffTime = Math.abs(now - postDate);
  const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24)); 
  if (diffDays < 30) {
    score += 5;
  }

  return score;
}

By running this on the Edge, we can adjust these weights instantly without redeploying the main frontend application.

2. Contextual Matching (Tender to Blog)

When a user is looking at a specific construction tender, we want to show them guides on "How to price construction bills."

We created a POST /posts/related-to-tender endpoint. It accepts the tender's categories and runs a similar scoring match against our list:all KV entry:

+10 pts for direct Category match.
+8 pts for Title keyword match.
+5 pts for Recency.

This allows the frontend to simply send { categories: ["construction"] } and receive a perfectly curated list of reading material.

The API Surface

We exposed a clean REST API from the Worker that our Next.js frontend now consumes:

GET /posts: The main list with pagination.
GET /posts/{slug}: The full content + SEO Metadata (Canonical, Title, Desc).
GET /posts/{slug}/related: Finds related content based on shared tags (+5pts per tag).
GET /categories: Returns categories with active post counts.

Why This Matters (RAG Readiness)

Beyond just speed, this structure prepares us for the next phase: AI.

By structuring our content in KV (post:{slug}), we have created a high-speed retrieval layer. When we implement our "Tender Assistant" chatbot later this year, this Worker will serve as the primary knowledge source for the RAG (Retrieval-Augmented Generation) pipeline. The Worker can quickly feed context to the LLM without touching a database or scraping a website.

Conclusion

Moving to Cloudflare Workers reduced our Next.js bundle size and offloaded complex iteration logic to the edge network. We kept our complex SEO scoring, improved response times, and prepared our data infrastructure for AI features.

If you are running a blog inside a Next.js monolith, consider breaking it out. The Edge is ready for it.

Next Steps for Tenders SA

[ ] Finalize the scripts/seed-blog-to-kv.ts migration script.
[ ] Switch the production DNS to route /api/blog/* to the new Worker.

Check out the platform at tenders-sa.org
Check out our Blog tenders-sa.org Blog

How We Built a "No-Recalc" Tender Matching Engine with Actionable Feedback

mobius-crypt — Fri, 12 Dec 2025 11:43:46 +0000

Government tender data in South Africa is notoriously messy. But the real challenge isn't just finding the data—it's matching it to businesses in a way that is accurate, performant, and, most importantly, explainable.

At Tenders SA, we moved away from opaque AI "black boxes" to build a transparent, feedback-driven matching engine - Which uses both AI and Matching Algos.

We wanted to answer two questions for our users: "Is this a good match?" and "If not, what can I do to fix it?"

Here is a deep dive into the architecture of our Tender Recommendation and Feedback Services, built with TypeScript and Prisma.

The Core Design Pattern: "Database as Cache"

One of the biggest performance killers in matching algorithms is calculating scores on the fly.

If you have 1,000 active tenders and 5,000 companies, running a complex scoring function ($1,000 \times 5,000$) every time a user loads their dashboard is unscalable.

We solved this with a strict architectural principle: The MatchingScore table is the cache.

Our TenderRecommendationService explicitly never recalculates scores on read. Instead, it queries a pre-computed MatchingScore table. This allows us to perform high-speed filtering and sorting using standard SQL queries via Prisma.

Here is how we fetch recommendations without killing the CPU:

// src/app/lib/services/tender-recommendation.service.ts

export class TenderRecommendationService {
    /**
     * READS from MatchingScore table - NEVER recalculates
     * Applies user preference filters on top of stored scores
     */
    async getRecommendationsForUser(
        userId: string,
        options: GetRecommendationsOptions = {}
    ): Promise<RecommendedTender[]> {
        // ... (setup code)

        // 1. Efficient Filtering directly in the DB query
        const whereClause: any = {
            companyId: company.id,
            score: { gte: minScore }, // Filter by pre-calculated score
            tender: {
                status: 'ACTIVE',
                closingDate: { gte: new Date() },
            },
        };

        // 2. Fetch matches with joined tender details
        const matchingScores = await db.matchingScore.findMany({
            where: whereClause,
            include: {
                tender: {
                    select: { id: true, title: true, status: true, /*...*/ },
                },
            },
            orderBy: { score: 'desc' }, // Instant sorting
            skip: offset,
            take: limit,
        });

        // 3. Map to DTOs (Data Transfer Objects)
        return matchingScores.map(ms => ({
            id: ms.id,
            score: ms.score,
            factors: parseFactors(ms.factors), // The "why" is stored as JSON
            matchCategory: getMatchCategory(ms.score),
            // ...
        }));
    }
}

This approach allows us to serve thousands of concurrent requests with sub-millisecond latency, as the heavy lifting is done asynchronously by background workers that populate the MatchingScore table.

The Feedback Loop: Making Scores Actionable

A score of "45%" is useless if the user doesn't know why. We built a MatchingFeedbackService to decompose these scores into actionable advice.

We defined specific weights for different scoring factors:

// src/app/lib/services/matching-feedback.service.ts

const FACTOR_WEIGHTS: Record<string, number> = {
    industry_match: 0.15,
    bbbee_compliance: 0.15,
    geographic_match: 0.10,
    document_readiness: 0.10,
    technical_capability: 0.15,
    financial_capability: 0.15,
    // ...
};

Using these weights, we generate dynamic Improvement Areas. If a user fails a specific check (like BBBEE compliance), we don't just lower their score—we tell them exactly how to fix it.

Here is the logic that generates those specific recommendations:

// src/app/lib/services/matching-feedback.service.ts

private static generateFactorRecommendation(
    factor: string,
    score: number,
    company: any
): { recommendation: string; actionable: boolean; } | null {
    switch (factor) {
        case 'bbbee_compliance':
            const currentLevel = company?.bbbeeLevel || 'Not specified';
            if (score < 50) {
                return {
                    recommendation: `Your BBBEE Level ${currentLevel} may not meet requirements. Consider upgrading to Level 1-4 to qualify for more tenders.`,
                    actionable: true
                };
            }
            return {
                recommendation: 'Maintain your BBBEE certification and consider improving to a higher level',
                actionable: true
            };

        case 'financial_capability':
            const turnover = company?.annualTurnover || 0;
            if (turnover < 1000000) {
                return {
                    recommendation: 'Update your annual turnover in your profile. Many tenders require minimum turnover thresholds.',
                    actionable: true
                };
            }
            // ...
    }
}

Calculating the "Match Explanation"

We aggregate these insights into a MatchExplanation object. This creates a transparent "Report Card" for every tender.

The service analyzes the gaps and even estimates the "Time to Qualify":

// src/app/lib/services/tender-recommendation.service.ts

// Estimate time to qualify based on gaps
let estimatedTimeToQualify: string | null = null;
if (gaps.length === 0) {
    estimatedTimeToQualify = 'Ready to apply';
} else if (gaps.length <= 2) {
    estimatedTimeToQualify = '1-3 days (with document uploads)';
} else {
    estimatedTimeToQualify = '1-2 weeks (significant updates needed)';
}

This is a game-changer for user experience. Instead of guessing if they can bid, users instantly know if they are "Ready to apply" or if they need "1-2 weeks" to prepare their compliance documents.

Categorization Logic

To make the UI scannable, we bucket matches into clear categories. We use a threshold-based approach:

Highly Qualified: Score ≥ 85
Good Match: Score ≥ 70
Potential: Score < 70

This simple logic powers our dashboard filters, allowing users to focus only on the opportunities they are statistically most likely to win.

Try Our Matching Engine

We are building in public and constantly refining our scoring weights and feedback algorithms.

See Our Launch Press Release: Launching Tenders SA - AI Base Tender Matching **Tenders SA Launch 2025
See it in action: Create a profile and see your personalized match scores at tenders-sa.org.

We'd love to hear your feedback on how we handle data modeling and scoring efficiency!