# mrahmanashiq/pfm architecture

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

- Interactive diagram: https://gitdiagram.com/mrahmanashiq/pfm
- Repository: https://github.com/mrahmanashiq/pfm

## Overview

1. **Repository shape**
   - This is a monorepo with two independently built applications: a **Spring Boot backend** in the root `src/` tree and a **React + TypeScript frontend** in `pfm-client/`.
   - The root Gradle build (`build.gradle`, `settings.gradle`) drives the backend; the client has its own `package.json` and Node toolchain.

2. **Primary runtime boundary**
   - The backend runs as a Java 17 Spring Boot service on port **8090**.
   - The frontend runs as a separate SPA dev/build app, typically on **3000**, and talks to the backend over HTTP.
   - `docker-compose.yml` and `Dockerfile` indicate the system is also meant to be containerized, with MySQL as the persistent store.

3. **Backend layering**
   - The backend follows a classic layered Spring structure:
     - `controller` exposes REST endpoints,
     - `service` holds business logic,
     - `repository` handles persistence,
     - `entity` defines JPA domain models,
     - `dto` isolates API payloads,
     - `security` contains JWT and Spring Security components,
     - `config` contains app-wide wiring.
   - This separation is the main architecture boundary for diagramming the server side.

4. **Domain model**
   - The core persisted domain is finance-oriented: `Users`, `UserProfile`, `Account`, `Transaction`, `Category`, `Budget`, and `Goal`.
   - The implemented API surface in the tree is strongest around **auth, users, accounts, and transactions**; budgets/goals/categories exist as entities/DTOs but appear more like modeled future or partial features.

5. **API flow**
   - HTTP requests enter through `AuthController`, `AccountController`, and `UserController`.
   - Controllers map requests into DTOs, call services, then services use repositories to load or mutate JPA entities.
   - Responses are returned as DTOs, keeping the API contract separate from persistence entities.

6. **Security flow**
   - Authentication is JWT-based, implemented with `JwtUtils`, `JwtAuthenticationFilter`, `JwtAuthenticationEntryPoint`, `CustomUserDetailsService`, and `UserPrincipal`.
   - The typical flow is: user signs in via `/api/v1/auth/*`, backend validates credentials, issues a JWT, and later requests present that token to access protected endpoints.
   - `WebSecurityConfig` defines the security boundary and request filtering.

7. **Persistence boundary**
   - The backend persists state through Spring Data JPA repositories: `AccountRepository`, `TransactionRepository`, `CategoryRepository`, and `UserRepository`.
   - MySQL 8 is the external database dependency, configured through `application.properties` and environment variables from `.env.example`.
   - This is the only durable data store visible in the repo tree.

8. **Frontend architecture**
   - The client is a React 18 + TypeScript SPA built from `pfm-client/src`.
   - The UI is organized into feature-oriented components: `Auth`, `Accounts`, `Transactions`, `Dashboard`, and shared `Layout`.
   - `services/api.ts` is the client-side integration point to the backend API, while `types/` centralizes typed contracts.

9. **Frontend-to-backend interaction**
   - The frontend submits forms for login/registration, account creation/editing, and transaction entry.
   - It likely consumes JWT-protected endpoints after authentication, with state flowing from forms/components to the API service layer and back into lists/cards/dashboard summaries.
   - The `Dashboard` area is the aggregation point for finance summaries, while `Layout` wraps authenticated navigation and page chrome.

10. **Configuration and environment**
   - Runtime configuration is externalized through properties/env vars: DB URL, JWT secret/expirations, and CORS origins.
   - `AppConfig` and `WebSecurityConfig` are the key Spring configuration points affecting request handling and cross-origin access from the SPA.
   - The presence of `swagger-ui.html` in the README suggests API documentation is exposed by the backend as part of the service boundary.

11. **Build, test, and deployment**
   - Backend build/test lifecycle is Gradle-based, with a minimal backend test scaffold under `src/test`.
   - Frontend uses Node tooling, Tailwind, and typical React app packaging.
   - GitHub Actions (`.github/workflows/ci-cd.yml`) plus Docker assets indicate the repo is set up for automated CI/CD and container deployment.

12. **What to emphasize in an architecture diagram**
   - Draw two major tiers: **React SPA** and **Spring Boot API**.
   - Show the backend internally split into **security → controllers → services → repositories → MySQL**.
   - Show JWT as the cross-cutting control plane for authenticated API calls.
   - Treat budgets/goals/categories as domain models present in the codebase, even if the currently exposed UI/API emphasis is on authentication, accounts, and transactions.

