# rajadilipkolli/hilla-folioman architecture

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

- Interactive diagram: https://gitdiagram.com/rajadilipkolli/hilla-folioman
- Repository: https://github.com/rajadilipkolli/hilla-folioman

## Overview

1. **Overall shape**  
   FolioMan is a **single Spring Boot monolith** with a **React/Hilla frontend** embedded in the same deployable application. The browser UI is built from `src/main/frontend`, while the server-side domain, REST APIs, security, persistence, and background jobs live under `src/main/java/com/app/folioman`.

2. **Primary user-facing flows**  
   The frontend is route-based and centered on a few views: login, user profile, mutual fund scheme search, portfolio overview, CAS import, and rebalance. `MainLayout` provides the shell/navigation, and `auth.ts` handles client-side auth integration. The frontend talks to backend endpoints over HTTP; there is no separate frontend server in production.

3. **Security boundary**  
   Authentication is handled in the `auth` package with **JWT-based security**. The flow includes login, access token issuance, refresh tokens, token blacklist support, login-attempt tracking, and a JWT filter inserted into Spring Security. User profile and user-info endpoints sit behind this security layer. A default admin account is seeded for local/testing use.

4. **Mutual-fund reference data subsystem**  
   The `mfschemes` package is the reference-data engine for AMC, scheme, and NAV information. It integrates with external mutual-fund data sources such as **AMFI** and **BSE Star** through scheduled sync services and REST clients. This subsystem stores scheme metadata and NAV history, exposes scheme/NAV APIs, and keeps a local searchable copy of fund master data.

5. **Portfolio ingestion and analytics subsystem**  
   The `portfolio` package is the transactional core. It ingests **CAS files** from mutual fund registrars, extracts holdings and transactions, persists investor/folio/scheme/transaction records, and computes portfolio values, monthly/yearly summaries, and rebalancing recommendations. It also contains valuation logic such as **XIRR** calculations and aggregation projections for the UI.

6. **Non-JVM processing boundary**  
   CAS PDF parsing crosses a clear process boundary via the `pythonbridge` package. Java commands are translated into Python executions, with explicit handling for missing Python, execution failures, and timeouts. This is a key architectural dependency because CAS import will not work without the external Python CLI tooling (`casparser`).

7. **Persistence model**  
   The application uses **PostgreSQL** with **Liquibase** changelogs to create and evolve schemas for auth, mutual-fund reference data, and portfolio data. The codebase relies heavily on JPA entities, Spring Data repositories, and projection interfaces to shape query results for REST responses. The repo layout suggests a domain-oriented schema split rather than a single flat table model.

8. **Caching strategy**  
   Redis is a first-class infrastructure dependency. There is a custom cache manager, cache circuit breaker, TTL adjustment policies, and adaptive cache-sizing logic. Caches are used to protect expensive reference-data and portfolio computations, especially where NAV and scheme data are reused frequently.

9. **Background processing and eventing**  
   Several services run asynchronously or on schedules: scheme/NAV synchronization, portfolio value updates, and cache policy evaluation. The `shared.events` package and listeners such as `NewlyInsertedSchemesListener` show that the app uses internal events to propagate changes between subsystems without tight coupling.

10. **Cross-cutting infrastructure**  
   Common application concerns are centralized under `config`: async execution, scheduling, CORS, global exception handling, REST client setup, OpenTelemetry appender installation, and database connection tuning. This makes the runtime behavior more operationally robust and shows that the app is designed for long-running server deployment, not just local development.

11. **Operational topology**  
   Local development is container-friendly: the repo includes Docker Compose for PostgreSQL and pgAdmin, plus Spring profiles for local and production. The backend is packaged as a single JAR that includes the frontend assets, so deployment is effectively one service with external dependencies on PostgreSQL, Redis, and Python tooling.

12. **How the main data flows connect**  
   The critical flow is: **user logs in → JWT-secured API calls → CAS import or portfolio actions → Python parsing and domain persistence → reference-data lookup for schemes/NAVs → cached portfolio calculations → REST responses back to the React UI**. External mutual-fund feeds continuously refresh the reference-data layer, and portfolio analytics consume that data to keep valuations and recommendations current.

