mrahmanashiq/pfm

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.