Main entry points: [`pfm-client/src/components/Layout/MainLayout.tsx`](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Layout/MainLayout.tsx) (Layout), [`pfm-client/src/services/api.ts`](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/services/api.ts) (API client), [`src/main/java/mra_pfm/pfm/controller/AuthController.java`](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/controller/AuthController.java) (Controllers), [`src/main/java/mra_pfm/pfm/service/AuthService.java`](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/service/AuthService.java) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_frontend_app["SPA<br/>react ts app<br/>[App.tsx]"]
  node_frontend_auth["Auth UI<br/>feature views<br/>[LoginForm.tsx]"]
  node_frontend_accounts["Accounts UI<br/>feature views<br/>[AccountList.tsx]"]
  node_frontend_txns["Transactions UI<br/>feature views"]
  node_frontend_dashboard["Dashboard<br/>summary view<br/>[Dashboard.tsx]"]
  node_frontend_layout["Layout<br/>shell<br/>[MainLayout.tsx]"]
  node_frontend_api["API client<br/>http service<br/>[api.ts]"]
  node_frontend_types["Types<br/>contracts<br/>[index.ts]"]
end

subgraph group_backend["Spring Boot API"]
  node_backend_app["API app<br/>spring boot app"]
  node_backend_config["Config"]
  node_backend_security["JWT security<br/>auth pipeline<br/>[JwtUtils.java]"]
  node_backend_controllers["Controllers<br/>rest api"]
  node_backend_services["Services<br/>business logic<br/>[AuthService.java]"]
  node_backend_repos["Repositories<br/>jpa data access"]
  node_backend_dto["DTOs<br/>api contracts<br/>[LoginRequest.java]"]
  node_backend_domain[("Entities<br/>jpa domain<br/>[Account.java]")]
end

subgraph group_infra["Runtime & Deploy"]
  node_infra_db[("MySQL<br/>database")]
  node_infra_docker["Docker<br/>container stack<br/>[docker-compose.yml]"]
  node_infra_ci["CI/CD<br/>workflow<br/>[ci-cd.yml]"]
end

node_frontend_app -->|"uses"| node_frontend_layout
node_frontend_layout -->|"navigates"| node_frontend_auth
node_frontend_layout -->|"navigates"| node_frontend_accounts
node_frontend_layout -->|"navigates"| node_frontend_txns
node_frontend_layout -->|"navigates"| node_frontend_dashboard
node_frontend_auth -->|"calls"| node_frontend_api
node_frontend_accounts -->|"calls"| node_frontend_api
node_frontend_txns -->|"calls"| node_frontend_api
node_frontend_api -->|"typed by"| node_frontend_types
node_frontend_api -->|"HTTP"| node_backend_controllers
node_backend_app -->|"loads"| node_backend_config
node_backend_config -->|"configures"| node_backend_security
node_backend_security -->|"protects"| node_backend_controllers
node_backend_controllers -->|"maps"| node_backend_dto
node_backend_controllers -->|"delegates"| node_backend_services
node_backend_services -->|"uses"| node_backend_repos
node_backend_services -->|"mutates"| node_backend_domain
node_backend_repos -->|"persists"| node_backend_domain
node_backend_repos -->|"stores in"| node_infra_db
node_infra_docker -->|"runs"| node_backend_app
node_infra_docker -->|"runs"| node_frontend_app
node_infra_ci -.->|"builds"| node_infra_docker

