# apptivedev/fin-be architecture

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

- Interactive diagram: https://gitdiagram.com/apptivedev/fin-be
- Repository: https://github.com/apptivedev/fin-be

## Overview

Y-FIN is a Spring backend for youth-oriented finance discovery and planning. The principal workflow takes a user's product criteria, resolves eligibility and personalization, ranks eligible product options, and returns recommendations with matching details. Related capabilities cover OAuth2/JWT access, profiles and terms, favorites, policy calendars, and savings calculators. The graph reflects README-described API capabilities and the source references shown in the index; several domain implementations were not excerpted, so their internal links are intentionally limited.

Main entry points: [`src/main/java/apptive/fin/search/service/SearchService.java`](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/SearchService.java) (Recommendation search), [`src/main/java/apptive/fin/auth/service/AuthService.java`](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/service/AuthService.java) (Token lifecycle), [`src/main/java/apptive/fin/auth/oauth/OAuth2UserService.java`](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/oauth/OAuth2UserService.java) (OAuth2 login), [`src/main/java/apptive/fin/auth/controller/AuthController.java`](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/controller/AuthController.java) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; Profile"]
  node_oauth["OAuth2 login"]
  node_authapi["Auth endpoints"]
  node_authservice["Token lifecycle<br/>[AuthService.java]"]
  node_refreshstore[("Refresh tokens")]
  node_users[("User accounts<br/>[User.java]")]
  node_profile["User profile"]
  node_terms["Terms &amp; consent<br/>[TermService.java]"]
end

subgraph group_discovery["Product Discovery"]
  node_searchapi["Search endpoints"]
  node_search["Recommendation search<br/>[SearchService.java]"]
  node_eligibility["Eligibility filtering"]
  node_scoring["Match scoring"]
  node_rates["Rate &amp; return estimates"]
  node_products[("Financial products<br/>[Product.java]")]
end

subgraph group_planning["Planning Tools"]
  node_calendar["Policy calendar"]
  node_calculator["Savings calculator"]
end

subgraph group_catalog["Catalog &amp; Favorites"]
  node_categories["Categories"]
  node_myfin["Favorites<br/>[MyFinService.java]"]
  node_favoritesstore[("Favorite records")]
  node_providers["Providers"]
end

node_client(("Finance client"))

node_client -->|"starts login"| node_oauth
node_client -->|"manages tokens"| node_authapi
node_oauth -->|"resolves account"| node_users
node_authapi -.->|"handles auth"| node_authservice
node_authservice -->|"rotates tokens"| node_refreshstore
node_authservice -->|"checks consent"| node_terms
node_client -->|"manages profile"| node_profile
node_client -->|"records consent"| node_terms
node_client -->|"requests categories"| node_categories
node_client -->|"submits criteria"| node_searchapi
node_searchapi -.->|"dispatches search"| node_search
node_search -->|"filters options"| node_eligibility
node_search -->|"scores matches"| node_scoring
node_search -->|"calculates returns"| node_rates
node_search -.->|"reads products"| node_products
node_client -->|"manages favorites"| node_myfin
node_myfin -->|"stores favorites"| node_favoritesstore
node_client -->|"views schedules"| node_calendar
node_client -->|"calculates savings"| node_calculator

