How spy4x/financy works
Project type and purpose
• Financy is a self-hostable, full-stack finance-tracking web application with:
• A PWA-style frontend (apps/web) written in Preact/TypeScript
• A Deno-based backend API (apps/api) implementing CQRS, WebSockets, and HTTP endpoints
• Real-time updates via WebSockets and a Telegram bot integration
• A PostgreSQL database plus caching (Redis or Deno KV)
• Containerization (Docker Compose) and infrastructure/monitoring (Prometheus, Loki, Grafana)
File structure
• Top-level “apps” folder contains two sub-apps:
• apps/web: PWA UI, service worker, Vite, Tailwind, offline Dexie DB
• apps/api: Deno service hosting HTTP routes, WebSocket gateway, CQRS handlers, middleware, workers
• “libs” folder houses shared TypeScript modules for client/server/db/cqrs/helpers
• “infra” folder holds Docker Compose files (dev/prod), deployment scripts, monitoring configs
• “docs” describes architecture, tech stack, deployment. “e2e” and unit tests validate behavior.
README for additional insights
• Confirms CQRS pattern (commandBus, queryBus, eventBus).
• Real-time WebSocket API and push notifications planned.
• PWA foundation with offline-first behavior.
• Infrastructure uses Docker Compose, SSL/TLS, monitoring (Prometheus & Loki) and deployment scripts.
Main components and their interactions
a. Frontend (PWA)
• Service worker & Dexie (offline cache)
• UI components connect to API via HTTPS and WebSocket
• Local state management, eventBus for UI updates
b. Backend API (Deno)
• HTTP API (REST-like routes in apps/api/routes/*.ts)
• WebSocket gateway for real-time events
• CQRS layer:
• Command bus → command-handlers → event bus
• Query bus → query-handlers (read models)
• Middleware: auth, logging
• Services: db (Postgres), cache (Redis or Deno KV), webPush, websockets, Telegram bot
• Workers: Telegram polling worker
c. Data stores
• Primary store: PostgreSQL (libs/server/db/migrations/*.sql)
• Caching layer: Redis or Deno KV for high-throughput reads
d. External integrations
• Telegram Bot API (apps/api/services/telegram + worker)
• Push notifications (webPush)
• Monitoring & logging: Prometheus, Loki, Grafana
Architectural patterns and design principles
• CQRS (separate command/write and query/read pipelines)
• Event-driven design: eventBus publishes domain events → event-handlers (e.g., WebSocket notifications, seeding data)
• Layered architecture: routes → handlers → services → data access
• Monorepo with shared libraries for code reuse
• PWA offline-first strategy with Dexie/IndexedDB