rajadilipkolli/hilla-folioman

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.