# ABIL: A Startup Studio Case Study, and a Note to Future Students

This is a case study for the Startup Studio Library. It explains what ABIL is, how it was built, and the few decisions worth borrowing. If you are a future student reading this: go through it once before you start your own build, and again when you get stuck.

## What ABIL is, in one breath

**Environmental Site Intelligence.** Companies report their environmental impact once a year, on a slide. Regulators, insurers and lenders now check the same physical sites all year long, from orbit. ABIL closes that gap. It turns open satellite data into a defensible, cited environmental score for every site a company owns, and it gives you an AI analyst you can simply ask, one that answers only from the measurements and writes the report a regulator can accept.

The unit of value is the asset, not the map. Everything in the product answers one question: "What is true at this site, with a number I can cite, a source, a date and a confidence?"

Live: landing `clearesg.vercel.app`, app `frontend-blush-gamma-69.vercel.app`, API `abil-backend.onrender.com`.

## What was actually built

A real system that works from end to end, not a clickable mock:

- **An Earth observation pipeline** that computes environmental indicators (NDVI, land surface temperature anomaly, land cover, proximity to water and to protected areas, flood exposure and more) over an area of interest drawn around each site, with every result carrying its provenance and confidence.
- **A scoring engine with four axes**: Impact, Physical exposure, Nature sensitivity and Observed change, combined into one Environmental Site Score that you can always break back down. Never an opaque number.
- **A grounded AI analyst** (Gemini with tools and RAG) that cannot invent figures, labels every claim as observation, inference or recommendation, and cites the source, the date and the confidence.
- **Reports you can verify** (PDF and HTML) with a chain of custody manifest and a hash you can check again later.
- **The full commercial spine**, added in one focused week of work: real authentication (Firebase with RBAC), product telemetry (Firestore), a CRM link (HubSpot), transactional email (Resend) and payments (Stripe Checkout, Customer Portal and webhooks). All of it behind clean seams, all of it with an offline default.

For the full technical tour, see [`ARCHITECTURE_TOUR.md`](./ARCHITECTURE_TOUR.md). For the honest buyer's view, see [`CUSTOMER_POV.md`](./CUSTOMER_POV.md). For the demo day script, see [`SALES_PITCH.md`](./SALES_PITCH.md).

## Five decisions worth borrowing

1. **Build seams, not forks.** Every external dependency (the satellite engine, auth, the model, payments, the CRM) sits behind a small interface that you pick with a single setting, and every seam has a deterministic offline default. The payoff is large. The same codebase is a free local demo that needs no credentials, and also a credentialed production service. Your tests never touch the network. You can demo on a plane. You can swap Stripe for another processor by editing one file.

2. **Make the demo deterministic.** The synthetic satellite provider is seeded by location, metric and period, so the demo portfolio looks real and never shifts under you. A demo that flickers is a demo that fails on stage. Precompute it, freeze it, and seed it the same way every time.

3. **Sell evidence, not assertions, and never certification.** Every number carries a source, a date and a confidence. The model is not allowed to invent figures. Reports can be checked by hash. And everywhere, the product says it supports compliance, it does not certify it. That honesty is the right position and the legally safe one, and customers trust it more, not less.

4. **Ground the model or do not ship it.** A model that makes up an environmental number is a liability, not a feature. The analyst only speaks through tools that read real computed results, labels observation against inference against recommendation, and shows its uncertainty. That discipline is what turns a chatbot into an analyst.

5. **Cheap by construction.** Open data, serverless compute, a map with no paid token, a precomputed demo. The marginal cost of one more site is close to zero, so the unit economics work before you raise a round.

## The hard problems, and how they were solved

These are the real ones, the kind you will hit too.

- **"Stripe does not work."** It did. The backend created real Checkout sessions, and the hosted page showed the right product and price. The failure was in the experience, not in Stripe. The Subscribe button was disabled when signed out, a silent dead end, and the footer literally said "no charge until Stripe keys are configured," which was both false and alarming. The lesson: when a user says something is broken, reproduce their exact path before you touch the code, because the bug is often two layers away from where they point.

- **A config string of thirty characters that returned 401 across all of production.** On Linux, calling `Path(raw).exists()` on a long inline JSON service account string raises `ENAMETOOLONG`, and `Path.exists()` does not swallow that error, so auth failed only inside the container and never on a laptop. The lesson: "works on my machine" failures hide in edge cases at the operating system level, so reproduce in the environment you actually deploy to.

- **The landing analyst sometimes said "I cannot find your assets."** Two causes, both useful. The first was a cold start: the Render free tier sleeps, so the first tool call that reached the database failed. We fixed it by warming the connection pool when the page loads. The second was a poor suggested question: "which of the three quarries" pushed the agent to filter by an asset type that does not exist. The lesson: with agentic tools, the prompts you ship are part of your reliability budget, so test the exact wording you put in front of users.

- **Cloud firewalls dislike default user agents.** Resend, sitting behind Cloudflare, returned error 1010 until the request sent a User Agent header that looked like a real browser. The lesson: integration failures are often boring transport details, not your own logic.

## The honest state

ABIL is a genuinely working product with one limitation that only shows up beyond the demo: multitenancy. Every signed in user currently maps to the same demo company, which is perfect for showing the product and blocking for real self service. The move with the most leverage from here is to provision a real company per organisation and add a "score my own site" onboarding moment. Knowing what you deliberately left for later, and being able to say so plainly, is itself a skill. (See `CUSTOMER_POV.md`, section 5.)

## If you take three things from this project

1. **Architecture is leverage.** The seam pattern did not just keep the code clean. It made the product easy to demo, easy to test, cheap to run and easy to fund. Good structure is a business advantage, not a tax.
2. **Trust is the product.** In a field with regulatory and financial stakes, cited, uncertain and verifiable beats confident and slick every time. Build the honesty in from the first line.
3. **Ship the boring spine.** Anyone can build the exciting core. The week you spend wiring real auth, payments, telemetry and a CRM, behind seams, with defaults, is the week a project becomes a company.

Build something real. Make it honest. Make it cheap to run. Then go talk to a customer.