# spy4x/financy architecture

> Architecture diagram of the GitHub repository spy4x/financy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spy4x/financy
- Repository: https://github.com/spy4x/financy

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser
    User["User"]:::user
    Browser["Browser (PWA)"]:::browser

    %% Frontend Subgraph
    subgraph "Frontend (PWA)" 
        direction TB
        WebApp["PWA App"]:::frontend
        SW["Service Worker"]:::frontend
        Manifest["Web Manifest"]:::frontend
        Components["UI Components"]:::frontend
        Routes["Client Routes"]:::frontend
        State["State Management"]:::frontend
        EventBusFE["Event Bus"]:::frontend
        WebApp -->|bootstrap| Main[/"main.tsx"/]:::frontend
        WebApp --> SW
        WebApp --> Manifest
        WebApp --> Components
        WebApp --> Routes
        WebApp --> State
        State --> EventBusFE
    end

    %% Backend API Subgraph
    subgraph "Backend (Deno API)"
        direction TB
        subgraph "Entry Points"
            direction TB
            HTTP["HTTP API Routes"]:::backend
            WS["WebSocket Gateway"]:::backend
        end

        subgraph "Middlewares"
            direction TB
            AuthMW["Authentication Middleware"]:::backend
            LogMW["Logging Middleware"]:::backend
        end

        subgraph "CQRS"
            direction TB
            CmdBus["Command Bus"]:::cqrs
            QueryBus["Query Bus"]:::cqrs
            EventBusBE["Event Bus"]:::cqrs
            subgraph "Handlers"
                direction TB
                CmdHandlers["Command Handlers"]:::cqrs
                QueryHandlers["Query Handlers"]:::cqrs
                EventHandlers["Event Handlers"]:::cqrs
            end
        end

        subgraph "Services"
            direction TB
            AuthSvc["Auth Services"]:::service
            DBSvc["Database Service (PostgreSQL)"]:::service
            CacheSvc["Cache Service (Redis/Deno KV)"]:::service
            PushSvc["WebPush Service"]:::service
            WSvc["Telegram Bot Service"]:::service
        end

        subgraph "Workers"
            direction TB
            TelegramWorker["Telegram Polling Worker"]:::service
        end

        HTTP -->|auth & log| AuthMW --> LogMW --> CmdBus
        HTTP -->|auth & log| AuthMW --> LogMW --> QueryBus
        WS --> CmdBus
        CmdBus --> CmdHandlers --> EventBusBE --> EventHandlers --> WS
        QueryBus --> QueryHandlers
        QueryHandlers --> DBSvc
        QueryHandlers --> CacheSvc
        CmdHandlers --> DBSvc
        CmdHandlers --> CacheSvc
        EventHandlers --> PushSvc
        EventHandlers --> WS
        TelegramWorker --> WSvc --> DBSvc
        PushSvc --> SW
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres["PostgreSQL"]:::db
        Cache["Redis / Deno KV"]:::db
    end

    %% External Integrations
    TelegramAPI["Telegram Bot API"]:::external
    Monitoring["Monitoring Stack"]:::external
    subgraph "Monitoring"
        direction TB
        Prom["Prometheus"]:::external
        Loki["Loki"]:::external
        Graf["Grafana"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Docker["Docker Compose"]:::infra
        Nginx["Nginx Reverse Proxy"]:::infra
    end

    %% Connections
    User -->|uses| Browser
    Browser -->|HTTPS| HTTP
    Browser -->|WS| WS
    Browser -->|offline| SW
    HTTP -->|SQL| Postgres
    HTTP -->|cache| Cache
    AuthMW -->|SQL| Postgres
    AuthMW -->|cache| Cache
    Docker --> HTTP
    Docker --> WS
    Docker --> Nginx
    Nginx --> Browser
    Monitoring --> Docker
    Monitoring --> HTTP
    WSvc --> TelegramAPI
    Prom -->|logs| Loki
    Loki --> Graf
    Prom --> Graf

    %% Click Events
    click WebApp "https://github.com/spy4x/financy/tree/main/apps/web"
    click Main "https://github.com/spy4x/financy/blob/main/apps/web/src/main.tsx"
    click SW "https://github.com/spy4x/financy/blob/main/apps/web/public/sw.js"
    click Manifest "https://github.com/spy4x/financy/blob/main/apps/web/public/manifest.json"
    click Components "https://github.com/spy4x/financy/tree/main/apps/web/src/components"
    click Routes "https://github.com/spy4x/financy/tree/main/apps/web/src/routes"
    click State "https://github.com/spy4x/financy/tree/main/apps/web/src/state"
    click EventBusFE "https://github.com/spy4x/financy/blob/main/apps/web/src/services/eventBus.ts"
    click HTTP "https://github.com/spy4x/financy/blob/main/apps/api/routes/auth.ts"
    click HTTP "https://github.com/spy4x/financy/blob/main/apps/api/routes/currencies.ts"
    click WS "https://github.com/spy4x/financy/blob/main/apps/api/routes/websockets.ts"
    click WS "https://github.com/spy4x/financy/blob/main/apps/api/services/websockets.ts"
    click CmdBus "https://github.com/spy4x/financy/blob/main/apps/api/services/commandBus.ts"
    click CmdBus "https://github.com/spy4x/financy/blob/main/libs/shared/cqrs/command-bus.ts"
    click QueryBus "https://github.com/spy4x/financy/blob/main/apps/api/services/queryBus.ts"
    click QueryBus "https://github.com/spy4x/financy/blob/main/libs/shared/cqrs/query-bus.ts"
    click EventBusBE "https://github.com/spy4x/financy/blob/main/apps/api/services/eventBus.ts"
    click EventBusBE "https://github.com/spy4x/financy/blob/main/libs/shared/cqrs/event-bus.ts"
    click CmdHandlers "https://github.com/spy4x/financy/tree/main/apps/api/cqrs/command-handlers"
    click QueryHandlers "https://github.com/spy4x/financy/tree/main/apps/api/cqrs/query-handlers"
    click EventHandlers "https://github.com/spy4x/financy/tree/main/apps/api/cqrs/event-handlers"
    click AuthMW "https://github.com/spy4x/financy/blob/main/apps/api/middlewares/auth.ts"
    click LogMW "https://github.com/spy4x/financy/blob/main/apps/api/middlewares/log.ts"
    click AuthSvc "https://github.com/spy4x/financy/tree/main/apps/api/services/auth"
    click DBSvc "https://github.com/spy4x/financy/blob/main/apps/api/services/db.ts"
    click DBSvc "https://github.com/spy4x/financy/tree/main/libs/server/db/migrations"
    click CacheSvc "https://github.com/spy4x/financy/blob/main/apps/api/services/cache.ts"
    click CacheSvc "https://github.com/spy4x/financy/blob/main/libs/server/kv/+index.ts"
    click PushSvc "https://github.com/spy4x/financy/blob/main/apps/api/services/webPush.ts"
    click WSvc "https://github.com/spy4x/financy/tree/main/apps/api/services/telegram"
    click TelegramWorker "https://github.com/spy4x/financy/blob/main/apps/api/workers/telegram-polling.ts"
    click Docker "https://github.com/spy4x/financy/blob/main/infra/compose/compose.dev.yml"
    click Docker "https://github.com/spy4x/financy/blob/main/infra/compose/compose.prod.yml"
    click Docker "https://github.com/spy4x/financy/blob/main/infra/compose/compose.shared.yml"
    click Monitoring "https://github.com/spy4x/financy/blob/main/infra/configs/prometheus.yml"
    click Monitoring "https://github.com/spy4x/financy/blob/main/infra/configs/loki.yml"
    click Monitoring "https://github.com/spy4x/financy/blob/main/infra/configs/promtail.yml"
    click Nginx "https://github.com/spy4x/financy/tree/main/infra/scripts"
    click Monitoring "https://github.com/spy4x/financy/blob/main/docs/3.architecture.md"
    click Monitoring "https://github.com/spy4x/financy/blob/main/docs/6.infrastructure.md"

    %% Styles
    classDef user fill:#FFD580,stroke:#D48B00
    classDef browser fill:#FFF2CC,stroke:#D6C06E
    classDef frontend fill:#D5E8D4,stroke:#82B366
    classDef backend fill:#F8CECC,stroke:#B85450
    classDef cqrs fill:#E1D5E7,stroke:#9673A6
    classDef service fill:#DAE8FC,stroke:#6C8EBF
    classDef db fill:#FFE6CC,stroke:#D79B00
    classDef external fill:#E1E1E1,stroke:#999999
    classDef infra fill:#F5F5F5,stroke:#CCCCCC
```
