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 /metrics endpoint

See the full API contract in openapi.yaml.

Prerequisites: Docker Engine and Docker Compose (or a Rust toolchain for local builds). For exact toolchain and build instructions see aidlc-docs/construction/build-and-test/build-instructions.md.

Start with Docker Compose:

cp .env.example .env
docker compose -f docker/docker-compose.yml up --build

Run locally (development):

cp .env.example .env
# adjust DATABASE_URL as needed
cargo build
cargo run

Verify 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 20

Runtime configuration is provided via environment variables. See .env.example for required keys and sensible defaults used for local development.

Refer to aidlc-docs/construction/build-and-test/build-instructions.md for recommended toolchain versions, CI checks, and detailed build and test commands.

• src/ — application source code (server, handlers, core logic)
• migrations/ — database migrations
• docker/ — docker-compose and container helpers
• aidlc-docs/ — architectural and planning documents
• tests/ — integration and unit tests

For a detailed code layout and design rationale see aidlc-docs/.

Design artifacts, plans, and implementation notes live in aidlc-docs/. Use those documents for architecture, NFRs, and construction plans.

This project is licensed under the BSD-3-Clause license. See LICENSE for details.