# ananthakumaran/paisa architecture

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

- Interactive diagram: https://gitdiagram.com/ananthakumaran/paisa
- Repository: https://github.com/ananthakumaran/paisa

## Overview

##### Project Type and Purpose
- Paisa is a full-stack personal finance manager written in Go (core/business logic & servers) plus SvelteKit/TypeScript (web & desktop UIs).
- It exposes three “faces”:
– CLI commands (`cmd/`)
– Desktop GUI via Wails (`desktop/`)
– Web UI via SvelteKit (`src/` + `web/web.go`)
- All three reuse the same monolithic core in `internal/` (ledger parsing, accounting, caching, scrapers, services, taxation, XIRR).

##### File‐Structure Analysis
- Top‐level entrypoints
– `cmd/` – CLI commands: init, serve, update, version
– `desktop/` – Wails-powered desktop app (`app.go`, `main.go`, plus embedded frontend runtime)
– `src/` + `web/web.go` – SvelteKit web frontend + Go static-asset server
- Core logic (`internal/`)
– `internal/server/` – HTTP handlers & router for JSON API
– `internal/model/`, `internal/ledger/`, `internal/accounting/`, `internal/config/`, `internal/cache/`, etc.
– `internal/scraper/` – external data fetchers (mutual funds, NPS, stocks)
- Supporting files: Dockerfiles, Makefile, fixtures/tests, docs, brand assets

##### Key README Insights
- “Builds on top of ledger CLI” – the core sometimes shells out to the `ledger` binary
- Provides demo URL, open-source under AGPL

a. Main Components
1. User Interfaces
- CLI (Go `cmd/`)
- Desktop App (Wails: Go ↔ Svelte runtime)
- Web App (SvelteKit + Go server)
2. API Layer
- HTTP JSON API (`internal/server/`) – consumed by web & desktop
3. Core Business Logic
- Configuration & schema (`internal/config/`)
- Ledger parsing & command integration (`internal/ledger/`, external `ledger` binary)
- Accounting domain (`internal/accounting/`, `internal/model/`)
- Prediction, XIRR, taxation, services (`internal/prediction/`, `internal/xirr/`, `internal/service/`, `internal/taxation/`)
- Scrapers (`internal/scraper/`)
- Cache layer (`internal/cache/`)
4. External Dependencies
- Ledger-CLI binary
- Third-party data sources (APIs, HTML endpoints for mutual funds, stock quotes)

b. Relationships & Data Flows
– CLI commands call core logic directly (Go function calls + occasional ledger-CLI subprocess).
– Desktop UI→Wails runtime→Go bindings→core logic→returns JSON/structs→UI.
– Web UI→HTTP JSON API (internal/server)→core logic→data→JSON response.
– Core logic may call ledger-CLI, scrapers, read/write local files (ledgers, caches).

c. Architectural Patterns & Principles
– Layered Monolith: clear separation between UI, API/controller (`internal/server`), domain/services (`internal/*`), infrastructure (filesystem, subprocess, HTTP fetch)
– Reuse of core business logic across multiple front-ends
– Single codebase, multi-target build (CLI, desktop, web, Docker)

d. Key Technologies & Frameworks
– Go (backend, CLI, API, desktop glue)
– SvelteKit & Vite (web frontend)
– Wails (desktop wrapper)
– Ledger-CLI external tool
– Docker / Nix for reproducible builds

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interfaces"
        CLI["CLI Commands"]:::frontend
        DesktopApp["Wails Desktop App"]:::frontend
        WebUI["SvelteKit Web UI"]:::frontend
        AssetServer["Go Asset Server"]:::api
    end

    %% API Layer
    subgraph "HTTP JSON API"
        API["HTTP JSON API"]:::api
    end

    %% Core Logic
    subgraph "Core Business Logic"
        config["Configuration & Schema"]:::core
        ledger["Ledger Parsing & Integration"]:::core
        accounting["Accounting Domain Logic"]:::core
        model["Data Models & Templates"]:::core
        cache["Caching Layer"]:::core
        scraper["Scrapers (External Data Fetchers)"]:::core
        prediction["Prediction Engine"]:::core
        xirr["XIRR Calculation Service"]:::core
        taxation["Taxation Service"]:::core
        services["Other Domain Services"]:::core
        binary["Embedded Ledger Binary Helper"]:::core
    end

    %% External Dependencies
    subgraph "External Systems"
        LedgerBinary["Ledger-CLI Binary"]:::external
        DataSources["Third-Party Data Sources"]:::external
    end

    %% Connections
    CLI -->|"Go Function Calls"| ledger
    CLI -->|"Go Function Calls"| accounting
    CLI -->|"Go Function Calls"| services

    DesktopApp -->|"Go Bindings/JSON"| ledger
    DesktopApp -->|"Go Bindings/JSON"| accounting
    DesktopApp -->|"Go Bindings/JSON"| services

    WebUI -->|"HTTP/JSON"| API
    AssetServer -->|"Serves Static Assets"| WebUI
    API -->|"Calls Core Logic"| ledger
    API -->|"Calls Core Logic"| accounting
    API -->|"Calls Core Logic"| services

    ledger -->|"Subprocess Execution"| LedgerBinary
    scraper -->|"HTTP Fetch"| DataSources
    scraper -->|"Feeds Data"| cache
    cache -->|"Serves Data"| accounting
    accounting -->|"Uses Models"| model
    prediction -->|"Uses Cache & Models"| cache
    xirr -->|"Calculation on Models"| model
    taxation -->|"Calculation Service"| model
    services -->|"Orchestrates Domain Logic"| accounting

    %% Click Events
    click CLI "https://github.com/ananthakumaran/paisa/tree/master/cmd/"
    click DesktopApp "https://github.com/ananthakumaran/paisa/tree/master/desktop/"
    click WebUI "https://github.com/ananthakumaran/paisa/tree/master/src/"
    click AssetServer "https://github.com/ananthakumaran/paisa/blob/master/web/web.go"
    click API "https://github.com/ananthakumaran/paisa/tree/master/internal/server/"
    click config "https://github.com/ananthakumaran/paisa/tree/master/internal/config/"
    click ledger "https://github.com/ananthakumaran/paisa/tree/master/internal/ledger/"
    click accounting "https://github.com/ananthakumaran/paisa/tree/master/internal/accounting/"
    click model "https://github.com/ananthakumaran/paisa/tree/master/internal/model/"
    click cache "https://github.com/ananthakumaran/paisa/tree/master/internal/cache/"
    click scraper "https://github.com/ananthakumaran/paisa/tree/master/internal/scraper/"
    click prediction "https://github.com/ananthakumaran/paisa/tree/master/internal/prediction/"
    click xirr "https://github.com/ananthakumaran/paisa/tree/master/internal/xirr/"
    click taxation "https://github.com/ananthakumaran/paisa/tree/master/internal/taxation/"
    click services "https://github.com/ananthakumaran/paisa/tree/master/internal/service/"
    click binary "https://github.com/ananthakumaran/paisa/tree/master/internal/binary/"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1
    classDef api fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef core fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64
```
