FinOps Agent

What it does#

FinOps Agent is a personal budgeting application with a multi-agent spending-intelligence engine. Its design goal is production-grade, multi-user infrastructure behind a single-user experience: the plumbing is built like a real product, while the UX stays focused on one person's money. It ingests transactions, categorises and analyses them through a set of agents, and answers questions about spending.

Monorepo#

A Turborepo workspace managed with pnpm, with clear separation between apps and shared packages:

apps/web              Next.js 15 frontend (App Router)
apps/api              FastAPI backend
packages/ui           design system (Storybook)
packages/shared-types generated TypeScript types
packages/tsconfig     shared TS presets
packages/eslint-config
docker/               Compose configs (MongoDB, Redis, init)
docs/                 plans, ADRs, test docs

Backend#

FastAPI exposes the REST API, with MongoDB for persistence through the Beanie ODM and Redis for caching. Interactive OpenAPI docs are served at /docs. The multi-agent layer runs the financial analysis: transaction categorisation and spending insight over the data store.

Frontend#

Next.js 15 (App Router) with styled-components v6, built against the shared packages/ui design system that is documented in Storybook.

The contract: generated types#

A key decision is that the frontend never hand-writes API types. pnpm types:generate reads the backend OpenAPI schema and emits TypeScript into packages/shared-types, so the web app and the API cannot silently drift apart.

Developer workflow#

pnpm dev             # web + api in parallel via Turbo
pnpm typecheck       # tsc + mypy (strict)
pnpm test            # Vitest (web) + pytest (api)
pnpm lint            # ESLint + Ruff
pnpm seed            # 24 months of demo transactions

Docker Compose brings up MongoDB, Redis, and an init service; locally the web app runs on http://localhost:1234 and the API on http://localhost:8000. Node and tool versions are pinned via .nvmrc and .tool-versions, and architecture notes live in CLAUDE.md. By line count the codebase is an even split of Python (about 52%) and TypeScript (about 48%).

Why it matters#

It is a blueprint for a serious full-stack AI product: strict type-safety across the Python and TypeScript boundary, a real caching and persistence layer, agent-driven analysis, and the monorepo tooling to hold it together.