# kirithikji/pocketpulse architecture

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

- Interactive diagram: https://gitdiagram.com/kirithikji/pocketpulse
- Repository: https://github.com/kirithikji/pocketpulse

## Overview

PocketPulse is an installable personal-finance app for recording spending, understanding it, and saving toward goals. A typical workflow is sign-in and setup, then entering transactions (including queued offline entries), which feed balances, budgets, insights, reports, and rewards. The graph also preserves planning, recurring items, and the app’s Supabase-backed data layer. Edges are limited to relationships shown in the README or supplied source index/excerpts; unsampled routes and integrations are represented without guessed call chains.

Main entry points: [`src/app/api/sync/route.ts`](https://github.com/kirithikji/pocketpulse/blob/main/src/app/api/sync/route.ts) (Sync endpoint), [`src/lib/ledger/commands.ts`](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/ledger/commands.ts) (Ledger commands), [`src/domain/ledger.ts`](https://github.com/kirithikji/pocketpulse/blob/main/src/domain/ledger.ts) (Ledger rules), [`src/lib/data/queries/index.ts`](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/data/queries/index.ts) (Data queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and setup"]
  node_auth["Auth forms<br/>[auth-forms.tsx]"]
  node_authroute["Auth confirmation<br/>[route.ts]"]
  node_onboarding["Onboarding<br/>[page.tsx]"]
end

subgraph group_ledger["Entries and sync"]
  node_entryreview["Entry review<br/>[draft-review.tsx]"]
  node_ledgercmd["Ledger commands<br/>[commands.ts]"]
  node_syncroute["Sync endpoint<br/>[route.ts]"]
  node_offline["Offline queue<br/>[queue.ts]"]
  node_transactions["Transaction screens<br/>[page.tsx]"]
end

subgraph group_planning["Planning and rewards"]
  node_planning["Budgets and goals<br/>[page.tsx]"]
  node_recurring["Recurring items<br/>[page.tsx]"]
  node_rewards["Rewards engine<br/>[engine.ts]"]
end

subgraph group_analysis["Insights and reports"]
  node_home["Home dashboard<br/>[page.tsx]"]
  node_insights["Spending insights<br/>[page.tsx]"]
  node_reports["Reports and export<br/>[page.tsx]"]
end

subgraph group_foundation["Data and domain"]
  node_domainledger["Ledger rules<br/>[ledger.ts]"]
  node_aggregation["Financial aggregation<br/>[aggregation.ts]"]
  node_money["Money utilities<br/>[money.ts]"]
  node_queries["Data queries<br/>[index.ts]"]
  node_session["User session<br/>[session.ts]"]
  node_rewarddomain["Reward calculations<br/>[rewards.ts]"]
  node_feedback["User feedback<br/>[toast.tsx]"]
end

node_user(("Finance user"))
node_supabase[("Supabase")]

node_user -->|"signs in"| node_auth
node_auth -->|"confirms email"| node_authroute
node_user -->|"sets up finances"| node_onboarding
node_onboarding -->|"loads setup data"| node_queries
node_user -->|"reviews entries"| node_entryreview
node_entryreview -->|"submits commands"| node_ledgercmd
node_user -->|"manages entries"| node_transactions
node_offline -->|"sends queued operations"| node_syncroute
node_syncroute -->|"verifies session"| node_session
node_syncroute -->|"validates commands"| node_ledgercmd
node_syncroute -->|"syncs rewards"| node_rewards
node_session -->|"creates scoped client"| node_supabase
node_queries -->|"uses session"| node_session
node_ledgercmd -->|"uses ledger rules"| node_domainledger
node_domainledger -->|"uses money functions"| node_money
node_aggregation -->|"uses ledger functions"| node_domainledger
node_user -->|"views summary"| node_home
node_home -->|"loads finance data"| node_queries
node_user -->|"plans spending"| node_planning
node_user -->|"manages recurring items"| node_recurring
node_user -->|"explores spending"| node_insights
node_user -->|"views and exports"| node_reports
node_rewards -->|"calculates awards"| node_rewarddomain
node_user -->|"receives notices"| node_feedback

click node_auth "https://github.com/kirithikji/pocketpulse/blob/main/src/components/auth/auth-forms.tsx"
click node_authroute "https://github.com/kirithikji/pocketpulse/blob/main/src/app/auth/confirm/route.ts"
click node_onboarding "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(public)/onboarding/page.tsx"
click node_home "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/home/page.tsx"
click node_entryreview "https://github.com/kirithikji/pocketpulse/blob/main/src/components/transactions/draft-review.tsx"
click node_ledgercmd "https://github.com/kirithikji/pocketpulse/blob/main/src/lib/ledger/commands.ts"
click node_syncroute "https://github.com/kirithikji/pocketpulse/blob/main/src/app/api/sync/route.ts"
click node_offline "https://github.com/kirithikji/pocketpulse/blob/main/src/lib/offline/queue.ts"
click node_transactions "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/transactions/page.tsx"
click node_domainledger "https://github.com/kirithikji/pocketpulse/blob/main/src/domain/ledger.ts"
click node_aggregation "https://github.com/kirithikji/pocketpulse/blob/main/src/domain/aggregation.ts"
click node_money "https://github.com/kirithikji/pocketpulse/blob/main/src/domain/money.ts"
click node_queries "https://github.com/kirithikji/pocketpulse/blob/main/src/lib/data/queries/index.ts"
click node_session "https://github.com/kirithikji/pocketpulse/blob/main/src/lib/data/session.ts"
click node_planning "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/budgets/page.tsx"
click node_recurring "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/recurring/page.tsx"
click node_insights "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/insights/page.tsx"
click node_reports "https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/reports/page.tsx"
click node_rewards "https://github.com/kirithikji/pocketpulse/blob/main/src/lib/rewards/engine.ts"
click node_rewarddomain "https://github.com/kirithikji/pocketpulse/blob/main/src/domain/rewards.ts"
click node_feedback "https://github.com/kirithikji/pocketpulse/blob/main/src/components/feedback/toast.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_authroute,node_onboarding,node_user toneBlue
class node_entryreview,node_ledgercmd,node_syncroute,node_offline,node_transactions,node_supabase toneAmber
class node_planning,node_recurring,node_rewards toneMint
class node_home,node_insights,node_reports toneRose
class node_domainledger,node_aggregation,node_money,node_queries,node_session,node_rewarddomain,node_feedback toneIndigo
```

## Components

### Access and setup

- [Auth forms](https://github.com/kirithikji/pocketpulse/blob/main/src/components/auth/auth-forms.tsx): `src/components/auth/auth-forms.tsx`
- [Auth confirmation](https://github.com/kirithikji/pocketpulse/blob/main/src/app/auth/confirm/route.ts): `src/app/auth/confirm/route.ts`
- [Onboarding](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(public)/onboarding/page.tsx): `src/app/(public)/onboarding/page.tsx`

### Entries and sync

- [Entry review](https://github.com/kirithikji/pocketpulse/blob/main/src/components/transactions/draft-review.tsx): `src/components/transactions/draft-review.tsx`
- [Ledger commands](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/ledger/commands.ts): `src/lib/ledger/commands.ts`
- [Sync endpoint](https://github.com/kirithikji/pocketpulse/blob/main/src/app/api/sync/route.ts): `src/app/api/sync/route.ts`
- [Offline queue](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/offline/queue.ts): `src/lib/offline/queue.ts`
- [Transaction screens](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/transactions/page.tsx): `src/app/(app)/(main)/transactions/page.tsx`

### Planning and rewards

- [Budgets and goals](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/budgets/page.tsx): `src/app/(app)/(main)/budgets/page.tsx`
- [Recurring items](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/recurring/page.tsx): `src/app/(app)/(main)/recurring/page.tsx`
- [Rewards engine](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/rewards/engine.ts): `src/lib/rewards/engine.ts`

### Insights and reports

- [Home dashboard](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/home/page.tsx): `src/app/(app)/(main)/home/page.tsx`
- [Spending insights](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/insights/page.tsx): `src/app/(app)/(main)/insights/page.tsx`
- [Reports and export](https://github.com/kirithikji/pocketpulse/blob/main/src/app/(app)/(main)/reports/page.tsx): `src/app/(app)/(main)/reports/page.tsx`

### Data and domain

- [Ledger rules](https://github.com/kirithikji/pocketpulse/blob/main/src/domain/ledger.ts): `src/domain/ledger.ts`
- [Financial aggregation](https://github.com/kirithikji/pocketpulse/blob/main/src/domain/aggregation.ts): `src/domain/aggregation.ts`
- [Money utilities](https://github.com/kirithikji/pocketpulse/blob/main/src/domain/money.ts): `src/domain/money.ts`
- [Data queries](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/data/queries/index.ts): `src/lib/data/queries/index.ts`
- [User session](https://github.com/kirithikji/pocketpulse/blob/main/src/lib/data/session.ts): `src/lib/data/session.ts`
- [Reward calculations](https://github.com/kirithikji/pocketpulse/blob/main/src/domain/rewards.ts): `src/domain/rewards.ts`
- [User feedback](https://github.com/kirithikji/pocketpulse/blob/main/src/components/feedback/toast.tsx): `src/components/feedback/toast.tsx`

### Other components

- **Finance user**
- **Supabase**

## Connections

- Finance user → Auth forms: signs in
- Auth forms → Auth confirmation: confirms email
- Finance user → Onboarding: sets up finances (evidence: `src/app/(public)/onboarding/page.tsx`)
- Onboarding → Data queries: loads setup data (evidence: `src/app/(public)/onboarding/page.tsx`)
- Finance user → Entry review: reviews entries (evidence: `src/components/transactions/draft-review.tsx`)
- Entry review → Ledger commands: submits commands (evidence: `src/components/transactions/draft-review.tsx`)
- Finance user → Transaction screens: manages entries
- Offline queue → Sync endpoint: sends queued operations (evidence: `src/app/api/sync/route.ts`)
- Sync endpoint → User session: verifies session (evidence: `src/app/api/sync/route.ts`)
- Sync endpoint → Ledger commands: validates commands (evidence: `src/app/api/sync/route.ts`)
- Sync endpoint → Rewards engine: syncs rewards (evidence: `src/app/api/sync/route.ts`)
- User session → Supabase: creates scoped client (evidence: `src/lib/data/session.ts`)
- Data queries → User session: uses session (evidence: `src/lib/data/session.ts`)
- Ledger commands → Ledger rules: uses ledger rules (evidence: `src/lib/ledger/commands.ts`)
- Ledger rules → Money utilities: uses money functions (evidence: `src/domain/ledger.ts`)
- Financial aggregation → Ledger rules: uses ledger functions (evidence: `src/domain/aggregation.ts`)
- Finance user → Home dashboard: views summary (evidence: `src/app/(app)/(main)/home/page.tsx`)
- Home dashboard → Data queries: loads finance data (evidence: `src/app/(app)/(main)/home/page.tsx`)
- Finance user → Budgets and goals: plans spending
- Finance user → Recurring items: manages recurring items (evidence: `src/app/(app)/(main)/recurring/page.tsx`)
- Finance user → Spending insights: explores spending
- Finance user → Reports and export: views and exports (evidence: `src/app/(app)/(main)/reports/page.tsx`)
- Rewards engine → Reward calculations: calculates awards (evidence: `src/lib/rewards/engine.ts`)
- Finance user → User feedback: receives notices