Developer Overview

Welcome, Developer

This section provides a comprehensive technical reference for NeoCash’s internals. Whether you’re contributing to the codebase, building integrations, or just curious about how a privacy-first AI financial app works under the hood, you’ll find everything here.

Architecture at a Glance

NeoCash is a Next.js 15 application with a local-first architecture:

• Frontend: React 19 with custom hooks for IndexedDB state management
• Backend: Next.js API routes that proxy to Anthropic’s Claude API
• Storage: Browser IndexedDB via idb — no cloud database
• AI: Claude models (Sonnet, Haiku, Opus) with tool use and streaming
• Agent System: 5 specialist agents with keyword + AI-based routing

Data Flow

User Input → Agent Router → Specialist System Prompt
    → Claude API (streaming) → Tool Calls → IndexedDB
    → Signal Detection (Haiku) → Dashboard Updates

Key Subsystems

Chat & Streaming

The /api/chat endpoint handles message streaming with tool execution. Messages are windowed to fit within a 160k token budget, keeping recent messages intact while trimming older ones.

Goal Management

Goals extend conversations with structured dashboards, action items, and AI insights. Each goal has a typed schema (currency, percentage, date, text, number, boolean) that’s auto-generated by Claude based on the goal’s context.

Memory System

Long-term user context is stored as facts (biographical data) and decisions (financial choices). Memories are auto-extracted from conversations and injected into system prompts for personalized responses.

Signal Detection

After each AI response, Claude Haiku analyzes the text against all active goals to detect cross-pollination opportunities — data points from one conversation that are relevant to another goal.

Agent Routing

A three-tier classification system routes messages to the right specialist:

1. Goal category override — instant, no API call
2. Haiku classification — fast AI classification into 5 agent types
3. Keyword fallback — local keyword scoring

Section Guide

Key Files