# eric8900/weneedabudget-backend architecture

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

- Interactive diagram: https://gitdiagram.com/eric8900/weneedabudget-backend
- Repository: https://github.com/eric8900/weneedabudget-backend

## Overview

##### Project Type and Purpose
- This is a Java Spring Boot monolithic backend service exposing RESTful CRUD endpoints for a budgeting app (“We Need A Budget” clone).
- It handles user management, account/category/transaction CRUD, authentication (JWT and Google OAuth2), and persists data in PostgreSQL.

##### Key Directory/Component Analysis
- src/main/java/com/example/wnabudgetbackend
- config: security configuration, JWT utilities, OAuth2 success handler
- controller: REST controllers (Account, Category, Transaction, User, Auth, Ping)
- service: business logic for each domain entity
- repository: Spring Data JPA repositories for persistence
- dto: request/response models and PATCH payloads
- model: JPA entity definitions (User, Account, CategoryGroup, Category, Transaction)
- WnabudgetBackendApplication.java: Spring Boot entry point
- StreamLambdaHandler.java & template.yml: AWS Lambda / SAM packaging (optional serverless deployment)
- pom.xml & Maven wrapper: build and dependency management
- application.properties: externalized configuration (DB URL, AWS, security)
- Tests: one integration test class

##### Architectural Overview
a. Main Components
- Client (Web or Mobile UI)
- API Gateway / Load Balancer (e.g., AWS API Gateway or ELB)
- Spring Boot Application (hosted on AWS EC2, Container, or Lambda)
- Security Layer (JWT filter, OAuth2 filter)
- Controllers (REST endpoints)
- Service Layer
- Repository Layer
- PostgreSQL Database (AWS RDS)
- External Auth Provider (Google OAuth2)
b. Data Flows & Interactions
1. Client → API Gateway/Load Balancer → Spring Boot Security Filters
2. JWT Authentication Filter validates tokens; if login/signup, AuthController issues JWT via JwtUtil
3. For OAuth logins, Spring’s OAuth2SuccessHandler exchanges Google code for tokens
4. Controller receives requests → calls corresponding Service → invokes Repository → reads/writes DB
5. Database responses propagate back up through layers to client
c. Optional Serverless Variation
- API Gateway → AWS Lambda (StreamLambdaHandler) → Spring Boot function adapter → same service/repo layers → RDS
d. Architectural Patterns & Principles
- Layered Architecture (Controller → Service → Repository)
- Separation of Concerns (DTO layer for transport, model layer for persistence)
- Externalized Configuration (application.properties for environment-specific settings)
- Security as a Cross-Cutting Concern (filters, handlers, beans in config package)

