Insurance Brokerage System

Next.js 15 + TypeScript insurance brokerage management system for the Nigerian market: clients, policies, broking slips, credit/debit notes, claims, and commissions, with a real brokerage/VAT/statutory-levy calculation engine over a ~44-table Drizzle/Turso schema.

Built with Next.js, React, TypeScript, Drizzle ORM, Turso, and 1 more.

A full-stack back-office system for a Nigerian insurance brokerage, built as a single Next.js 15 (React 19, TypeScript) app on Drizzle ORM over libSQL/Turso with better-auth. It manages the brokerage lifecycle end to end: onboarding company and individual clients (with CAC/RC and TIN capture and KYC docs), creating policies with property items and co-insurance shares, generating single-page broking-slip PDFs, raising credit and debit notes, running a claims workflow (register, assign adjuster, approve/reject/settle), and tracking agent commissions. The domain core is a 324-line calculation module that applies fixed 9/15/20% brokerage slabs, 7.5% VAT on brokerage, agent commission, and the NAICOM/NCRIB/education-tax statutory levies to derive the net amount due to the insurer, with explicit 2-decimal rounding. The data model is broad and genuinely domain-specific: a 744-line schema across ~44 tables, evolved through 21 incremental SQL migrations. The build went through a real deployment fight, migrating the entire API surface to Next.js 15's Promise-based route params and untangling Vercel production-dependency and module-resolution failures. NOTE: the previously-live Vercel URL now 404s and the app needs redeploying to demo.

• Client management for company and individual clients with CAC/RC + TIN capture, KYC document upload, and contacts.
• Policy management with property items, co-insurance shares, renewal tracking, auto-expiry, and single-page broking-slip PDF generation.
• Credit and debit notes with automated brokerage, 7.5% VAT, agent commission, and NAICOM/NCRIB/education-tax levy math, exported to PDF.
• Claims workflow: registration, document upload, adjuster assignment, and approve/reject/settle actions with status tracking.
• Brokerage calculation engine with 9/15/20% slabs and 2-decimal rounding, deriving net-amount-due-to-insurer.
• CSV policy batch import with template and import history.
• Role-based auth (Admin, Underwriter, Accounts, Claims, Marketer, Viewer) via better-auth, with audit logging.
• Nigeria-specific validation and seed data: Naira currency, NUBAN/IBAN bank-account checks, seeded Nigerian insurers, banks, and lines of business.

Every project hits walls. Here's what nearly broke Insurance Brokerage System — and how it shipped anyway.

• Next.js 15's breaking change turned all dynamic route params into Promises, breaking every [id] API handler at once and forcing an app-wide migration to 'await params' plus a cascade of TypeScript fixes.
• Vercel production builds failed because build-time dependencies (TypeScript, @types, Tailwind/@tailwindcss/postcss) were in devDependencies, compounded by module-resolution errors needing tsconfig baseUrl and a webpack alias.
• A note creation/approval change broke a core workflow in production and had to be reverted same-day rather than forward-fixed.
• Encoding Nigeria-specific statutory rules correctly (NAICOM/NCRIB/education-tax levies, 7.5% VAT on brokerage, NUBAN/IBAN validation) instead of leaving them as manual inputs.
• Fitting a multi-section broking slip onto a single-page PDF via pdfkit by tuning font sizes, line heights, and spacing.
• Keeping a ~44-table schema coherent as it evolved across 21 migrations (auth, commissions, claims, batch import, broking slip, renewal tracking).

Every build leaves residue. The takeaways from Insurance Brokerage System that carry forward.

• Framework major-version upgrades (Next.js 14 -> 15) can invalidate an entire API surface at once; the Promise-based params change is a concrete example of why pinning versions and reading migration notes before deploying matters.
• The devDependencies-vs-dependencies distinction is invisible locally and only bites in a clean production build; Vercel/Netlify build failures are usually dependency-placement or module-resolution issues, not app bugs.
• Reverting a regression fast is often the right production call over a risky forward-fix.
• Domain rules (levies, tax, rounding) belong in one tested module, not scattered across form handlers, so they can be verified independently, which is exactly where the only automated tests live.
• GAP/self-reflection for Archit: agentic AI development can generate dozens of near-empty status docs and one-off scripts; pruning that noise makes a repo readable and a portfolio credible.