# matheusaaguirra/wealthos architecture

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

- Interactive diagram: https://gitdiagram.com/matheusaaguirra/wealthos
- Repository: https://github.com/matheusaaguirra/wealthos

## Overview

WealthOS is a personal-finance application: users sign in, organize accounts and transactions, manage recurring expenses, and review their financial overview and investments. The current product combines an Angular finance interface with Next.js public pages and server APIs, using Supabase for identity and PostgreSQL-backed financial data. Public guides and multilingual landing pages are a separate product-facing branch. The README identifies the preserved NestJS/Prisma code as historical, so it is omitted. Some API and client wiring is unsampled; edges are limited to shown references or documented relationships.

Main entry points: [`app/api/finance/route.ts`](https://github.com/matheusaaguirra/wealthos/blob/main/app/api/finance/route.ts) (Finance API), [`app/api/market`](https://github.com/matheusaaguirra/wealthos/tree/main/app/api/market) (Market endpoints), [`wealthos-source/apps/web/src/app.component.ts`](https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/app.component.ts) (Finance interface), [`components/wealthos-guides.tsx`](https://github.com/matheusaaguirra/wealthos/blob/main/components/wealthos-guides.tsx) (Guides)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public experience"]
  node_landing["Landing pages"]
  node_localized["Localized content"]
  node_guides["Guides"]
  node_guidecontent["Guide content<br/>[content.ts]"]
  node_planner["Monthly planner"]
  node_seo["SEO metadata<br/>[seo.ts]"]
end

subgraph group_client["Finance application"]
  node_financeui["Finance interface<br/>[app.component.ts]"]
  node_localization["App localization<br/>[language.ts]"]
  node_pdf["Transaction reports"]
end

subgraph group_server["Server and data"]
  node_financeapi["Finance API<br/>[route.ts]"]
  node_authcore["Auth core<br/>[auth-core.ts]"]
  node_supabaseserver["Supabase server auth<br/>[server.ts]"]
  node_financialstate["Financial state<br/>[financial-state.ts]"]
  node_financestore["Financial store<br/>[finance.ts]"]
  node_recurring["Recurring posting"]
  node_financialdb[("Supabase PostgreSQL")]
end

subgraph group_market["Market data"]
  node_marketapi["Market endpoints"]
  node_marketlogic["Market normalization<br/>[market.ts]"]
  node_marketcache[("Market cache<br/>[market-cache.ts]")]
  node_googlefinance["Google Finance adapter<br/>[google-finance.ts]"]
end

node_visitor(("Visitor or user"))
node_marketproviders(("Market data providers"))

node_visitor -->|"browses"| node_landing
node_visitor -->|"uses"| node_financeui
node_landing -->|"uses metadata"| node_seo
node_localized -->|"uses metadata"| node_seo
node_visitor -->|"reads"| node_guides
node_guides -->|"loads"| node_guidecontent
node_guides -->|"renders"| node_planner
node_financeui -->|"uses"| node_localization
node_financeui -->|"uses"| node_pdf
node_financeui -->|"uses APIs"| node_financeapi
node_financeapi -->|"authenticates"| node_supabaseserver
node_financeapi -->|"validates request"| node_financialstate
node_financeapi -->|"reads and saves"| node_financestore
node_financeapi -->|"posts due items"| node_recurring
node_supabaseserver -->|"uses errors"| node_authcore
node_financialstate -->|"uses"| node_authcore
node_financialstate -.->|"persists user data"| node_financialdb
node_financestore -.->|"reads and writes"| node_financialdb
node_marketapi -->|"validates and normalizes"| node_marketlogic
node_marketapi -->|"caches responses"| node_marketcache
node_marketapi -->|"fetches quotes"| node_googlefinance
node_marketapi -.->|"requests data"| node_marketproviders

click node_landing "https://github.com/matheusaaguirra/wealthos/blob/main/components/wealthos-landing.tsx"
click node_localized "https://github.com/matheusaaguirra/wealthos/blob/main/components/international-landing.tsx"
click node_guides "https://github.com/matheusaaguirra/wealthos/blob/main/components/wealthos-guides.tsx"
click node_guidecontent "https://github.com/matheusaaguirra/wealthos/blob/main/lib/guides/content.ts"
click node_planner "https://github.com/matheusaaguirra/wealthos/blob/main/components/monthly-planner.tsx"
click node_seo "https://github.com/matheusaaguirra/wealthos/blob/main/lib/seo.ts"
click node_financeui "https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/app.component.ts"
click node_localization "https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/i18n/language.ts"
click node_pdf "https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/transactions-pdf.ts"
click node_financeapi "https://github.com/matheusaaguirra/wealthos/blob/main/app/api/finance/route.ts"
click node_authcore "https://github.com/matheusaaguirra/wealthos/blob/main/lib/auth-core.ts"
click node_supabaseserver "https://github.com/matheusaaguirra/wealthos/blob/main/lib/supabase/server.ts"
click node_financialstate "https://github.com/matheusaaguirra/wealthos/blob/main/lib/financial-state.ts"
click node_financestore "https://github.com/matheusaaguirra/wealthos/blob/main/lib/supabase/finance.ts"
click node_recurring "https://github.com/matheusaaguirra/wealthos/blob/main/lib/recurring-posting.ts"
click node_marketapi "https://github.com/matheusaaguirra/wealthos/tree/main/app/api/market"
click node_marketlogic "https://github.com/matheusaaguirra/wealthos/blob/main/lib/market.ts"
click node_marketcache "https://github.com/matheusaaguirra/wealthos/blob/main/lib/market-cache.ts"
click node_googlefinance "https://github.com/matheusaaguirra/wealthos/blob/main/lib/google-finance.ts"
click node_financialdb "https://github.com/matheusaaguirra/wealthos/tree/main/db"

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_landing,node_localized,node_guides,node_guidecontent,node_planner,node_seo,node_visitor toneBlue
class node_financeui,node_localization,node_pdf toneAmber
class node_financeapi,node_authcore,node_supabaseserver,node_financialstate,node_financestore,node_recurring,node_financialdb toneMint
class node_marketapi,node_marketlogic,node_marketcache,node_googlefinance toneRose
class node_marketproviders toneIndigo
```

## Components

### Public experience

- [Landing pages](https://github.com/matheusaaguirra/wealthos/blob/main/components/wealthos-landing.tsx): `components/wealthos-landing.tsx`
- [Localized content](https://github.com/matheusaaguirra/wealthos/blob/main/components/international-landing.tsx): `components/international-landing.tsx`
- [Guides](https://github.com/matheusaaguirra/wealthos/blob/main/components/wealthos-guides.tsx): `components/wealthos-guides.tsx`
- [Guide content](https://github.com/matheusaaguirra/wealthos/blob/main/lib/guides/content.ts): `lib/guides/content.ts`
- [Monthly planner](https://github.com/matheusaaguirra/wealthos/blob/main/components/monthly-planner.tsx): `components/monthly-planner.tsx`
- [SEO metadata](https://github.com/matheusaaguirra/wealthos/blob/main/lib/seo.ts): `lib/seo.ts`

### Finance application

- [Finance interface](https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/app.component.ts): `wealthos-source/apps/web/src/app.component.ts`
- [App localization](https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/i18n/language.ts): `wealthos-source/apps/web/src/i18n/language.ts`
- [Transaction reports](https://github.com/matheusaaguirra/wealthos/blob/main/wealthos-source/apps/web/src/transactions-pdf.ts): `wealthos-source/apps/web/src/transactions-pdf.ts`

### Server and data

- [Finance API](https://github.com/matheusaaguirra/wealthos/blob/main/app/api/finance/route.ts): `app/api/finance/route.ts`
- [Auth core](https://github.com/matheusaaguirra/wealthos/blob/main/lib/auth-core.ts): `lib/auth-core.ts`
- [Supabase server auth](https://github.com/matheusaaguirra/wealthos/blob/main/lib/supabase/server.ts): `lib/supabase/server.ts`
- [Financial state](https://github.com/matheusaaguirra/wealthos/blob/main/lib/financial-state.ts): `lib/financial-state.ts`
- [Financial store](https://github.com/matheusaaguirra/wealthos/blob/main/lib/supabase/finance.ts): `lib/supabase/finance.ts`
- [Recurring posting](https://github.com/matheusaaguirra/wealthos/blob/main/lib/recurring-posting.ts): `lib/recurring-posting.ts`
- [Supabase PostgreSQL](https://github.com/matheusaaguirra/wealthos/tree/main/db): `db`

### Market data

- [Market endpoints](https://github.com/matheusaaguirra/wealthos/tree/main/app/api/market): `app/api/market`
- [Market normalization](https://github.com/matheusaaguirra/wealthos/blob/main/lib/market.ts): `lib/market.ts`
- [Market cache](https://github.com/matheusaaguirra/wealthos/blob/main/lib/market-cache.ts): `lib/market-cache.ts`
- [Google Finance adapter](https://github.com/matheusaaguirra/wealthos/blob/main/lib/google-finance.ts): `lib/google-finance.ts`

### Other components

- **Visitor or user**
- **Market data providers**

## Connections

- Visitor or user → Landing pages: browses (evidence: `README.md`)
- Visitor or user → Finance interface: uses (evidence: `README.md`)
- Landing pages → SEO metadata: uses metadata (evidence: `app/(pt)/page.tsx`)
- Localized content → SEO metadata: uses metadata (evidence: `app/(en)/en/page.tsx`)
- Visitor or user → Guides: reads (evidence: `README.md`)
- Guides → Guide content: loads (evidence: `components/wealthos-guides.tsx`)
- Guides → Monthly planner: renders (evidence: `components/wealthos-guides.tsx`)
- Finance interface → App localization: uses (evidence: `wealthos-source/apps/web/src/app.component.ts`)
- Finance interface → Transaction reports: uses (evidence: `wealthos-source/apps/web/src/app.component.ts`)
- Finance interface → Finance API: uses APIs (evidence: `README.md`)
- Finance API → Supabase server auth: authenticates (evidence: `app/api/finance/route.ts`)
- Finance API → Financial state: validates request (evidence: `app/api/finance/route.ts`)
- Finance API → Financial store: reads and saves (evidence: `app/api/finance/route.ts`)
- Finance API → Recurring posting: posts due items (evidence: `app/api/finance/route.ts`)
- Supabase server auth → Auth core: uses errors (evidence: `lib/supabase/server.ts`)
- Financial state → Auth core: uses (evidence: `lib/financial-state.ts`)
- Financial state → Supabase PostgreSQL: persists user data
- Financial store → Supabase PostgreSQL: reads and writes
- Market endpoints → Market normalization: validates and normalizes (evidence: `app/api/market/google-finance/route.ts`)
- Market endpoints → Market cache: caches responses (evidence: `app/api/market/google-finance/route.ts`)
- Market endpoints → Google Finance adapter: fetches quotes (evidence: `app/api/market/google-finance/route.ts`)
- Market endpoints → Market data providers: requests data