akncodes/ai-spend-audit

1. This is a Next.js 15 App Router application organized around a single business flow: collect AI tool/spend data, analyze it, persist the audit, and expose a shareable result link. The codebase is split cleanly into route handlers, domain logic, service wrappers, and reusable UI.

2. The main user-facing surfaces are:

• / for the landing page

• /scan for entering team spend/tool usage

• /audit/results/[slug] for the authenticated/internal results view

• /audit/share/[slug] for a public share page

The app/(audit) route group keeps the audit experience together without changing URLs.

3. Input collection is handled by components/forms/SpendForm.tsx and ToolSelector.tsx, with form-schemas.ts providing validation rules. The repo uses Zod + React Hook Form, so validation happens before the request reaches the API layer.

4. The server API surface is small and purpose-built:

• POST/GET /api/audit for creating an audit

• GET /api/audit/[slug] for retrieving an existing audit by share slug

• /api/tools for the supported tool catalog

• /api/leads for capturing interested users

• /api/health for deployment/liveness checks

These route handlers are the boundary between the browser and the server-side domain logic.

5. lib/audit-engine.ts is the core business logic. It appears to be the deterministic scoring layer that decides whether a team is overpaying, calculates savings opportunities, and produces the audit findings. The presence of a dedicated unit test file for it suggests this logic is meant to stay pure and well-covered.

6. lib/audit-service.ts likely orchestrates the full audit lifecycle: accept normalized form data, invoke the audit engine, store the audit result, and return the slug used for sharing. This is the main application service that connects business rules to persistence and external services.

7. lib/ai-service.ts is the content-generation boundary. Per the README, Anthropic is used for summaries, so the audit likely combines deterministic savings analysis with an AI-written explanation or executive summary. This keeps the model-driven text separate from the scoring logic.

8. Persistence and integration are centralized:

• lib/supabase.ts encapsulates Supabase access

• Supabase provides the backing data store for audits and related records

• lib/email-service.ts handles outbound email, using Gmail/Nodemailer per the README

• lib/tools-config.ts provides the supported AI tools and their pricing/plan metadata

This makes the repo easy to diagram as “app → service layer → external providers.”

9. The results flow is slug-based. After an audit is created, the user is routed to a results page keyed by slug. The client component at app/(audit)/results/[slug]/AuditResultsClient.tsx suggests the page may fetch or hydrate data client-side after the initial server render. The public share page reuses the same underlying audit record but presents it without the internal scan workflow.

10. lib/types.ts and lib/utils.ts provide shared contracts and helpers used across UI, API, and services. The components/ui folder is a reusable primitive layer for the form and page UI, not a domain subsystem.

11. Quality gates are lightweight but focused: __tests__/audit-engine.test.ts validates the scoring logic, and __tests__/form-validation.test.ts validates the input schema behavior. CI is wired through GitHub Actions, so the main architectural risk areas are the business rules and form validation rather than infrastructure complexity.

12. Operationally, this is a serverless-style web app: all important work happens in request/response handlers or shared server modules, with no separate worker queue or background job system visible in the tree. The key external dependencies that matter architecturally are Supabase for data storage, Anthropic for summaries, and Gmail/Nodemailer for outbound email.