# pedroluizzampar/poup. architecture

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

- Interactive diagram: https://gitdiagram.com/pedroluizzampar/poup.
- Repository: https://github.com/pedroluizzampar/poup.

## Overview

Poup is a personal-finance PWA: a user signs in, connects a bank through Pluggy, reviews imported transactions and category suggestions, then explores spending, budgets, goals and reports; a household can share that financial view. The web app calls the Express API, whose scoped domain routes operate on PostgreSQL via Prisma. The README documents Open Finance, shared household finances and installable PWA behavior; several feature services are represented by their exact tree paths because their source was not excerpted, so only documented or indexed relationships are shown.

Main entry points: [`apps/api/src/prisma.ts`](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/prisma.ts) (PostgreSQL), [`apps/api/src/app.ts`](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/app.ts) (Express API), [`apps/web/src/lib/api.ts`](https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/lib/api.ts) (API client), [`apps/api/src/modules/auth/auth.service.ts`](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/auth/auth.service.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Finance PWA"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_review["Suggestion review<br/>[ReviewPage.tsx]"]
end

subgraph group_api["API and identity"]
  node_apiapp["Express API<br/>[app.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_scope["Request scope<br/>[scope.ts]"]
  node_authmw["Authentication middleware<br/>[requireAuth.ts]"]
  node_scopemw["Scope middleware<br/>[withScope.ts]"]
end

subgraph group_finance["Finance operations"]
  node_transactions["Transaction management"]
  node_transactionroutes["Transaction routes"]
  node_categorize["Categorization engine<br/>[engine.ts]"]
  node_suggestions["Suggestion workflow"]
  node_categories["Categories"]
  node_budgets["Budgets<br/>[budgets.service.ts]"]
  node_goals["Savings goals<br/>[goals.service.ts]"]
  node_reports["Reports<br/>[reports.service.ts]"]
  node_household["Shared household"]
end

subgraph group_sync["Bank sync"]
  node_pluggyroutes["Bank connection routes<br/>[pluggy.routes.ts]"]
  node_pluggy["Pluggy integration<br/>[pluggy.service.ts]"]
  node_pluggyservice["Pluggy client<br/>[pluggy.ts]"]
  node_webhook["Bank webhooks<br/>[webhook.routes.ts]"]
end

subgraph group_data["Persistence"]
  node_database[("PostgreSQL<br/>[prisma.ts]")]
  node_sharedtypes["Shared contracts<br/>[index.ts]"]
end

node_person(("Finance user"))
node_pluggyext{{"Pluggy Open Finance"}}

node_person -->|"uses"| node_webapp
node_webapp -->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_apiapp
node_apiapp -->|"mounts routes"| node_authroutes
node_apiapp -->|"mounts routes"| node_transactionroutes
node_apiapp -->|"mounts routes"| node_pluggyroutes
node_authroutes -->|"calls"| node_auth
node_authmw -->|"guards routes"| node_authroutes
node_scopemw -->|"resolves scope"| node_scope
node_authmw -->|"verifies token"| node_auth
node_transactionroutes -->|"calls"| node_transactions
node_transactionroutes -->|"bulk categorizes"| node_suggestions
node_review -->|"loads and applies"| node_webapi
node_webapi -->|"uses contracts"| node_sharedtypes
node_auth -->|"reads and writes"| node_database
node_transactions -.->|"persists records"| node_database
node_pluggyroutes -->|"calls"| node_pluggy
node_pluggy -.->|"uses client"| node_pluggyservice
node_pluggyservice -.->|"connects to"| node_pluggyext
node_webhook -->|"dispatches events"| node_pluggy
node_pluggy -.->|"stores sync data"| node_database
node_auth -->|"loads household"| node_household
node_categories -.->|"persists categories"| node_database
node_budgets -.->|"persists limits"| node_database
node_goals -.->|"persists goals"| node_database
node_reports -.->|"queries finances"| node_database
node_household -->|"persists membership"| node_database
node_suggestions -.->|"uses engine"| node_categorize

click node_webapp "https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/App.tsx"
click node_webapi "https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/lib/api.ts"
click node_review "https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/pages/ReviewPage.tsx"
click node_apiapp "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_authroutes "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/auth/auth.routes.ts"
click node_scope "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/lib/scope.ts"
click node_authmw "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/middleware/requireAuth.ts"
click node_scopemw "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/middleware/withScope.ts"
click node_transactions "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/transactions/transactions.service.ts"
click node_transactionroutes "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/transactions/transactions.routes.ts"
click node_categorize "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/lib/categorization/engine.ts"
click node_suggestions "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/categorization/suggestions.service.ts"
click node_categories "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/categories/categories.service.ts"
click node_budgets "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/budgets/budgets.service.ts"
click node_goals "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/goals/goals.service.ts"
click node_reports "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/reports/reports.service.ts"
click node_household "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/household/household.service.ts"
click node_pluggyroutes "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/pluggy/pluggy.routes.ts"
click node_pluggy "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/pluggy/pluggy.service.ts"
click node_pluggyservice "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/lib/pluggy.ts"
click node_webhook "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/pluggy/webhook.routes.ts"
click node_database "https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/prisma.ts"
click node_sharedtypes "https://github.com/pedroluizzampar/poup./blob/main/packages/shared/src/index.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_webapp,node_webapi,node_review,node_person toneBlue
class node_apiapp,node_auth,node_authroutes,node_scope,node_authmw,node_scopemw toneAmber
class node_transactions,node_transactionroutes,node_categorize,node_suggestions,node_categories,node_budgets,node_goals,node_reports,node_household toneMint
class node_pluggyroutes,node_pluggy,node_pluggyservice,node_webhook toneRose
class node_database,node_sharedtypes,node_pluggyext toneIndigo
```

## Components

### Finance PWA

- [Web application](https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Suggestion review](https://github.com/pedroluizzampar/poup./blob/main/apps/web/src/pages/ReviewPage.tsx): `apps/web/src/pages/ReviewPage.tsx`

### API and identity

- [Express API](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Auth routes](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/auth/auth.routes.ts): `apps/api/src/modules/auth/auth.routes.ts`
- [Request scope](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/lib/scope.ts): `apps/api/src/lib/scope.ts`
- [Authentication middleware](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/middleware/requireAuth.ts): `apps/api/src/middleware/requireAuth.ts`
- [Scope middleware](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/middleware/withScope.ts): `apps/api/src/middleware/withScope.ts`

### Finance operations

- [Transaction management](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/transactions/transactions.service.ts): `apps/api/src/modules/transactions/transactions.service.ts`
- [Transaction routes](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/transactions/transactions.routes.ts): `apps/api/src/modules/transactions/transactions.routes.ts`
- [Categorization engine](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/lib/categorization/engine.ts): `apps/api/src/lib/categorization/engine.ts`
- [Suggestion workflow](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/categorization/suggestions.service.ts): `apps/api/src/modules/categorization/suggestions.service.ts`
- [Categories](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/categories/categories.service.ts): `apps/api/src/modules/categories/categories.service.ts`
- [Budgets](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/budgets/budgets.service.ts): `apps/api/src/modules/budgets/budgets.service.ts`
- [Savings goals](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/goals/goals.service.ts): `apps/api/src/modules/goals/goals.service.ts`
- [Reports](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/reports/reports.service.ts): `apps/api/src/modules/reports/reports.service.ts`
- [Shared household](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/household/household.service.ts): `apps/api/src/modules/household/household.service.ts`

### Bank sync

- [Bank connection routes](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/pluggy/pluggy.routes.ts): `apps/api/src/modules/pluggy/pluggy.routes.ts`
- [Pluggy integration](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/pluggy/pluggy.service.ts): `apps/api/src/modules/pluggy/pluggy.service.ts`
- [Pluggy client](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/lib/pluggy.ts): `apps/api/src/lib/pluggy.ts`
- [Bank webhooks](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/modules/pluggy/webhook.routes.ts): `apps/api/src/modules/pluggy/webhook.routes.ts`

### Persistence

- [PostgreSQL](https://github.com/pedroluizzampar/poup./blob/main/apps/api/src/prisma.ts): `apps/api/src/prisma.ts`
- [Shared contracts](https://github.com/pedroluizzampar/poup./blob/main/packages/shared/src/index.ts): `packages/shared/src/index.ts`

### Other components

- **Finance user**
- **Pluggy Open Finance**

## Connections

- Finance user → Web application: uses
- Web application → API client: requests data (evidence: `apps/web/src/App.tsx`)
- API client → Express API: calls API
- Express API → Auth routes: mounts routes (evidence: `apps/api/src/app.ts`)
- Express API → Transaction routes: mounts routes (evidence: `apps/api/src/app.ts`)
- Express API → Bank connection routes: mounts routes (evidence: `apps/api/src/app.ts`)
- Auth routes → Authentication: calls (evidence: `apps/api/src/modules/auth/auth.routes.ts`)
- Authentication middleware → Auth routes: guards routes (evidence: `apps/api/src/modules/auth/auth.routes.ts`)
- Scope middleware → Request scope: resolves scope (evidence: `apps/api/src/middleware/withScope.ts`)
- Authentication middleware → Authentication: verifies token (evidence: `apps/api/src/middleware/requireAuth.ts`)
- Transaction routes → Transaction management: calls (evidence: `apps/api/src/modules/transactions/transactions.routes.ts`)
- Transaction routes → Suggestion workflow: bulk categorizes (evidence: `apps/api/src/modules/transactions/transactions.routes.ts`)
- Suggestion review → API client: loads and applies (evidence: `apps/web/src/pages/ReviewPage.tsx`)
- API client → Shared contracts: uses contracts (evidence: `apps/web/src/lib/api.ts`)
- Authentication → PostgreSQL: reads and writes (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Transaction management → PostgreSQL: persists records
- Bank connection routes → Pluggy integration: calls (evidence: `apps/api/src/modules/pluggy/pluggy.routes.ts`)
- Pluggy integration → Pluggy client: uses client
- Pluggy client → Pluggy Open Finance: connects to
- Bank webhooks → Pluggy integration: dispatches events (evidence: `apps/api/src/modules/pluggy/webhook.routes.ts`)
- Pluggy integration → PostgreSQL: stores sync data
- Authentication → Shared household: loads household (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Categories → PostgreSQL: persists categories
- Budgets → PostgreSQL: persists limits
- Savings goals → PostgreSQL: persists goals
- Reports → PostgreSQL: queries finances
- Shared household → PostgreSQL: persists membership (evidence: `apps/api/src/modules/household/household.service.ts`)
- Suggestion workflow → Categorization engine: uses engine