Ocular

Ocular is a self‑hosted web application designed for personal and small‑team financial tracking. From a technical standpoint it exposes a RESTful API over HTTPS, serves a single‑page React front‑end, and persists all data in a lightweight SQLite database. The architecture is intentionally minimal to keep the deployment footprint small while still providing robust features such as multi‑year budgeting, Sankey visualizations, and PWA support. Developers looking to embed or extend Ocular will find a clean codebase with well‑defined interfaces, an open‑source license (MIT), and Docker images that enable rapid provisioning in any containerized environment.

Key Features

• API‑first design – All CRUD operations for budgets, categories, and transactions are available via /api/... endpoints. The API uses JWT authentication that can be integrated with existing OAuth providers or the built‑in user system.
• Data import/export – Ocular can ingest a Google Sheets CSV export of an annual planner, translating it into its internal JSON schema. Exporting is a single .json file that can be imported back, enabling data migration or backup.
• Visual analytics – The front‑end renders a Sankey diagram using D3.js, giving instant insight into money flow across categories and years. The component is fully reusable; developers can embed it in other dashboards.
• PWA & mobile readiness – The service worker, manifest, and responsive design allow the app to be installed on iOS/Android devices with offline support for viewing cached data.

Technical Stack

The choice of SQLite keeps the deployment lightweight and suitable for single‑user or small‑team scenarios, while Knex abstracts SQL queries to allow future migration to PostgreSQL if needed.

Core Capabilities

• Programmatic access – Endpoints such as /api/budgets, /api/categories, and /api/transactions return JSON payloads that can be consumed by custom dashboards or automation scripts.
• Webhooks – Ocular emits webhook events on creation, update, or deletion of key entities. This enables real‑time integration with external services like Slack or a custom analytics pipeline.
• Extensibility hooks – The API surface is documented with OpenAPI annotations, allowing developers to generate client libraries in any language. Additionally, the front‑end exposes a global ocular object that can be extended with custom components.

Deployment & Infrastructure

Deploying Ocular is as simple as pulling the pre‑built Docker image and running docker-compose up -d. The compose file mounts a local directory for the SQLite database, ensuring data persistence across container restarts. For production use, Ocular can be placed behind a reverse proxy (NGINX or Traefik) with TLS termination, and the database can be swapped for a managed PostgreSQL instance by updating Knex configuration. Scaling horizontally is limited by SQLite’s single‑writer constraint, but the application can run multiple read replicas behind a load balancer if read throughput becomes a bottleneck.

Integration & Extensibility

• Plugin system – While Ocular does not yet have a formal plugin API, its modular architecture allows developers to fork the repository and add new routes or UI panels. The React component tree is exported as a library, so custom visualizations can be injected.
• Custom data sources – The import routine is pluggable; developers can write a small script that transforms CSV or JSON from other budgeting tools (YNAB, Mint) into Ocular’s schema.
• Scripting – Because the backend is Node.js, developers can write cron jobs or serverless functions that call Ocular’s API to perform nightly reconciliations or send budget alerts.

Developer Experience

The project ships with comprehensive documentation hosted at https://simonwep.github.io/ocular. The README covers quickstart, deployment, and API usage. TypeScript typings are included for both server and client code, improving IDE support. The community is active on GitHub; issues are triaged quickly, and pull requests receive prompt reviews. The MIT license removes any licensing friction for commercial or internal use.

Use Cases

• Personal finance tracker – An individual can host Ocular on a Raspberry Pi, sync data from Google Sheets, and access the app via their phone or laptop.
• Small business budgeting – A startup with a handful of employees can use Ocular’s multi‑user authentication to share budgets, while the API allows integration with accounting software.
• Financial education – Educators can deploy Ocular in a classroom setting, letting students import mock data and visualize spending patterns.

Advantages

• Zero‑config Docker – No need to install Node, NPM, or a database server; the entire stack is encapsulated in containers.
• Fast UI – React with Tailwind and D3.js delivers a responsive, low‑latency experience even on