# apptivedev/fin-api architecture

> Architecture diagram of the GitHub repository apptivedev/fin-api, 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-api
- Repository: https://github.com/apptivedev/fin-api

## Overview

This is a Spring-based financial-product collector. Its principal workflow is to fetch product data from financial and youth-policy sources, retain raw snapshots, normalize and optionally enrich product drafts, then synchronize products and provider properties into the catalog. Separate workflows scrape bank product URLs and synchronize youth-policy and policy-round data. The graph preserves these documented capabilities, but orchestration and several normalization details were not sampled; unverified workflow links are dashed rather than presented as observed calls.

Main entry points: [`src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java`](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java) (Scrape coordinator), [`src/main/java/apptive/fin/apicollector/normalize/dto/ProductDraft.java`](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/dto/ProductDraft.java) (Product drafts), [`src/main/java/apptive/fin/apicollector/normalize/normalizer`](https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/normalize/normalizer) (Source normalizers), [`src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java`](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java) (LLM enrichment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection"]
  node_sourceclients["Source clients"]
  node_rawsave["Raw snapshot saving"]
  node_rawdata[("Raw product store<br/>[ProductRaw.java]")]
end

subgraph group_normalization["Normalization"]
  node_normalizers["Source normalizers"]
  node_drafts["Product drafts<br/>[ProductDraft.java]"]
  node_extractors["Field extraction"]
  node_enrichment["LLM enrichment"]
  node_merger["Enrichment merge"]
  node_llmprovider["Gemini provider"]
  node_llmcache[("Enrichment cache")]
end

subgraph group_catalog["Product catalog"]
  node_productsync["Product synchronization"]
  node_catalogdata[("Product catalog<br/>[Product.java]")]
end

subgraph group_bankurls["Bank URL scraping"]
  node_bankrunner["Scrape coordinator"]
  node_bankscrapers["Bank scrapers"]
  node_banktargets["Bank URL targets"]
  node_bankurlstore["Scrape persistence"]
end

subgraph group_policy["Policy data"]
  node_youthsync["Youth policy sync"]
  node_youthdata[("Youth policy store<br/>[YouthPolicy.java]")]
  node_roundsync["Policy round sync"]
  node_rounddata[("Policy round store")]
end

node_operator(("Job initiator"))

node_operator -.->|"starts collection"| node_sourceclients
node_sourceclients -.->|"supplies raw data"| node_rawsave
node_rawsave -->|"saves snapshots"| node_rawdata
node_rawdata -.->|"feeds normalization"| node_normalizers
node_normalizers -.->|"creates drafts"| node_drafts
node_normalizers -.->|"uses extraction"| node_extractors
node_drafts -.->|"enriches drafts"| node_enrichment
node_enrichment -.->|"requests enrichment"| node_llmprovider
node_enrichment -.->|"uses cache"| node_llmcache
node_merger -->|"merges into"| node_drafts
node_drafts -.->|"synchronizes drafts"| node_productsync
node_productsync -->|"updates catalog"| node_catalogdata
node_operator -.->|"starts scraping"| node_bankrunner
node_bankrunner -->|"dispatches scraping"| node_bankscrapers
node_bankrunner -->|"processes targets"| node_banktargets
node_bankrunner -.->|"persists results"| node_bankurlstore
node_operator -.->|"starts sync"| node_youthsync
node_youthsync -->|"updates policies"| node_youthdata
node_operator -.->|"starts sync"| node_roundsync
node_roundsync -->|"synchronizes rounds"| node_rounddata
node_roundsync -->|"looks up products"| node_catalogdata

click node_sourceclients "https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/client"
click node_rawsave "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/raw/RawProductSaveService.java"
click node_rawdata "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/raw/ProductRaw.java"
click node_normalizers "https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/normalize/normalizer"
click node_drafts "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/dto/ProductDraft.java"
click node_extractors "https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/normalize/extractor"
click node_enrichment "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java"
click node_merger "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/enrich/LlmEnrichmentMerger.java"
click node_llmprovider "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/llm/gemini/GeminiLlmProviderClient.java"
click node_llmcache "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/llm/cache/LlmEnrichmentCache.java"
click node_productsync "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/product/service/ProductSyncService.java"
click node_catalogdata "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/product/entity/Product.java"
click node_bankrunner "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java"
click node_bankscrapers "https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/bankurl/scraper"
click node_banktargets "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/BankProductUrlTarget.java"
click node_bankurlstore "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/BankProductUrlPersistenceService.java"
click node_youthsync "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicySyncService.java"
click node_youthdata "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicy.java"
click node_roundsync "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/policyround/PolicyProductRoundSyncService.java"
click node_rounddata "https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/policyround/PolicyProductRound.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_sourceclients,node_rawsave,node_rawdata toneBlue
class node_normalizers,node_drafts,node_extractors,node_enrichment,node_merger,node_llmprovider,node_llmcache toneAmber
class node_productsync,node_catalogdata toneMint
class node_bankrunner,node_bankscrapers,node_banktargets,node_bankurlstore toneRose
class node_youthsync,node_youthdata,node_roundsync,node_rounddata,node_operator toneIndigo
```

## Components

### Collection

- [Source clients](https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/client): `src/main/java/apptive/fin/apicollector/client`
- [Raw snapshot saving](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/raw/RawProductSaveService.java): `src/main/java/apptive/fin/apicollector/raw/RawProductSaveService.java`
- [Raw product store](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/raw/ProductRaw.java): `src/main/java/apptive/fin/apicollector/raw/ProductRaw.java`

### Normalization

- [Source normalizers](https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/normalize/normalizer): `src/main/java/apptive/fin/apicollector/normalize/normalizer`
- [Product drafts](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/dto/ProductDraft.java): `src/main/java/apptive/fin/apicollector/normalize/dto/ProductDraft.java`
- [Field extraction](https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/normalize/extractor): `src/main/java/apptive/fin/apicollector/normalize/extractor`
- [LLM enrichment](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java): `src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java`
- [Enrichment merge](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/normalize/enrich/LlmEnrichmentMerger.java): `src/main/java/apptive/fin/apicollector/normalize/enrich/LlmEnrichmentMerger.java`
- [Gemini provider](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/llm/gemini/GeminiLlmProviderClient.java): `src/main/java/apptive/fin/apicollector/llm/gemini/GeminiLlmProviderClient.java`
- [Enrichment cache](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/llm/cache/LlmEnrichmentCache.java): `src/main/java/apptive/fin/apicollector/llm/cache/LlmEnrichmentCache.java`

### Product catalog

- [Product synchronization](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/product/service/ProductSyncService.java): `src/main/java/apptive/fin/apicollector/product/service/ProductSyncService.java`
- [Product catalog](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/product/entity/Product.java): `src/main/java/apptive/fin/apicollector/product/entity/Product.java`

### Bank URL scraping

- [Scrape coordinator](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java): `src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java`
- [Bank scrapers](https://github.com/apptivedev/fin-api/tree/main/src/main/java/apptive/fin/apicollector/bankurl/scraper): `src/main/java/apptive/fin/apicollector/bankurl/scraper`
- [Bank URL targets](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/BankProductUrlTarget.java): `src/main/java/apptive/fin/apicollector/bankurl/BankProductUrlTarget.java`
- [Scrape persistence](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/bankurl/BankProductUrlPersistenceService.java): `src/main/java/apptive/fin/apicollector/bankurl/BankProductUrlPersistenceService.java`

### Policy data

- [Youth policy sync](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicySyncService.java): `src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicySyncService.java`
- [Youth policy store](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicy.java): `src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicy.java`
- [Policy round sync](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/policyround/PolicyProductRoundSyncService.java): `src/main/java/apptive/fin/apicollector/policyround/PolicyProductRoundSyncService.java`
- [Policy round store](https://github.com/apptivedev/fin-api/blob/main/src/main/java/apptive/fin/apicollector/policyround/PolicyProductRound.java): `src/main/java/apptive/fin/apicollector/policyround/PolicyProductRound.java`

### Other components

- **Job initiator**

## Connections

- Job initiator → Source clients: starts collection
- Source clients → Raw snapshot saving: supplies raw data
- Raw snapshot saving → Raw product store: saves snapshots (evidence: `src/main/java/apptive/fin/apicollector/raw/RawProductSaveService.java`)
- Raw product store → Source normalizers: feeds normalization
- Source normalizers → Product drafts: creates drafts
- Source normalizers → Field extraction: uses extraction
- Product drafts → LLM enrichment: enriches drafts (evidence: `src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java`)
- LLM enrichment → Gemini provider: requests enrichment
- LLM enrichment → Enrichment cache: uses cache (evidence: `src/main/java/apptive/fin/apicollector/normalize/enrich/LlmProductDraftEnricher.java`)
- Enrichment merge → Product drafts: merges into (evidence: `src/main/java/apptive/fin/apicollector/normalize/enrich/LlmEnrichmentMerger.java`)
- Product drafts → Product synchronization: synchronizes drafts (evidence: `src/main/java/apptive/fin/apicollector/product/service/ProductSyncService.java`)
- Product synchronization → Product catalog: updates catalog (evidence: `src/main/java/apptive/fin/apicollector/product/service/ProductSyncService.java`)
- Job initiator → Scrape coordinator: starts scraping
- Scrape coordinator → Bank scrapers: dispatches scraping (evidence: `src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java`)
- Scrape coordinator → Bank URL targets: processes targets (evidence: `src/main/java/apptive/fin/apicollector/bankurl/runner/BankProductUrlScrapeService.java`)
- Scrape coordinator → Scrape persistence: persists results
- Job initiator → Youth policy sync: starts sync
- Youth policy sync → Youth policy store: updates policies (evidence: `src/main/java/apptive/fin/apicollector/youthpolicy/YouthPolicySyncService.java`)
- Job initiator → Policy round sync: starts sync
- Policy round sync → Policy round store: synchronizes rounds (evidence: `src/main/java/apptive/fin/apicollector/policyround/PolicyProductRoundSyncService.java`)
- Policy round sync → Product catalog: looks up products (evidence: `src/main/java/apptive/fin/apicollector/policyround/PolicyProductRoundSyncService.java`)