Main entry points: [`src/main/frontend/routes.tsx`](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/routes.tsx) (UI routes), [`src/main/java/com/app/folioman/portfolio/domain`](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/portfolio/domain) (Portfolio core), [`src/main/java/com/app/folioman/mfschemes/domain`](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/mfschemes/domain) (Scheme sync), [`src/main/java/com/app/folioman/config`](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/config) (App config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_shell["UI shell<br/>Hilla layout<br/>[MainLayout.tsx]"]
  node_ui_routes["UI routes<br/>React navigation<br/>[routes.tsx]"]
  node_ui_auth["Client auth<br/>frontend auth<br/>[auth.ts]"]
  node_login_view["Login<br/>auth view<br/>[LoginView.tsx]"]
  node_portfolio_view["Portfolio"]
  node_import_view["CAS import<br/>upload view"]
  node_rebalance_view["Rebalance<br/>analytics view<br/>[ReBalanceView.tsx]"]
  node_profile_view["Profile"]
  node_mfschemes_view["Schemes<br/>reference-data view<br/>[MfSchemesView.tsx]"]
end

subgraph group_backend["Backend"]
  node_app(("FolioMan app<br/>Spring Boot monolith<br/>[Application.java]"))
  node_auth_api["Auth API<br/>security api"]
  node_jwt_security{{"JWT security<br/>security layer"}}
  node_mfschemes_api["MF APIs<br/>reference-data api"]
  node_mfschemes_domain{{"Scheme sync<br/>reference-data domain"}}
  node_portfolio_api["Portfolio API<br/>[PortfolioAPI.java]"]
  node_portfolio_domain{{"Portfolio core<br/>portfolio domain"}}
end

subgraph group_infra["Infrastructure"]
  node_python_bridge{{"Python bridge<br/>non-jvm bridge"}}
  node_redis_cache[("Redis cache<br/>adaptive caching")]
  node_db_schema[("PostgreSQL + Liquibase<br/>persistence")]
  node_shared_events(("Shared events<br/>internal events"))
  node_app_config["App config<br/>runtime config"]
end

node_app -->|"serves UI"| node_ui_shell
node_ui_shell -->|"navigates"| node_ui_routes
node_ui_routes -->|"auth flow"| node_ui_auth
node_ui_routes -->|"shows"| node_login_view
node_ui_routes -->|"shows"| node_portfolio_view
node_ui_routes -->|"shows"| node_import_view
node_ui_routes -->|"shows"| node_rebalance_view
node_ui_routes -->|"shows"| node_profile_view
node_ui_routes -->|"shows"| node_mfschemes_view
node_ui_auth -->|"calls"| node_auth_api
node_auth_api -->|"protected by"| node_jwt_security
node_jwt_security -->|"persists"| node_db_schema
node_mfschemes_api -->|"delegates"| node_mfschemes_domain
node_mfschemes_domain -->|"stores"| node_db_schema
node_mfschemes_domain -->|"caches"| node_redis_cache
node_mfschemes_domain -->|"publishes"| node_shared_events
node_portfolio_api -->|"delegates"| node_portfolio_domain
node_portfolio_domain -->|"parses CAS"| node_python_bridge
node_portfolio_domain -->|"looks up NAV"| node_mfschemes_domain
node_portfolio_domain -->|"stores"| node_db_schema
node_portfolio_domain -->|"caches"| node_redis_cache
node_portfolio_domain -->|"consumes"| node_shared_events
node_app_config -->|"configures"| node_jwt_security
node_app_config -->|"configures"| node_redis_cache
node_app_config -->|"configures"| node_db_schema
node_app_config -->|"configures"| node_python_bridge

click node_app "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/java/com/app/folioman/Application.java"
click node_ui_shell "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/MainLayout.tsx"
click node_ui_routes "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/routes.tsx"
click node_ui_auth "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/auth.ts"
click node_login_view "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/login/LoginView.tsx"
click node_portfolio_view "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/userPortfolio/UserPortfolioView.tsx"
click node_import_view "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/importmutualfunds/ImportMutualFundsView.tsx"
click node_rebalance_view "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/rebalance/ReBalanceView.tsx"
click node_profile_view "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/userprofile/UserProfileView.tsx"
click node_mfschemes_view "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/mfschemes/MfSchemesView.tsx"
click node_auth_api "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/java/com/app/folioman/auth/rest/AuthController.java"
click node_jwt_security "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/auth"
click node_mfschemes_api "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/mfschemes"
click node_mfschemes_domain "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/mfschemes/domain"
click node_portfolio_api "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/java/com/app/folioman/portfolio/PortfolioAPI.java"
click node_portfolio_domain "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/portfolio/domain"
click node_python_bridge "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/pythonbridge"
click node_redis_cache "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/config/redis"
click node_db_schema "https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/resources/db/changelog/db.changelog-master.yaml"
click node_shared_events "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/shared/events"
click node_app_config "https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/config"

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_ui_shell,node_ui_routes,node_ui_auth,node_login_view,node_portfolio_view,node_import_view,node_rebalance_view,node_profile_view,node_mfschemes_view toneBlue
class node_app,node_auth_api,node_jwt_security,node_mfschemes_api,node_mfschemes_domain,node_portfolio_api,node_portfolio_domain toneAmber
class node_python_bridge,node_redis_cache,node_db_schema,node_shared_events,node_app_config toneMint
```

## Components

### Frontend

Embedded React/Hilla UI in the monolith.

- [UI shell](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/MainLayout.tsx): Hilla layout · Top-level app shell and route composition for the browser UI. · `src/main/frontend/views/MainLayout.tsx`
- [UI routes](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/routes.tsx): React navigation · Route setup and view wiring for the embedded frontend. · `src/main/frontend/routes.tsx`
- [Client auth](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/auth.ts): frontend auth · Browser-side auth integration and token/session handling. · `src/main/frontend/auth.ts`
- [Login](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/login/LoginView.tsx): auth view · User sign-in screen. · `src/main/frontend/views/login/LoginView.tsx`
- [Portfolio](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/userPortfolio/UserPortfolioView.tsx): portfolio view · Portfolio overview and summaries in the UI. · `src/main/frontend/views/userPortfolio/UserPortfolioView.tsx`
- [CAS import](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/importmutualfunds/ImportMutualFundsView.tsx): upload view · UI for importing mutual-fund CAS files. · `src/main/frontend/views/importmutualfunds/ImportMutualFundsView.tsx`
- [Rebalance](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/rebalance/ReBalanceView.tsx): analytics view · UI for rebalancing recommendations. · `src/main/frontend/views/rebalance/ReBalanceView.tsx`
- [Profile](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/userprofile/UserProfileView.tsx): profile view · User profile and account information view. · `src/main/frontend/views/userprofile/UserProfileView.tsx`
- [Schemes](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/frontend/views/mfschemes/MfSchemesView.tsx): reference-data view · Search and browse mutual-fund schemes and NAVs. · `src/main/frontend/views/mfschemes/MfSchemesView.tsx`

### Backend

Spring Boot domain and API layers.

- [FolioMan app](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/java/com/app/folioman/Application.java): Spring Boot monolith · Single deployable that bundles the backend and embedded frontend. · `src/main/java/com/app/folioman/Application.java`
- [Auth API](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/java/com/app/folioman/auth/rest/AuthController.java): security api · Login, user-info, and profile endpoints behind JWT security. · `src/main/java/com/app/folioman/auth/rest/AuthController.java`
- [JWT security](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/auth): security layer · JWT issuance, refresh tokens, blacklist, login-attempt tracking, and filter-based enforcement. · `src/main/java/com/app/folioman/auth`
- [MF APIs](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/mfschemes): reference-data api · Scheme and NAV REST endpoints. · `src/main/java/com/app/folioman/mfschemes`
- [Scheme sync](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/mfschemes/domain): reference-data domain · AMC, scheme, and NAV ingestion plus synchronization logic. · `src/main/java/com/app/folioman/mfschemes/domain`
- [Portfolio API](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/java/com/app/folioman/portfolio/PortfolioAPI.java): portfolio api · Import, transaction, and rebalance REST endpoints. · `src/main/java/com/app/folioman/portfolio/PortfolioAPI.java`
- [Portfolio core](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/portfolio/domain): portfolio domain · CAS ingestion, folio persistence, valuation, summaries, and rebalance calculations. · `src/main/java/com/app/folioman/portfolio/domain`

### Infrastructure

Cross-cutting runtime and integration support.

- [Python bridge](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/pythonbridge): non-jvm bridge · Executes external Python tooling for CAS PDF parsing and handles failures/timeouts. · `src/main/java/com/app/folioman/pythonbridge`
- [Redis cache](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/config/redis): adaptive caching · Custom cache manager, circuit breaker, TTL adjustment, and cache-size policies. · `src/main/java/com/app/folioman/config/redis`
- [PostgreSQL + Liquibase](https://github.com/rajadilipkolli/hilla-folioman/blob/main/src/main/resources/db/changelog/db.changelog-master.yaml): persistence · Versioned relational schema for auth, reference data, and portfolio records. · `src/main/resources/db/changelog/db.changelog-master.yaml`
- [Shared events](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/shared/events): internal events · Application events used to decouple refresh and update flows across subsystems. · `src/main/java/com/app/folioman/shared/events`
- [App config](https://github.com/rajadilipkolli/hilla-folioman/tree/main/src/main/java/com/app/folioman/config): runtime config · Async, scheduling, CORS, exception handling, telemetry, and database/runtime tuning. · `src/main/java/com/app/folioman/config`

## Connections

- FolioMan app → UI shell: serves UI · Backend packages and serves the embedded frontend assets.
- UI shell → UI routes: navigates · The shell hosts route-based views.
- UI routes → Client auth: auth flow · Routes coordinate client-side authentication state.
- UI routes → Login: shows · Login is one of the primary routes.
- UI routes → Portfolio: shows · Portfolio overview route.
- UI routes → CAS import: shows · CAS import route.
- UI routes → Rebalance: shows · Rebalance route.
- UI routes → Profile: shows · Profile route.
- UI routes → Schemes: shows · Scheme search and NAV browsing route.
- Client auth → Auth API: calls · Frontend auth integrates with backend authentication endpoints.
- Auth API → JWT security: protected by · Auth endpoints sit inside the JWT security boundary.
- JWT security → PostgreSQL + Liquibase: persists · Refresh tokens, users, roles, and blacklist-related state are stored in the database.
- MF APIs → Scheme sync: delegates · Reference-data endpoints rely on sync and lookup services.
- Scheme sync → PostgreSQL + Liquibase: stores · Scheme, AMC, type, and NAV data are persisted relationally.
- Scheme sync → Redis cache: caches · Reference-data lookups and NAV reuse are accelerated through Redis.
- Scheme sync → Shared events: publishes · New scheme insertions and refresh events are propagated internally.
- Portfolio API → Portfolio core: delegates · Portfolio endpoints invoke ingestion, valuation, and rebalance logic.
- Portfolio core → Python bridge: parses CAS · CAS import crosses into Python tooling for PDF extraction.
- Portfolio core → Scheme sync: looks up NAV · Portfolio valuation and recommendations depend on scheme and NAV reference data.
- Portfolio core → PostgreSQL + Liquibase: stores · Investor, folio, scheme, transaction, and value records are persisted.
- Portfolio core → Redis cache: caches · Expensive valuations and summaries are cached.
- Portfolio core → Shared events: consumes · Portfolio updates react to internal application events.
- App config → JWT security: configures · Security behavior is wired through application configuration.
- App config → Redis cache: configures · Cache policies and Redis runtime are centralized here.
- App config → PostgreSQL + Liquibase: configures · Data source and persistence behavior are tuned here.
- App config → Python bridge: configures · Python execution settings and timeouts are supplied through config.