click node_oauth "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/oauth/OAuth2UserService.java"
click node_authapi "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/controller/AuthController.java"
click node_authservice "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/service/AuthService.java"
click node_refreshstore "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/repository/RefreshTokenRepository.java"
click node_users "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/user/entity/User.java"
click node_profile "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/user/service/UserProfileService.java"
click node_terms "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/term/service/TermService.java"
click node_categories "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/category/service/CategoryService.java"
click node_searchapi "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/controller/SearchController.java"
click node_search "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/SearchService.java"
click node_eligibility "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/EligibilityFilterService.java"
click node_scoring "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/MatchScoreService.java"
click node_rates "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/RateCalculatorService.java"
click node_products "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/entity/Product.java"
click node_myfin "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/myfin/service/MyFinService.java"
click node_favoritesstore "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/myfin/repository/MyFinRepository.java"
click node_providers "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/provider/service/ProviderService.java"
click node_calendar "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/calendar/service/CalendarService.java"
click node_calculator "https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/calculator/service/CalculatorService.java"

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_oauth,node_authapi,node_authservice,node_refreshstore,node_users,node_profile,node_terms,node_client toneBlue
class node_searchapi,node_search,node_eligibility,node_scoring,node_rates,node_products toneAmber
class node_calendar,node_calculator toneMint
class node_categories,node_myfin,node_favoritesstore,node_providers toneRose
```

## Components

### Identity & Profile

- [OAuth2 login](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/oauth/OAuth2UserService.java): `src/main/java/apptive/fin/auth/oauth/OAuth2UserService.java`
- [Auth endpoints](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/controller/AuthController.java): `src/main/java/apptive/fin/auth/controller/AuthController.java`
- [Token lifecycle](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/service/AuthService.java): `src/main/java/apptive/fin/auth/service/AuthService.java`
- [Refresh tokens](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/auth/repository/RefreshTokenRepository.java): `src/main/java/apptive/fin/auth/repository/RefreshTokenRepository.java`
- [User accounts](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/user/entity/User.java): `src/main/java/apptive/fin/user/entity/User.java`
- [User profile](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/user/service/UserProfileService.java): `src/main/java/apptive/fin/user/service/UserProfileService.java`
- [Terms & consent](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/term/service/TermService.java): `src/main/java/apptive/fin/term/service/TermService.java`

### Product Discovery

- [Search endpoints](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/controller/SearchController.java): `src/main/java/apptive/fin/search/controller/SearchController.java`
- [Recommendation search](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/SearchService.java): `src/main/java/apptive/fin/search/service/SearchService.java`
- [Eligibility filtering](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/EligibilityFilterService.java): `src/main/java/apptive/fin/search/service/EligibilityFilterService.java`
- [Match scoring](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/MatchScoreService.java): `src/main/java/apptive/fin/search/service/MatchScoreService.java`
- [Rate & return estimates](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/service/RateCalculatorService.java): `src/main/java/apptive/fin/search/service/RateCalculatorService.java`
- [Financial products](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/search/entity/Product.java): `src/main/java/apptive/fin/search/entity/Product.java`

### Planning Tools

- [Policy calendar](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/calendar/service/CalendarService.java): `src/main/java/apptive/fin/calendar/service/CalendarService.java`
- [Savings calculator](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/calculator/service/CalculatorService.java): `src/main/java/apptive/fin/calculator/service/CalculatorService.java`

### Catalog & Favorites

- [Categories](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/category/service/CategoryService.java): `src/main/java/apptive/fin/category/service/CategoryService.java`
- [Favorites](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/myfin/service/MyFinService.java): `src/main/java/apptive/fin/myfin/service/MyFinService.java`
- [Favorite records](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/myfin/repository/MyFinRepository.java): `src/main/java/apptive/fin/myfin/repository/MyFinRepository.java`
- [Providers](https://github.com/apptivedev/fin-be/blob/main/src/main/java/apptive/fin/provider/service/ProviderService.java): `src/main/java/apptive/fin/provider/service/ProviderService.java`

### Other components

- **Finance client**

## Connections

- Finance client → OAuth2 login: starts login
- Finance client → Auth endpoints: manages tokens
- OAuth2 login → User accounts: resolves account (evidence: `src/main/java/apptive/fin/auth/oauth/OAuth2UserService.java`)
- Auth endpoints → Token lifecycle: handles auth (evidence: `src/main/java/apptive/fin/auth/controller/AuthController.java`)
- Token lifecycle → Refresh tokens: rotates tokens (evidence: `src/main/java/apptive/fin/auth/service/AuthService.java`)
- Token lifecycle → Terms & consent: checks consent (evidence: `src/main/java/apptive/fin/auth/service/AuthService.java`)
- Finance client → User profile: manages profile
- Finance client → Terms & consent: records consent
- Finance client → Categories: requests categories
- Finance client → Search endpoints: submits criteria
- Search endpoints → Recommendation search: dispatches search (evidence: `src/main/java/apptive/fin/search/controller/SearchController.java`)
- Recommendation search → Eligibility filtering: filters options (evidence: `src/main/java/apptive/fin/search/service/SearchService.java`)
- Recommendation search → Match scoring: scores matches (evidence: `src/main/java/apptive/fin/search/service/SearchService.java`)
- Recommendation search → Rate & return estimates: calculates returns (evidence: `src/main/java/apptive/fin/search/service/SearchService.java`)
- Recommendation search → Financial products: reads products
- Finance client → Favorites: manages favorites
- Favorites → Favorite records: stores favorites (evidence: `src/main/java/apptive/fin/myfin/service/MyFinService.java`)
- Finance client → Policy calendar: views schedules
- Finance client → Savings calculator: calculates savings
