Kanakku

கணக்கு — Tamil for "account" or "calculation"

A Privacy-First AI Financial Navigator that bridges the gap between cold mathematical data and the emotional weight of personal finance. The system provides a high-empathy, voice-driven experience that acts as a personalized advisor — without ever storing sensitive documents or real-world identities on a server.

All financial calculations run client-side in the browser. The server is a stateless proxy that forwards API calls but stores nothing. When you close the tab, everything is gone.

---

Prerequisites

• Node.js ≥ 20.4
• npm ≥ 9
• An Anthropic API key (required — powers conversation and intent routing)
• A Deepgram API key (optional — enables voice input)
• An ElevenLabs API key + Voice ID (optional — enables audio narration)

---

Setup

1. Install dependencies

# From the project root
cd client && npm install
cd ../server && npm install

2. Configure API keys

Edit .env in the project root:

ANTHROPIC_API_KEY=sk-ant-...       # Required
DEEPGRAM_API_KEY=                  # Optional — voice input
ELEVENLABS_API_KEY=                # Optional — audio narration
ELEVENLABS_VOICE_ID=               # Optional — e.g. EXAVITQu4vr4xnSDxMaL (Sarah)
PORT=3001

The app runs without Deepgram and ElevenLabs keys — voice input and audio narration are simply unavailable, and the UI degrades gracefully. Text input and streaming text responses work with the Anthropic key alone.

---

Running

Open two terminals from the project root.

Terminal 1 — proxy server:

cd server && npm run dev
# Listening on http://localhost:3001

Terminal 2 — frontend:

cd client && npm run dev
# Open http://localhost:5173

---

What the app does

Type (or speak) a financial question. The system:

1. Strips structured PII from your input before it leaves the browser
2. Classifies your intent (Claude Haiku) — CALC, INFO, CHAT, HYBRID, or COMPARE
3. Runs any required calculations locally using the in-browser math engine
4. Looks up relevant financial term definitions from a static knowledge base
5. Streams an empathetic narrative response (Claude Sonnet)
6. Narrates the response aloud (ElevenLabs, if configured)
7. Renders a chart alongside the transcript

"Download summary" appears after the first assistant reply — it generates a PDF of the full session (transcript, financial snapshot, chart) entirely in the browser.

"End session" wipes all data from sessionStorage. Closing the tab does the same automatically.

---

Example queries to try

What to type	What happens
I'm overwhelmed by my debt	Empathetic CHAT response, no chart
What is compound interest?	INFO — definition narrated in context
I owe $8,000 at 22% APR over 24 months	CALC — amortization chart + payoff narration
I have $15k debt and $40k savings	Leaking Bucket overlay chart showing net loss per year
What is APR and how does it affect my $8k debt?	HYBRID — definition + calculation together
What if I pay half now and the rest over 12 months?	COMPARE — side-by-side table with dollar cost of each path
Should I buy Tesla stock?	Graceful out-of-scope decline

---

Privacy model

Threat model: no data on our server.

• The proxy server forwards requests and immediately discards them — no database, no logs, no session storage.
• Financial numbers never leave the browser for calculations; only the narrative prompt (with your numbers) is sent to the Anthropic API.
• Voice audio goes to Deepgram. Generated speech text goes to ElevenLabs. These are accepted third-party services under this threat model.
• Names and street addresses are not caught by the PII scrubber — the UI reminds you not to share them.
• All session data lives in sessionStorage and is wiped on tab close.

---

Running tests

cd client && npm test

50 unit tests covering the math engine (amortization, savings, budget, net worth, scenario comparison) and the PII scrubber.

---

Project structure

kanakku/
├── .env                          # API keys (never committed)
├── client/                       # React + Vite frontend
│   └── src/
│       ├── components/
│       │   ├── AudioPlayer.jsx   # Waveform animation + play/pause
│       │   ├── ChartPanel.jsx    # Plotly charts (6 types)
│       │   └── InputBar.jsx      # Text input + mic button
│       ├── hooks/
│       │   ├── useAudio.js       # ElevenLabs TTS playback
│       │   ├── useMicrophone.js  # Deepgram STT via WebSocket
│       │   ├── useNarrator.js    # Claude SSE stream consumer
│       │   ├── useSessionStore.js# sessionStorage (history + context)
│       │   └── useTurn.js        # Turn orchestrator (wires everything)
│       └── lib/
│           ├── contextBuilder.js # Builds Claude message array
│           ├── exportSummary.js  # jsPDF client-side export
│           ├── financialTerms.json # 50 financial definitions
│           ├── knowledgeBase.js  # Term lookup
│           ├── mathDispatch.js   # Routes context → math engine + chart data
│           ├── mathEngine.js     # Pure JS calculators (no network)
│           ├── persona.js        # Claude system prompt
│           ├── piiScrubber.js    # Strips emails, phones, SSNs, card numbers
│           └── router.js         # Intent classifier (Claude Haiku)
└── server/                       # Stateless Express proxy
    └── index.js                  # /api/chat, /api/speak, ws:/api/transcribe