Family Accounting Tool

Family Accounting Tool (FACTO) is a self‑hosted, Java‑based web application that models household finances as a relational database. From a developer’s perspective it is essentially a Spring‑style MVC service built on the Play Framework, with data access handled by Slick and a MySQL/MariaDB backend. The core purpose is to ingest raw transaction records, compute family‑level metrics (spending by category, internal debt balances, hidden fees), and expose those results through a web UI that can be queried programmatically via REST endpoints.

Architecture & Technical Stack

• Language: Java 11 (JDK 11) with optional Scala support through Play’s mixed‑language ecosystem.
• Web Framework: Play 2.x – provides a lightweight, asynchronous HTTP server and routing DSL.
• Persistence: Slick 3.x with MySQL/MariaDB drivers; schema migrations are managed via bin/server -DdropAndCreateNewDb.
• Configuration: HOCON (conf/application.conf) for database, secret keys, and Play settings; YAML (accounting-config.yml) for domain‑specific parameters (e.g., user login names).
• Build: sbt (Scala Build Tool) orchestrates compilation, packaging, and test execution; CI is defined in GitHub Actions.

Core Capabilities & APIs

FACTO exposes a set of RESTful endpoints under /api that allow CRUD operations on transactions, accounts, and user balances. These APIs return JSON payloads with typed models that mirror the Slick case classes. The application also provides a WebSocket channel for real‑time updates to dashboards, useful when integrating with front‑end frameworks like React or Vue. Internally, a scheduled job aggregates daily statistics and persists them in a separate reports table for fast retrieval.

Deployment & Infrastructure

The recommended deployment model is stand‑alone binary with a local MariaDB instance. The bin/server script boots an embedded Netty server on port 9000, making it trivial to run as a systemd service or within Docker if desired. Although the Docker compose example is discouraged for production, it demonstrates that FACTO can be containerized with a separate database container. The application is stateless apart from the database, enabling horizontal scaling by running multiple instances behind a load balancer and sharing the same MySQL backend.

Integration & Extensibility

Developers can extend FACTO through:

• Plugin hooks: Custom Java modules can be dropped into the plugins directory and discovered via Play’s dependency injection.
• Webhooks: External services (e.g., bank APIs) can POST new transactions to /api/transactions.
• Scripting: The accounting-config.yml supports user‑defined rules for categorizing expenses, which can be enhanced by adding new YAML entries or overriding the parsing logic in Java.
• OAuth/JWT: While not built‑in, the Play security filters can be configured to integrate with an external identity provider.

Developer Experience

Configuration is driven by clear, well‑documented HOCON and YAML files. The repository contains comprehensive unit tests and integration tests that exercise the Slick queries, ensuring that schema changes are caught early. Community support is modest but active on GitHub issues; the CI pipeline guarantees that every pull request passes all tests before merging. The codebase follows standard Java conventions, making it approachable for teams familiar with Play or Spring MVC.

Use Cases

• Family finance dashboards: Deploy on a home server to centralize all household transactions and generate monthly reports.
• Educational projects: Use the open‑source code to teach students about relational modeling, REST APIs, and Java web development.
• Small business bookkeeping: Adapt the internal debt logic to track inter‑departmental expenses or employee reimbursements.
• Personal budgeting tools: Integrate FACTO with personal finance apps via its REST API to sync transactions automatically.

Advantages

• Open source & license‑free: No proprietary costs, allowing full control over the deployment environment.
• Performance: Slick’s compiled queries and Play’s non‑blocking I/O deliver low latency even with thousands of daily transactions.
• Flexibility: The configuration‑driven model lets developers tailor the accounting logic without touching code.
• Self‑hosted security: All data resides on the user’s own infrastructure, eliminating third‑party exposure.

In summary, FACTO offers a robust, developer‑friendly platform for building household or small‑business accounting solutions with minimal operational overhead and maximum extensibility.