# jpaulovaz/cartoes-jp-app architecture

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

- Interactive diagram: https://gitdiagram.com/jpaulovaz/cartoes-jp-app
- Repository: https://github.com/jpaulovaz/cartoes-jp-app

## Overview

OrganizaPay is a financial-management web app and installable PWA centered on organizing card spending by monthly statement period, importing or entering transactions, splitting expenses, and following shared repayments. Its documented backend layers routes, controllers, services, and SQLite repositories; the README also describes sharing, messaging, administration, and backup capabilities. The graph includes those documented product areas, but their internal wiring is not fully shown in the sampled source, so uncertain links are omitted. External integrations are marked optional.

Main entry points: [`src/routes/index.js`](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/routes/index.js) (Route registry), [`src/repositories/finances.repository.js`](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/repositories/finances.repository.js) (SQLite repositories), [`src/services/import.service.js`](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/import.service.js) (Statement imports), [`src/services/adminCore.service.js`](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/adminCore.service.js) (Admin controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web and PWA"]
  node_client["Web client<br/>[app.js]"]
  node_pwa["Service worker<br/>[sw.js]"]
end

subgraph group_finance["Finance workflow"]
  node_cards["Cards and periods<br/>[cards.service.js]"]
  node_finances["Transactions and splits"]
  node_imports["Statement imports<br/>[import.service.js]"]
  node_importers["CSV importers<br/>[index.js]"]
  node_summary["Monthly summaries<br/>[summary.service.js]"]
end

subgraph group_people["People and sharing"]
  node_shared["Shared repayments"]
  node_social["Person sharing"]
  node_notifications["Notifications"]
end

subgraph group_platform["Identity and operations"]
  node_entry["Server bootstrap<br/>[server.js]"]
  node_runtime["App runtime<br/>[server.runtime.js]"]
  node_route_index["Route registry<br/>[index.js]"]
  node_auth["Google sign-in<br/>[auth.service.js]"]
  node_security["PIN and passkeys"]
  node_admin["Admin controls"]
  node_backup["Backup and restore<br/>[backupEngine.js]"]
  node_repositories["SQLite repositories"]
  node_database[("Application database<br/>[db.js]")]
end

node_user(("App user"))
node_google(("Google OAuth"))
node_push(("Web Push"))
node_whatsapp(("WhatsApp API"))
node_drive(("Google Drive"))

node_user -->|"uses"| node_client
node_client -->|"requests"| node_entry
node_pwa -->|"supports offline"| node_client
node_entry -->|"loads runtime"| node_runtime
node_runtime -->|"composes routes"| node_route_index
node_route_index -->|"dispatches card routes"| node_cards
node_route_index -->|"dispatches finance routes"| node_finances
node_route_index -->|"dispatches import routes"| node_imports
node_route_index -->|"dispatches summary routes"| node_summary
node_route_index -->|"dispatches debt routes"| node_shared
node_route_index -->|"dispatches sharing routes"| node_social
node_route_index -->|"dispatches notification routes"| node_notifications
node_route_index -->|"dispatches auth routes"| node_auth
node_route_index -->|"dispatches security routes"| node_security
node_route_index -->|"dispatches admin routes"| node_admin
node_imports -->|"uses importers"| node_importers
node_cards -->|"accesses data"| node_repositories
node_finances -->|"accesses data"| node_repositories
node_imports -->|"accesses data"| node_repositories
node_summary -->|"accesses data"| node_repositories
node_shared -->|"accesses data"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_auth -.->|"authenticates"| node_google
node_notifications -.->|"sends alerts"| node_push
node_admin -.->|"configures messaging"| node_whatsapp
node_backup -.->|"uploads backups"| node_drive
node_admin -->|"manages backups"| node_backup

click node_client "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/public/app.js"
click node_pwa "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/public/sw.js"
click node_entry "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/server.js"
click node_runtime "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/server.runtime.js"
click node_route_index "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/routes/index.js"
click node_cards "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/cards.service.js"
click node_finances "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/finances.service.js"
click node_imports "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/import.service.js"
click node_importers "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/importers/index.js"
click node_summary "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/summary.service.js"
click node_shared "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/sharedDebts.service.js"
click node_social "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/socialShare.service.js"
click node_notifications "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/notifications.service.js"
click node_auth "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/auth.service.js"
click node_security "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/security.service.js"
click node_admin "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/adminCore.service.js"
click node_backup "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/backupEngine.js"
click node_repositories "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/repositories/finances.repository.js"
click node_database "https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/db.js"

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_client,node_pwa,node_user toneBlue
class node_cards,node_finances,node_imports,node_importers,node_summary toneAmber
class node_shared,node_social,node_notifications,node_whatsapp toneMint
class node_entry,node_runtime,node_route_index,node_auth,node_security,node_admin,node_backup,node_repositories,node_database toneRose
class node_google,node_push,node_drive toneIndigo
```

## Components

### Web and PWA

- [Web client](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/public/app.js): `public/app.js`
- [Service worker](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/public/sw.js): `public/sw.js`

### Finance workflow

- [Cards and periods](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/cards.service.js): `src/services/cards.service.js`
- [Transactions and splits](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/finances.service.js): `src/services/finances.service.js`
- [Statement imports](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/import.service.js): `src/services/import.service.js`
- [CSV importers](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/importers/index.js): `src/importers/index.js`
- [Monthly summaries](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/summary.service.js): `src/services/summary.service.js`

### People and sharing

- [Shared repayments](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/sharedDebts.service.js): `src/services/sharedDebts.service.js`
- [Person sharing](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/socialShare.service.js): `src/services/socialShare.service.js`
- [Notifications](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/notifications.service.js): `src/services/notifications.service.js`

### Identity and operations

- [Server bootstrap](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/server.js): `server.js`
- [App runtime](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/server.runtime.js): `server.runtime.js`
- [Route registry](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/routes/index.js): `src/routes/index.js`
- [Google sign-in](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/auth.service.js): `src/services/auth.service.js`
- [PIN and passkeys](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/security.service.js): `src/services/security.service.js`
- [Admin controls](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/services/adminCore.service.js): `src/services/adminCore.service.js`
- [Backup and restore](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/backupEngine.js): `src/backupEngine.js`
- [SQLite repositories](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/repositories/finances.repository.js): `src/repositories/finances.repository.js`
- [Application database](https://github.com/jpaulovaz/cartoes-jp-app/blob/main/src/db.js): `src/db.js`

### Other components

- **App user**
- **Google OAuth**
- **Web Push**
- **WhatsApp API**
- **Google Drive**

## Connections

- App user → Web client: uses
- Web client → Server bootstrap: requests
- Service worker → Web client: supports offline
- Server bootstrap → App runtime: loads runtime
- App runtime → Route registry: composes routes
- Route registry → Cards and periods: dispatches card routes
- Route registry → Transactions and splits: dispatches finance routes
- Route registry → Statement imports: dispatches import routes
- Route registry → Monthly summaries: dispatches summary routes
- Route registry → Shared repayments: dispatches debt routes
- Route registry → Person sharing: dispatches sharing routes
- Route registry → Notifications: dispatches notification routes
- Route registry → Google sign-in: dispatches auth routes
- Route registry → PIN and passkeys: dispatches security routes
- Route registry → Admin controls: dispatches admin routes
- Statement imports → CSV importers: uses importers
- Cards and periods → SQLite repositories: accesses data
- Transactions and splits → SQLite repositories: accesses data
- Statement imports → SQLite repositories: accesses data
- Monthly summaries → SQLite repositories: accesses data
- Shared repayments → SQLite repositories: accesses data
- SQLite repositories → Application database: reads and writes
- Google sign-in → Google OAuth: authenticates
- Notifications → Web Push: sends alerts
- Admin controls → WhatsApp API: configures messaging
- Backup and restore → Google Drive: uploads backups
- Admin controls → Backup and restore: manages backups