##### Final Checklist for Detailed Coverage
- All REST controllers mapped to their domain entities.
- Security flow: JWT issuance & validation, OAuth2 integration.
- Data persistence path into PostgreSQL on RDS.
- Build/deployment artifacts (Maven wrapper, pom.xml, template.yml).
- Environment/configuration layering (application.properties).
- Optional vs. primary deployment topology (EC2 container vs. Lambda).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Layer
    subgraph "Infrastructure" 
        style Infrastructure fill:#B3E5FC,stroke:#0288D1
        Client["Client (Web/Mobile)"]:::external
        APIGW["API Gateway / ELB"]:::infra
        EC2["AWS EC2 / Container"]:::infra
        RDS["PostgreSQL (RDS)"]:::database
        OAuth["Google OAuth2"]:::external
    end

    Client --> APIGW
    APIGW --> EC2

    %% Spring Boot Monolith
    subgraph "Spring Boot Application" 
        style SpringBootApplication fill:#E8F5E9,stroke:#2E7D32
        Entry["WnabudgetBackendApplication"]:::appEntry

        subgraph "Security Layer" 
            style SecurityLayer fill:#FFF3E0,stroke:#EF6C00
            Security["Spring Security Filters\n(JWT & OAuth2)"]:::security
        end

        subgraph "Security Configs & Utils" 
            style SecurityConfigs fill:#FFFDE7,stroke:#F9A825
            SC["SecurityConfig"]:::config
            JU["JwtUtil"]:::config
            JAF["JwtAuthenticationFilter"]:::config
            OAH["OAuth2SuccessHandler"]:::config
            CAE["CustomAuthenticationEntryPoint"]:::config
            SB["SecurityBeans"]:::config
            SU["SecurityUtil"]:::config
        end

        subgraph "Controllers" 
            style Controllers fill:#E1F5FE,stroke:#039BE5
            AC["AccountController"]:::controller
            CGC["CategoryGroupController"]:::controller
            CC["CategoryController"]:::controller
            TC["TransactionController"]:::controller
            UC["UserController"]:::controller
            AuthC["AuthController"]:::controller
            PingC["PingController"]:::controller
        end

        subgraph "Services" 
            style Services fill:#E8EAF6,stroke:#5C6BC0
            AS["AccountService"]:::service
            CGS["CategoryGroupService"]:::service
            CS["CategoryService"]:::service
            TS["TransactionService"]:::service
        end

        subgraph "Repositories" 
            style Repositories fill:#F3E5F5,stroke:#8E24AA
            AR["AccountRepository"]:::repository
            CGR["CategoryGroupRepository"]:::repository
            CR["CategoryRepository"]:::repository
            TR["TransactionRepository"]:::repository
            UR["UserRepository"]:::repository
        end

        Entry --> SC
        SC --> Security
        JU --> Security
        JAF --> Security
        OAH --> Security
        CAE --> Security
        SB --> Security
        SU --> Security

        Security --> AC
        Security --> CGC
        Security --> CC
        Security --> TC
        Security --> UC
        Security --> AuthC
        Security --> PingC

        AC --> AS
        CGC --> CGS
        CC --> CS
        TC --> TS
        UC --> AS
        AuthC --> AS
        PingC --> AS

        AS --> AR
        CGS --> CGR
        CS --> CR
        TS --> TR
        AS --> UR

        AR --> RDS
        CGR --> RDS
        CR --> RDS
        TR --> RDS
        UR --> RDS
    end

    EC2 --> Entry
    Security --> OAuth

    %% Optional Serverless Variant
    subgraph "Optional Serverless" 
        style OptionalServerless fill:#FFE0B2,stroke:#FB8C00
        APIGW2["API Gateway"]:::infra
        Lambda["AWS Lambda\n(StreamLambdaHandler)"]:::infra
        Template["SAM Template\n(template.yml)"]:::infra
    end

    APIGW2 --> Lambda
    Lambda --> Entry
    Lambda --> Template

    %% Click Events
    click Entry "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/WnabudgetBackendApplication.java"
    click Lambda "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/StreamLambdaHandler.java"
    click Template "https://github.com/eric8900/weneedabudget-backend/blob/master/template.yml"
    click SC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/SecurityConfig.java"
    click JU "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/JwtUtil.java"
    click JAF "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/JwtAuthenticationFilter.java"
    click OAH "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/OAuth2SuccessHandler.java"
    click CAE "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/CustomAuthenticationEntryPoint.java"
    click SB "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/SecurityBeans.java"
    click SU "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/config/SecurityUtil.java"
    click AC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/AccountController.java"
    click CGC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/CategoryGroupController.java"
    click CC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/CategoryController.java"
    click TC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/TransactionController.java"
    click UC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/UserController.java"
    click AuthC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/AuthController.java"
    click PingC "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/controller/PingController.java"
    click AS "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/service/AccountService.java"
    click CGS "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/service/CategoryGroupService.java"
    click CS "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/service/CategoryService.java"
    click TS "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/service/TransactionService.java"
    click AR "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/repository/AccountRepository.java"
    click CGR "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/repository/CategoryGroupRepository.java"
    click CR "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/repository/CategoryRepository.java"
    click TR "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/repository/TransactionRepository.java"
    click UR "https://github.com/eric8900/weneedabudget-backend/blob/master/src/main/java/com/example/wnabudgetbackend/repository/UserRepository.java"

    %% Styles
    classDef infra fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef external fill:#CFD8DC,stroke:#455A64,color:#455A64;
    classDef database fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef appEntry fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32;
    classDef security fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00;
    classDef config fill:#FFFDE7,stroke:#F9A825,color:#F9A825;
    classDef controller fill:#E1F5FE,stroke:#039BE5,color:#039BE5;
    classDef service fill:#E8EAF6,stroke:#5C6BC0,color:#5C6BC0;
    classDef repository fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA;
    classDef model fill:#E0F2F1,stroke:#004D40,color:#004D40;
```
