Foppy AI - Backend

Voice-driven personal finance backend. Speak one sentence in Spanish; log a transaction, savings goal, or budget.

Foppy AI grew out of Fopymes, the prototype my teammate and I built for the Hatary Shunko Fintech Innovation Contest 2025, where it took 3rd place. After the event, the two of us kept iterating on it as a more complete personal-finance application. This repo is the backend.

Frontend: devjaes/foppy-ai-front

Problem

Manual expense tracking is tedious enough that most people stop doing it. We wanted a Spanish-language voice interface so a user could capture a transaction, savings goal, or budget in a single spoken sentence - and a backend that turns that audio into structured, validated finance records.

Approach

Audio is recorded on the Next.js client and sent to this Hono backend running on Bun. OpenAI Whisper transcribes the Spanish speech; a GPT-class model classifies intent (transaction, goal, or budget) and extracts structured fields. A small set of agent services - voice-orchestrator, transaction-agent, goal-agent, budget-agent, validation-agent - normalize and validate the extracted data before it returns to the UI for confirmation. The backend follows a hexagonal (ports & adapters) layout with Drizzle ORM over PostgreSQL, so the Whisper / LLM providers sit behind swappable adapters.

Stack

Layer	Tech
Runtime	Bun
HTTP	Hono + @hono/zod-openapi (OpenAPI / Scalar reference at /reference)
ORM	Drizzle ORM
DB	PostgreSQL
Validation	Zod
AI	OpenAI Whisper (STT) + GPT / OpenRouter (intent routing, multi-agent)
Logging	Pino + hono-pino
Infra	Docker / docker-compose

Highlights

• Voice-first capture for transactions, savings goals, and budgets via a Whisper STT → LLM intent-routing pipeline.
• Multi-agent orchestration (voice-orchestrator dispatches to per-domain agents + a validation agent) lives in src/features/ai-agents/.
• Hexagonal layout per feature (application / domain / infrastructure) - Whisper and LLM providers are adapters behind ports, so swapping OpenAI ↔ OpenRouter is local to the adapter layer.
• Drizzle schema with migrations and seed / clean scripts for fast local resets.
• Surrounding finance domain features already wired in: auth, categories, payment methods, debts, subscriptions, scheduled transactions, recommendations, reports (CSV / Excel / PDF) and email notifications via Brevo.
• Dockerized PostgreSQL for local dev; container entrypoint for the API.

Local setup

# 1. install
bun install

# 2. env
cp .env.example .env       # set OPENAI_*, DATABASE_URL, etc.

# 3. database (Postgres in Docker)
docker compose up -d

# 4. migrations + seed
bun run generate           # bun drizzle-kit generate (only if schema changed)
bun run migrate            # bun drizzle-kit migrate
bun run db:seed            # seed default categories

# 5. dev server
bun run dev                # bun run --hot src/index.ts

Useful scripts (see package.json):

Script	What it does
bun run dev	Hot-reload dev server
bun run build	Bundle to dist/
bun run start	Run the built bundle
bun run migrate	Apply Drizzle migrations
bun run generate	Generate Drizzle migrations
bun run db:seed	Seed categories
bun run db:clean	Wipe the database
bun run db:refresh	db:clean then db:seed
bun run test	Vitest

Once the server is up, the OpenAPI reference is served at /reference.

Project layout

src/
├── app.ts
├── index.ts
├── core/
│   └── infrastructure/        # db, env, lib, middleware, types
├── features/
│   ├── ai-agents/             # Whisper adapter + multi-agent orchestrator
│   ├── transactions/  goals/  budgets/  categories/
│   ├── auth/  users/  friends/
│   ├── debts/  subscriptions/ scheduled-transactions/
│   ├── payment-methods/  recommendations/
│   ├── reports/  notifications/  email/
└── shared/                    # utils + shared services

Each feature follows application/ (DTOs, services, use-cases) · domain/ (entities, ports) · infrastructure/ (adapters, controllers).

Status

• Built for the Hatary Shunko Fintech Innovation Contest (3rd place, Apr 2025) and actively iterated since.
• Spanish-first UX. Multi-locale roadmap-tracked.

Team

• My role: Backend lead (~72% of backend commits) - multi-agent orchestrator, Whisper / LLM adapters, validation layer, Drizzle schema, Hono routes.
• Co-author: Pablo Martínez (@SrPabvliss).
• Two-person team.

Recognition

3rd place - Hatary Shunko Fintech Innovation Contest 2025. Originally shipped as the Fopymes hackathon prototype, then iterated post-event into Foppy AI.

License

MIT.