API and Server Actions

Cashlytics primarily uses Next.js Server Actions as the application API layer.

Implementation Model

• Mutations and queries are implemented in src/actions/*.
• AI chat is exposed via an API route in src/app/api/chat/route.ts.
• Responses use a consistent success/error shape.

Core Action Domains

• Accounts
• Expenses, daily expenses, subscriptions, and attachments
• Income
• Transfers
• Categories
• Dashboard and analytics
• Forecasts
• Search and AI conversations
• Documents
• CSV import staging, reconciliation, conflict decisions, and confirmation
• User settings
• Exchange rates
• Push subscriptions and upcoming payment cron

API Routes

Route	Purpose	Notes
POST /api/chat	AI assistant chat and tool orchestration	Requires OPENAI_API_KEY; authenticated and rate-limited
POST /api/receipt-scan	Receipt image extraction	Requires OPENAI_API_KEY; JPG/PNG, 5 MB limit
GET /api/documents	List user documents	Authenticated
POST /api/documents	Upload a document	Authenticated; PDF/PNG/JPG/JPEG, 5 MB limit
GET /api/documents/[id]	Fetch one document	Authenticated/user-scoped behavior should be preserved when changing this route
DELETE /api/documents/[id]	Delete one document	Used by document library workflows
GET /api/exchange-rates	Return EUR-based exchange rates	Refreshes stale cache and falls back when upstream rates are unavailable
GET /api/push/vapid-public-key	Return browser push public key	Requires VAPID configuration for useful output
POST /api/push/subscribe	Save push subscription	Authenticated
DELETE /api/push/subscribe	Remove push subscription	Authenticated
GET /api/cron/upcoming-payments	Send upcoming payment reminders	Requires Authorization: Bearer <CRON_SECRET>

Import Actions

CSV import is implemented in src/actions/import-actions.ts and supporting services under src/lib/import. The flow stages rows first, runs deterministic and AI reconciliation, records conflict decisions, and only writes income/expense records during final confirmation.

Typical Action Contract

type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: string };

Revalidation Strategy

After successful writes, affected paths are revalidated so dashboard and list views stay consistent.

Related Source Docs

• cashlytics/docs/api/README.md
• cashlytics/docs/api/expenses.md
• cashlytics/docs/api/incomes.md
• cashlytics/docs/api/accounts.md
• cashlytics/docs/api/transfers.md

For AI scope, restrictions, and approval rules, see AI Capabilities and Guardrails.