ExpenseOwl

ExpenseOwl is a lightweight, single‑user expense tracking service designed for self‑hosting scenarios where speed and simplicity trump feature breadth. From a developer’s perspective, it exposes a minimal yet well‑structured API surface, leverages a modern JavaScript stack for the front end, and packs all runtime dependencies into a single binary or multi‑arch Docker image. The application focuses on three core use cases: adding transactions, visualizing monthly spend by category, and exporting/importing data. It intentionally omits complex budgeting, account hierarchies, or multi‑user authentication to keep the codebase approachable and the runtime footprint low.

Technical Stack

The Go server exposes a small RESTful API (/api/v1/...) that the Vue front end consumes. All data is persisted in a single SQLite file (data.db), which the container can mount as a volume for persistence across restarts. The binary is built with -ldflags "-s -w" to strip debug symbols, keeping the image size under 30 MB.

Core Capabilities & APIs

• Transaction CRUD: Endpoints for creating, listing, updating, and deleting transactions. Each transaction includes date, amount, category_id, optional tags, and a recurring flag.
• Category Management: CRUD for categories, including reordering and custom names. Categories are referenced by a UUID to avoid accidental renaming issues.
• Recurring Scheduler: A lightweight scheduler runs on server start, generating recurring transactions based on a cron‑like frequency (daily, weekly, monthly).
• Export/Import: /api/v1/export streams CSV data; /api/v1/import accepts a multipart file and replaces the current database (useful for backups or migrations).
• Metrics Endpoint: /metrics exposes Prometheus‑style counters (e.g., transactions_total, recurring_runs) for observability.
• Webhooks: Optional outbound POST hooks can be configured in settings to notify external services when a transaction is added or updated.

The API follows REST conventions and returns JSON payloads with appropriate HTTP status codes. Authentication is intentionally omitted; developers can wrap the service in an NGINX reverse proxy with basic auth or integrate it into a larger authentication layer if needed.

Deployment & Infrastructure

• Self‑Hosting: The application can run on any machine that supports Go binaries or Docker. For non‑Docker users, a single binary plus SQLite file is all that’s required.
• Container Orchestration: The Docker image includes a docker-entrypoint.sh that initializes the database schema on first run. A typical deployment in Docker Compose looks like:

services:
  expenseowl:
    image: tanq16/expenseowl:latest
    volumes:
      - ./data:/app/data
    ports:
      - "8080:80"

• Scalability: Designed for single‑user workloads; however, the stateless API and SQLite file can be replicated across a cluster with shared storage (e.g., NFS) if a multi‑user scenario is required. For higher throughput, replace SQLite with PostgreSQL and adjust the migration scripts accordingly.
• Resource Footprint: The binary consumes <10 MiB RAM on startup; peak usage stays below 30 MiB even under moderate load. CPU usage is negligible, making it suitable for Raspberry Pi or cloud micro‑instances.

Integration & Extensibility

• Plugin Architecture: While no built‑in plugin system exists, the Go codebase exposes a simple plugins package that can be extended by importing additional modules. Developers can add new endpoints or modify the scheduler without altering the core server.
• Webhooks & Callbacks: The optional webhook feature allows integration with external services such as Slack, email notifications, or custom dashboards. Payloads include full transaction data and can be signed with HMAC for security.
• Custom Frontend: The Vue app is bundled as static assets; developers may replace it with a custom UI that consumes the same API, enabling mobile apps or desktop Electron wrappers.
• PWA Support: The front end registers a service worker and includes manifest.json, allowing installation on Android, iOS (via Safari), and desktop browsers. This makes it possible to use the app offline while still syncing with the backend when online.

Developer Experience

• Configuration: All settings are stored in a JSON file (config.json) that the server reads on startup. Developers can tweak defaults (currency symbol, start date) without recompiling.
• Documentation: The GitHub repository contains a comprehensive README.md with API reference, data model diagrams, and deployment examples. The code is well‑