ClearClaim

System


The parts, how a request moves between them, the tools we used, the trade-offs we made and how it would grow. Everything here describes the system as it runs today.
ArchitectureWorking diagramsStackData modelTrade-offsScalability
10
system parts
16
database tables
305
engine parity tests
64
backend tests
26
guide articles
0
AI-generated numbers

Architecture

Ten parts, three places.

Some of ClearClaim runs on your device, some on our server, and some with managed services. Pick a journey to watch a request move through it, or click any part for details.

Your device
Edge and our server
Managed services and ledger

Step 1 of 5

You press “Save claim record”. The app sends the result to the API with your session token.

Our server

ClearClaim API

The only part that can read or write stored data. Checks who you are and what you may see on every request.

Built with

  • Python 3.12
  • FastAPI
  • Pydantic 2
  • SlowAPI rate limits
  • GZip
  • Docker

Worth knowing

  • Your sign-in token is verified locally with Supabase’s public keys (cached), so no extra call per request.
  • Your role comes from the database, never from the browser.
  • Runs on Render’s free tier, which sleeps when idle: the first request can take 30 to 60 seconds.

Working diagrams

See the logic run.

Change the inputs or play a scenario. The calculation uses the same engine as the claim check.

Mostly
No-Claim Bonus now

Fixed for this example: IDV ₹6,00,000, deductible ₹1,000, renewal premium ₹18,000, no zero-dep cover.

1 · What the insurer pays

Repair bill

₹0

Depreciation

₹0

plastic: 50%

Deductible

₹0

always yours

Insurer pays

₹0

never more than your IDV

2 · What claiming costs you

You pay the workshop

₹0

bill − insurer pays

Bonus lost next year

₹0

45% of ₹18,000

Cost of claiming

₹0

3 · The decision

Cost of paying yourself

₹0

the whole bill, bonus kept

Cost of claiming

₹0

Claiming saves

₹3,400

  • More than ₹2,000 → claim
  • Less than −₹1,000 → pay yourself
  • In between → close call

Stack

What it’s made of, and why.

  • Next.jsv16.3

    Pre-renders public pages for speed and search, and hosts the app in one codebase.

  • Reactv19.2

    Component model for the interactive tools.

  • TypeScriptv5

    Catches mistakes in money calculations before they ship.

  • Tailwind CSSv4

    Design tokens (colours, type, spacing) in one place.

  • Framer Motionv13

    Animations that switch off when your device asks for reduced motion.

  • Sonner and Lucide

    Notifications and icons.

Data model

Where the data lives.

The main tables in Postgres. Click one to see what it connects to. The schema has six more (accidents, repairs, repair items, service events, policy add-ons and model outputs) that today’s screens don’t use.

claims

Saved claim checks and their figures

Connected to

Trade-offs

Every choice cost something.

What we chose, what it bought, and what we gave up for it.

What it buys

Instant results, no server cost per check, and your figures never leave your device.

What it costs

The same rules exist in TypeScript and Python. 305 shared test cases keep them identical.

Scalability

What holds up, and what changes next.

  • Claim checks

    Run in each visitor’s browser, so more users add no server load.

  • Public pages

    Pre-rendered and served from Vercel’s CDN.

  • API

    One stateless container on Render’s free tier. Tokens are verified locally, profiles cached for 60 seconds, status for 30.

  • Database

    Lists load in a fixed number of queries (no query per row), with lookups by key.

  • Ledger writes

    Done while saving; if the ledger is down the record is kept as pending and can be retried safely.

  • PDF reading

    In the API process, one file at a time per request, 10 MB cap.

  • Abuse

    Per-client rate limits, size limits and strict input validation.

The code is open: github.com/Sathvik103/InsurTrace. For what we protect and how, see Security.