click node_frontend_app "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/App.tsx"
click node_frontend_auth "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Auth/LoginForm.tsx"
click node_frontend_accounts "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Accounts/AccountList.tsx"
click node_frontend_txns "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Transactions/TransactionList.tsx"
click node_frontend_dashboard "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Dashboard/Dashboard.tsx"
click node_frontend_layout "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Layout/MainLayout.tsx"
click node_frontend_api "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/services/api.ts"
click node_frontend_types "https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/types/index.ts"
click node_backend_app "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/PfmApplication.java"
click node_backend_config "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/config/WebSecurityConfig.java"
click node_backend_security "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/security/JwtUtils.java"
click node_backend_controllers "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/controller/AuthController.java"
click node_backend_services "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/service/AuthService.java"
click node_backend_repos "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/repository/AccountRepository.java"
click node_backend_dto "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/dto/auth/LoginRequest.java"
click node_backend_domain "https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/entity/Account.java"
click node_infra_docker "https://github.com/mrahmanashiq/pfm/blob/master/docker-compose.yml"
click node_infra_ci "https://github.com/mrahmanashiq/pfm/blob/master/.github/workflows/ci-cd.yml"

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_frontend_app,node_frontend_auth,node_frontend_accounts,node_frontend_txns,node_frontend_dashboard,node_frontend_layout,node_frontend_api,node_frontend_types toneBlue
class node_backend_app,node_backend_config,node_backend_security,node_backend_controllers,node_backend_services,node_backend_repos,node_backend_dto,node_backend_domain toneAmber
class node_infra_db,node_infra_docker,node_infra_ci toneMint
```

## Components

### React SPA

Client application built in pfm-client/

- [SPA](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/App.tsx): react ts app · React 18 + TypeScript single-page app · `pfm-client/src/App.tsx`
- [Auth UI](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Auth/LoginForm.tsx): feature views · Login and registration forms · `pfm-client/src/components/Auth/LoginForm.tsx`
- [Accounts UI](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Accounts/AccountList.tsx): feature views · Account cards, lists, and forms · `pfm-client/src/components/Accounts/AccountList.tsx`
- [Transactions UI](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Transactions/TransactionList.tsx): feature views · Transaction entry and listing screens · `pfm-client/src/components/Transactions/TransactionList.tsx`
- [Dashboard](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Dashboard/Dashboard.tsx): summary view · Finance summary and overview panels · `pfm-client/src/components/Dashboard/Dashboard.tsx`
- [Layout](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/components/Layout/MainLayout.tsx): shell · Shared navigation and page chrome · `pfm-client/src/components/Layout/MainLayout.tsx`
- [API client](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/services/api.ts): http service · Frontend integration point for backend calls · `pfm-client/src/services/api.ts`
- [Types](https://github.com/mrahmanashiq/pfm/blob/master/pfm-client/src/types/index.ts): contracts · Shared TypeScript data contracts · `pfm-client/src/types/index.ts`

### Spring Boot API

Java backend in src/main/java

- [API app](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/PfmApplication.java): spring boot app · Spring Boot application entry point · `src/main/java/mra_pfm/pfm/PfmApplication.java`
- [Config](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/config/WebSecurityConfig.java): spring config · Application and security configuration · `src/main/java/mra_pfm/pfm/config/WebSecurityConfig.java`
- [JWT security](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/security/JwtUtils.java): auth pipeline · Token issuance, filtering, and user details · `src/main/java/mra_pfm/pfm/security/JwtUtils.java`
- [Controllers](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/controller/AuthController.java): rest api · Auth, account, and user REST endpoints · `src/main/java/mra_pfm/pfm/controller/AuthController.java`
- [Services](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/service/AuthService.java): business logic · Core application logic for auth, users, and accounts · `src/main/java/mra_pfm/pfm/service/AuthService.java`
- [Repositories](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/repository/AccountRepository.java): jpa data access · Spring Data JPA persistence layer · `src/main/java/mra_pfm/pfm/repository/AccountRepository.java`
- [DTOs](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/dto/auth/LoginRequest.java): api contracts · Request and response payload models · `src/main/java/mra_pfm/pfm/dto/auth/LoginRequest.java`
- [Entities](https://github.com/mrahmanashiq/pfm/blob/master/src/main/java/mra_pfm/pfm/entity/Account.java): jpa domain · Persisted finance domain models · `src/main/java/mra_pfm/pfm/entity/Account.java`

### Runtime & Deploy

Database, container, and CI/CD support

- **MySQL**: database · Persistent data store
- [Docker](https://github.com/mrahmanashiq/pfm/blob/master/docker-compose.yml): container stack · Containerization and compose deployment · `docker-compose.yml`
- [CI/CD](https://github.com/mrahmanashiq/pfm/blob/master/.github/workflows/ci-cd.yml): workflow · Automated build and delivery pipeline · `.github/workflows/ci-cd.yml`

## Connections

- SPA → Layout: uses · SPA is wrapped by shared layout
- Layout → Auth UI: navigates · Layout hosts auth screens
- Layout → Accounts UI: navigates · Layout hosts account views
- Layout → Transactions UI: navigates · Layout hosts transaction views
- Layout → Dashboard: navigates · Layout hosts dashboard summaries
- Auth UI → API client: calls · Forms submit authentication requests
- Accounts UI → API client: calls · Account CRUD flows use the API client
- Transactions UI → API client: calls · Transaction flows use the API client
- API client → Types: typed by · Client requests and responses use shared types
- API client → Controllers: HTTP · SPA talks to backend endpoints over HTTP
- API app → Config: loads · Application bootstraps configuration
- Config → JWT security: configures · Security defines request handling and CORS
- JWT security → Controllers: protects · JWT filter guards API endpoints
- Controllers → DTOs: maps · Controllers accept and return DTOs
- Controllers → Services: delegates · REST endpoints hand off to services
- Services → Repositories: uses · Services access persistence through repositories
- Services → Entities: mutates · Business logic operates on JPA entities
- Repositories → Entities: persists · Repositories manage entity storage
- Repositories → MySQL: stores in · JPA persistence targets MySQL
- Docker → API app: runs · Backend is containerized
- Docker → SPA: runs · Frontend is containerized
- CI/CD → Docker: builds · Pipeline builds container artifacts