Agentic Cost Calculator Development

Development guidance for working with the Agentic Coding Cost Calculator repository - a full-stack TypeScript application for calculating AI/LLM development costs and savings.

Project Overview

This is a monorepo containing a React + Vite client and Express server that share TypeScript code for calculating costs associated with AI-assisted development. The application helps users estimate savings from using LLM tools like Claude, GPT, and other models.

Development Commands

When working in this repository, use these commands:

Starting Development Servers

Building for Production

Code Quality

Package Management

Architecture Guide

Client-Side (React + Vite)

Server-Side (Express + TypeScript)

Shared Code (Critical)

Key Implementation Details

Calculation Flow

1. User fills form → Client validation

2. Form submits to `POST /api/calculate`

3. Server validates with Zod schemas

4. `calculateCosts()` processes:

- Project parameters (hours, rates, token usage)

- Model configurations (pricing tiers)

- Global settings (currency, multipliers)

5. Returns comprehensive analysis (costs, savings, projections)

6. Client displays results with charts and export options

UI Modes

TypeScript Configuration

Testing

Important Constraints

1. **Always use pnpm** - Not npm or yarn (configured in package.json)

2. **Shared code is source of truth** - Types and calculations live in `src/shared/`

3. **Validate on both sides** - Client validates UX, server validates security

4. **Currency support** - USD/AUD with configurable exchange rates

5. **Persistent state** - Wizard mode saves progress to localStorage

6. **Export features** - Support both PDF and JSON export formats

Common Tasks

Adding a New LLM Model

1. Update `src/shared/utils/modelConfig.ts` with pricing and capabilities

2. Add model to appropriate tier in `MODELS_BY_TIER`

3. Update type definitions if needed in `src/shared/types/models.ts`

Modifying Calculation Logic

1. Edit `src/shared/utils/calculations.ts`

2. Update types in `src/shared/types/models.ts` if return structure changes

3. Update server validation in `src/server/routes/api.ts` if input changes

4. Run tests: `pnpm test`

Adding a Form Field

1. Update `CalculationFormState` type in `src/shared/types/models.ts`

2. Add field to form UI (wizard or advanced)

3. Update validation logic in `useCalculatorForm.ts`

4. Update server-side Zod schema if field affects API

5. Modify calculation engine if field affects cost logic

Debugging the Calculation Engine

1. Check browser console for client-side errors

2. Check server logs (port 3001) for API errors

3. Inspect network tab for `/api/calculate` request/response

4. Add console.logs to `src/shared/utils/calculations.ts` (both client and server will use it)

Data Flow Summary

```

User Input → Form State → Validation → API Call (/api/calculate)

↓

Server Validation (Zod) → calculateCosts() → Results

↓

Client State → UI Display (Charts, Summaries) → Export (PDF/JSON)

```