Utopia is a lightweight, self-hostable personal finance API with partial compatibility with Firefly-III.
Utopia implements a subset of the Firefly-III API surface to provide accounts, token management, transaction journals, and Prometheus metrics. This repository contains the server implementation, database migrations, and supporting infrastructure for local development and observability.
- Accounts API
- Token issuance and management (personal access tokens)
- Bootstrap token issuance (initial provisioning)
- Transactions / journals
- Metadata API (currencies, system info, user profile)
- Prometheus
/metricsendpoint
See the full API contract in openapi.yaml.
Prerequisites: Docker Engine and Docker Compose (or a Rust toolchain for local builds).
Start with Docker Compose:
cp .env.example .env
docker compose -f docker/docker-compose.yml up --buildRun locally (development):
cp .env.example .env
# adjust DATABASE_URL as needed
cargo build
cargo runVerify the service (examples):
# Check metrics endpoint
curl -fsS http://localhost:3000/metrics | head -n 20
# Check metadata endpoints (requires auth token)
curl -fsS http://localhost:3000/api/v1/currencies | head -n 20
curl -fsS http://localhost:3000/api/v1/about | head -n 20Runtime configuration is provided via environment variables. See .env.example for required keys and sensible defaults used for local development.
# Build
cargo build
# Run tests
cargo test
# Lint
cargo clippy -- -D warningssrc/— application source code (server, handlers, core logic)migrations/— database migrationsdocker/— docker-compose and container helperstests/— integration and unit testsaidlc/— AI-DLC workspace (design artifacts, decision records, and method memory)
Architecture, NFRs, and construction plans are generated and maintained under
aidlc/ as part of the AI-DLC workflow. Run /aidlc to start or resume a
workflow; see AGENTS.md for harness setup.
This project is licensed under the BSD-3-Clause license. See LICENSE for details.