# woodysc8/richard-newport architecture

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

- Interactive diagram: https://gitdiagram.com/woodysc8/richard-newport
- Repository: https://github.com/woodysc8/richard-newport

## Overview

This is a single-user personal-finance dashboard with Plaid account linking and refresh, transaction classification and accounting, investment tracking, and an MCP/API surface. The main workflow is linking financial accounts, refreshing their data into Supabase, then calculating and presenting dashboard and financial-context results. The source excerpts show the dashboard calculations and several API-to-library calls; some Plaid endpoints and MCP implementation are indexed but not excerpted, so their internal relationships are left unconnected.

Main entry points: [`app/components/PlaidConnect.tsx`](https://github.com/woodysc8/richard-newport/blob/master/app/components/PlaidConnect.tsx) (Plaid Connect), [`lib/financialContext.ts`](https://github.com/woodysc8/richard-newport/blob/master/lib/financialContext.ts) (Financial Context Builder), [`app/api/accounting/audit/route.ts`](https://github.com/woodysc8/richard-newport/blob/master/app/api/accounting/audit/route.ts) (Accounting Audit API), [`app/api/plaid/refresh/route.ts`](https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/refresh/route.ts) (Refresh APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connect["Account Connections"]
  node_connect_ui["Plaid Connect<br/>[PlaidConnect.tsx]"]
  node_plaid_link["Link Token API<br/>[route.ts]"]
  node_plaid_exchange["Token Exchange API<br/>[route.ts]"]
  node_plaid_refresh_api["Refresh APIs<br/>[route.ts]"]
  node_plaid_repair["Account Repair API<br/>[route.ts]"]
  node_plaid_diagnostics["Plaid Diagnostics<br/>[route.ts]"]
end

subgraph group_data["Financial Data"]
  node_refresh["Plaid Refresh<br/>[plaidRefresh.ts]"]
end

subgraph group_logic["Finance Logic"]
  node_classification["Transaction Classifier"]
  node_accounting["Accounting Engine<br/>[accounting.ts]"]
  node_budget["Budget Logic<br/>[budget.ts]"]
  node_weekly["Weekly Spending<br/>[weeklySpending.ts]"]
  node_account_types["Account Types<br/>[dashboard.ts]"]
  node_view_model["Dashboard View Model"]
end

subgraph group_experience["Dashboard and APIs"]
  node_dashboard["Dashboard Page<br/>[page.tsx]"]
  node_audit["Accounting Audit API<br/>[route.ts]"]
  node_classify_api["Classification API<br/>[route.ts]"]
  node_financial_route["Financial Context API<br/>[route.ts]"]
  node_financial_context["Financial Context Builder"]
  node_mcp["MCP API<br/>[route.ts]"]
end

node_user(("User"))
node_plaid["Plaid"]
node_supabase[("Supabase")]

node_user -->|"views"| node_dashboard
node_dashboard -->|"reads"| node_supabase
node_dashboard -->|"builds view"| node_view_model
node_view_model -->|"computes totals"| node_accounting
node_view_model -->|"classifies accounts"| node_account_types
node_connect_ui -->|"offers linking"| node_user
node_connect_ui -->|"requests token"| node_plaid_link
node_connect_ui -.->|"exchanges token"| node_plaid_exchange
node_connect_ui -.->|"requests refresh"| node_plaid_refresh_api
node_plaid_link -.->|"creates link token"| node_plaid
node_plaid_exchange -.->|"exchanges token"| node_plaid
node_plaid_refresh_api -->|"invokes refresh"| node_refresh
node_plaid_refresh_api -.->|"reads status"| node_supabase
node_refresh -->|"fetches updates"| node_plaid
node_refresh -->|"writes records"| node_supabase
node_plaid_repair -.->|"repairs records"| node_supabase
node_plaid_diagnostics -.->|"checks institutions"| node_plaid
node_audit -->|"reads records"| node_supabase
node_audit -->|"classifies transactions"| node_classification
node_audit -.->|"computes accounting"| node_accounting
node_classify_api -->|"reads transactions"| node_supabase
node_classify_api -->|"classifies transactions"| node_classification
node_financial_route -->|"builds context"| node_financial_context
node_financial_context -->|"reads financial data"| node_supabase
node_financial_context -->|"summarizes accounts"| node_accounting
node_financial_context -->|"classifies accounts"| node_account_types
node_weekly -->|"uses classifications"| node_classification

click node_connect_ui "https://github.com/woodysc8/richard-newport/blob/master/app/components/PlaidConnect.tsx"
click node_plaid_link "https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/create-link-token/route.ts"
click node_plaid_exchange "https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/exchange-token/route.ts"
click node_plaid_refresh_api "https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/refresh/route.ts"
click node_plaid_repair "https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/repair-accounts/route.ts"
click node_plaid_diagnostics "https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/institutions-diagnostic/route.ts"
click node_refresh "https://github.com/woodysc8/richard-newport/blob/master/lib/plaidRefresh.ts"
click node_classification "https://github.com/woodysc8/richard-newport/blob/master/lib/classifyTransaction.ts"
click node_accounting "https://github.com/woodysc8/richard-newport/blob/master/lib/accounting.ts"
click node_budget "https://github.com/woodysc8/richard-newport/blob/master/lib/budget.ts"
click node_weekly "https://github.com/woodysc8/richard-newport/blob/master/lib/weeklySpending.ts"
click node_account_types "https://github.com/woodysc8/richard-newport/blob/master/lib/dashboard.ts"
click node_view_model "https://github.com/woodysc8/richard-newport/blob/master/lib/dashboardViewModel.ts"
click node_dashboard "https://github.com/woodysc8/richard-newport/blob/master/app/page.tsx"
click node_audit "https://github.com/woodysc8/richard-newport/blob/master/app/api/accounting/audit/route.ts"
click node_classify_api "https://github.com/woodysc8/richard-newport/blob/master/app/api/transactions/classify/route.ts"
click node_financial_route "https://github.com/woodysc8/richard-newport/blob/master/app/api/financial-context/route.ts"
click node_financial_context "https://github.com/woodysc8/richard-newport/blob/master/lib/financialContext.ts"
click node_mcp "https://github.com/woodysc8/richard-newport/blob/master/app/api/mcp/route.ts"

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_connect_ui,node_plaid_link,node_plaid_exchange,node_plaid_refresh_api,node_plaid_repair,node_plaid_diagnostics,node_user toneBlue
class node_refresh,node_supabase toneAmber
class node_classification,node_accounting,node_budget,node_weekly,node_account_types,node_view_model toneMint
class node_dashboard,node_audit,node_classify_api,node_financial_route,node_financial_context,node_mcp toneRose
class node_plaid toneIndigo
```

## Components

### Account Connections

- [Plaid Connect](https://github.com/woodysc8/richard-newport/blob/master/app/components/PlaidConnect.tsx): `app/components/PlaidConnect.tsx`
- [Link Token API](https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/create-link-token/route.ts): `app/api/plaid/create-link-token/route.ts`
- [Token Exchange API](https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/exchange-token/route.ts): `app/api/plaid/exchange-token/route.ts`
- [Refresh APIs](https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/refresh/route.ts): `app/api/plaid/refresh/route.ts`
- [Account Repair API](https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/repair-accounts/route.ts): `app/api/plaid/repair-accounts/route.ts`
- [Plaid Diagnostics](https://github.com/woodysc8/richard-newport/blob/master/app/api/plaid/institutions-diagnostic/route.ts): `app/api/plaid/institutions-diagnostic/route.ts`

### Financial Data

- [Plaid Refresh](https://github.com/woodysc8/richard-newport/blob/master/lib/plaidRefresh.ts): `lib/plaidRefresh.ts`

### Finance Logic

- [Transaction Classifier](https://github.com/woodysc8/richard-newport/blob/master/lib/classifyTransaction.ts): `lib/classifyTransaction.ts`
- [Accounting Engine](https://github.com/woodysc8/richard-newport/blob/master/lib/accounting.ts): `lib/accounting.ts`
- [Budget Logic](https://github.com/woodysc8/richard-newport/blob/master/lib/budget.ts): `lib/budget.ts`
- [Weekly Spending](https://github.com/woodysc8/richard-newport/blob/master/lib/weeklySpending.ts): `lib/weeklySpending.ts`
- [Account Types](https://github.com/woodysc8/richard-newport/blob/master/lib/dashboard.ts): `lib/dashboard.ts`
- [Dashboard View Model](https://github.com/woodysc8/richard-newport/blob/master/lib/dashboardViewModel.ts): `lib/dashboardViewModel.ts`

### Dashboard and APIs

- [Dashboard Page](https://github.com/woodysc8/richard-newport/blob/master/app/page.tsx): `app/page.tsx`
- [Accounting Audit API](https://github.com/woodysc8/richard-newport/blob/master/app/api/accounting/audit/route.ts): `app/api/accounting/audit/route.ts`
- [Classification API](https://github.com/woodysc8/richard-newport/blob/master/app/api/transactions/classify/route.ts): `app/api/transactions/classify/route.ts`
- [Financial Context API](https://github.com/woodysc8/richard-newport/blob/master/app/api/financial-context/route.ts): `app/api/financial-context/route.ts`
- [Financial Context Builder](https://github.com/woodysc8/richard-newport/blob/master/lib/financialContext.ts): `lib/financialContext.ts`
- [MCP API](https://github.com/woodysc8/richard-newport/blob/master/app/api/mcp/route.ts): `app/api/mcp/route.ts`

### Other components

- **User**
- **Plaid**
- **Supabase**

## Connections

- User → Dashboard Page: views (evidence: `app/page.tsx`)
- Dashboard Page → Supabase: reads (evidence: `app/page.tsx`)
- Dashboard Page → Dashboard View Model: builds view (evidence: `app/page.tsx`)
- Dashboard View Model → Accounting Engine: computes totals (evidence: `lib/dashboardViewModel.ts`)
- Dashboard View Model → Account Types: classifies accounts (evidence: `lib/dashboardViewModel.ts`)
- Plaid Connect → User: offers linking (evidence: `app/components/PlaidConnect.tsx`)
- Plaid Connect → Link Token API: requests token (evidence: `app/components/PlaidConnect.tsx`)
- Plaid Connect → Token Exchange API: exchanges token
- Plaid Connect → Refresh APIs: requests refresh
- Link Token API → Plaid: creates link token
- Token Exchange API → Plaid: exchanges token
- Refresh APIs → Plaid Refresh: invokes refresh (evidence: `app/api/plaid/refresh/route.ts`)
- Refresh APIs → Supabase: reads status
- Plaid Refresh → Plaid: fetches updates (evidence: `lib/plaidRefresh.ts`)
- Plaid Refresh → Supabase: writes records (evidence: `lib/plaidRefresh.ts`)
- Account Repair API → Supabase: repairs records
- Plaid Diagnostics → Plaid: checks institutions
- Accounting Audit API → Supabase: reads records (evidence: `app/api/accounting/audit/route.ts`)
- Accounting Audit API → Transaction Classifier: classifies transactions (evidence: `app/api/accounting/audit/route.ts`)
- Accounting Audit API → Accounting Engine: computes accounting (evidence: `app/api/accounting/audit/route.ts`)
- Classification API → Supabase: reads transactions (evidence: `app/api/transactions/classify/route.ts`)
- Classification API → Transaction Classifier: classifies transactions (evidence: `app/api/transactions/classify/route.ts`)
- Financial Context API → Financial Context Builder: builds context (evidence: `app/api/financial-context/route.ts`)
- Financial Context Builder → Supabase: reads financial data (evidence: `lib/financialContext.ts`)
- Financial Context Builder → Accounting Engine: summarizes accounts (evidence: `lib/financialContext.ts`)
- Financial Context Builder → Account Types: classifies accounts (evidence: `lib/financialContext.ts`)
- Weekly Spending → Transaction Classifier: uses classifications (evidence: `lib/weeklySpending.ts`)
