# sushanttx/fullstack-filestorage architecture

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

- Interactive diagram: https://gitdiagram.com/sushanttx/fullstack-filestorage
- Repository: https://github.com/sushanttx/fullstack-filestorage

## Overview

1. **Overall shape**
This repo is a full-stack application with a **Spring Boot backend** and **two frontend implementations**: **React** and **Angular**. The backend is the system of record; the frontends are alternative clients that call the same REST API.

2. **Core domain**
The main business domain is **customer management with profile image storage**. The README describes the product as a file storage app, but the code strongly centers on customers, authentication, and customer profile pictures. Customer records live in the database, while image blobs are handled separately through the storage layer.

3. **Backend entry points**
The backend is a **single Spring Boot service** under `backend/`. Main API surfaces are:
- `AuthenticationController` for login/token issuance
- `CustomerController` for customer CRUD and related operations
- `PingPongController` for health/demo-style reachability
This is not a microservices repo in code structure; it is a **modular monolith** with clear package boundaries.

4. **Request flow**
A typical request path is:
**Browser/UI → REST endpoint → service layer → data access / storage → PostgreSQL and/or S3 → response DTO**.  
The backend uses DTOs and mapping classes to avoid exposing persistence entities directly to the clients.

5. **Authentication and authorization**
Security is JWT-based:
- `AuthenticationService` authenticates credentials
- `JWTUtil` creates/parses tokens
- `JWTAuthenticationFilter` protects requests
- `SecurityConfig` / `SecurityFilterChainConfig` define access rules
- `DelegatedAuthEntryPoint` and exception handlers shape unauthorized/error responses
The frontend stores and forwards the token via its client-side auth plumbing.

6. **Customer subsystem**
The customer package contains the main business workflow:
- `CustomerService` orchestrates registration, updates, and retrieval
- `CustomerDao` abstracts persistence
- Multiple DAO implementations exist: **JDBC**, **JPA**, and **in-memory list** (`CustomerJDBCDataAccessService`, `CustomerJPADataAccessService`, `CustomerListDataAccessService`)
- `CustomerRepository` supports the JPA path
- `CustomerDTOMapper` converts entity → API model
This abstraction suggests the repository is teaching or comparing persistence strategies, not just using one fixed repository pattern.

7. **Storage subsystem**
The `s3` package indicates a separate storage boundary for profile images/files:
- `S3Service` encapsulates object storage operations
- `S3Config` / `S3Buckets` hold configuration
- `FakeS3` exists for local/test substitution
The backend likely stores image metadata with the customer row and the file itself in S3-compatible storage.

8. **Database and schema management**
Persistence is backed by **PostgreSQL**. Schema evolution is managed with **Flyway** migrations in `backend/src/main/resources/db/migration`:
- initial setup
- later addition of a customer profile image column/structure  
This means the backend expects a relational database as the canonical store for users/customers and auth-related data.

9. **Frontend boundaries**
There are two client apps:
- **React** in `frontend/react`
- **Angular** in `frontend/angular`
Both have their own components, auth services, customer services, route protection/guards, and environment configuration. The React app also has a context-based auth layer and protected routes. In the architecture diagram, treat them as **separate presentation-layer options** rather than one combined UI.

10. **UI-to-API interaction**
The frontends model the same backend contracts:
- authentication request/response
- customer registration/update DTOs
- customer DTOs
They each handle login, signup, customer browsing, create/update flows, and token-based API calls. The backend remains stateless from the UI’s perspective except for JWT handling.

11. **Validation and error handling**
The backend has dedicated exception types and a global handler:
- `DuplicateResourceException`
- `ResourceNotFoundException`
- `RequestValidationException`
- `DefaultExceptionHandler`
- `ApiError`
This keeps the API responses consistent and gives the frontends predictable failure modes for form validation and authorization errors.

12. **Infrastructure and deployment**
The repo is container-first:
- backend and frontend Dockerfiles
- `docker-compose.yml` for local orchestration
- `nginx.conf` for reverse proxy behavior
- `Dockerrun.aws.json` and CI/CD workflows for AWS Elastic Beanstalk-style deployment
The deployment boundary is therefore: **containerized frontend(s) + containerized Spring Boot API + PostgreSQL**.

13. **Testing and verification**
The backend has a strong test split:
- unit tests for customer services and mappers
- integration tests with **Testcontainers**
- journey tests for authentication and customer flows
This suggests the system’s important contract boundaries are API behavior, persistence behavior, and storage behavior, not just isolated methods.

14. **What to draw in an architecture diagram**
The key diagram boxes should be:
- browser/client UI
- React frontend
- Angular frontend
- Spring Boot backend
- JWT/security layer
- customer service + DAO/repository layer
- S3/object storage
- PostgreSQL
- CI/CD + container/deployment layer  
The main arrows are authenticated REST calls from the UI to backend, and backend writes/reads to PostgreSQL plus S3 for image assets.

Main entry points: [`backend/src/main/java/com/sushant/Main.java`](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/Main.java) (Spring API), [`docker-compose.yml`](https://github.com/sushanttx/fullstack-filestorage/blob/main/docker-compose.yml) (Deploy Stack), [`backend/src/main/java/com/sushant/customer/CustomerService.java`](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerService.java) (Customer Service), [`backend/src/main/java/com/sushant/customer/CustomerDao.java`](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerDao.java) (Customer DAO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_browser(("Browser<br/>client"))
  node_react_app["React App<br/>frontend<br/>[main.jsx]"]
  node_angular_app["Angular App<br/>frontend<br/>[main.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_api["Spring API<br/>[Main.java]"]
  node_auth_controller["Auth API<br/>controller"]
  node_customer_controller["Customer API<br/>controller"]
  node_security_layer["Security"]
  node_jwt_layer["JWT Layer<br/>token auth<br/>[JWTUtil.java]"]
  node_auth_service["Auth Service"]
  node_customer_service["Customer Service<br/>domain service"]
  node_customer_persistence["Customer DAO<br/>persistence<br/>[CustomerDao.java]"]
  node_customer_jpa_repo["JPA Repo"]
  node_customer_mapper["DTO Mapper<br/>mapping"]
  node_s3_storage["S3 Storage<br/>object storage<br/>[S3Service.java]"]
  node_exception_handling["Errors"]
end

subgraph group_infrastructure["Infrastructure"]
  node_postgresql[("PostgreSQL<br/>relational db")]
  node_flyway_migrations["Migrations<br/>schema evolution"]
  node_deploy_stack["Deploy Stack<br/>containers/cicd<br/>[docker-compose.yml]"]
end

node_browser -->|"uses"| node_react_app
node_browser -->|"uses"| node_angular_app
node_react_app -->|"REST"| node_backend_api
node_angular_app -->|"REST"| node_backend_api
node_backend_api -->|"protects"| node_security_layer
node_security_layer -->|"uses"| node_jwt_layer
node_backend_api -->|"routes"| node_auth_controller
node_auth_controller -->|"delegates"| node_auth_service
node_backend_api -->|"routes"| node_customer_controller
node_customer_controller -->|"delegates"| node_customer_service
node_customer_service -->|"persists via"| node_customer_persistence
node_customer_persistence -->|"jpa path"| node_customer_jpa_repo
node_customer_service -->|"maps"| node_customer_mapper
node_customer_service -->|"stores images"| node_s3_storage
node_customer_persistence -->|"reads/writes"| node_postgresql
node_flyway_migrations -->|"migrates"| node_postgresql
node_backend_api -.->|"loads schema"| node_flyway_migrations
node_backend_api -->|"formats errors"| node_exception_handling
node_deploy_stack -->|"runs"| node_backend_api
node_deploy_stack -->|"runs"| node_react_app
node_deploy_stack -->|"runs"| node_angular_app
node_deploy_stack -->|"depends on"| node_postgresql

click node_react_app "https://github.com/sushanttx/fullstack-filestorage/blob/main/frontend/react/src/main.jsx"
click node_angular_app "https://github.com/sushanttx/fullstack-filestorage/blob/main/frontend/angular/src/main.ts"
click node_backend_api "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/Main.java"
click node_auth_controller "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/auth/AuthenticationController.java"
click node_customer_controller "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerController.java"
click node_security_layer "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/security/SecurityConfig.java"
click node_jwt_layer "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/jwt/JWTUtil.java"
click node_auth_service "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/auth/AuthenticationService.java"
click node_customer_service "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerService.java"
click node_customer_persistence "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerDao.java"
click node_customer_jpa_repo "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerRepository.java"
click node_customer_mapper "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerDTOMapper.java"
click node_s3_storage "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/s3/S3Service.java"
click node_exception_handling "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/exception/DefaultExceptionHandler.java"
click node_flyway_migrations "https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/resources/db/migration/V1__Initial_Setup.sql"
click node_deploy_stack "https://github.com/sushanttx/fullstack-filestorage/blob/main/docker-compose.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_browser,node_react_app,node_angular_app toneBlue
class node_backend_api,node_auth_controller,node_customer_controller,node_security_layer,node_jwt_layer,node_auth_service,node_customer_service,node_customer_persistence,node_customer_jpa_repo,node_customer_mapper,node_s3_storage,node_exception_handling toneAmber
class node_postgresql,node_flyway_migrations,node_deploy_stack toneMint
```

## Components

### Presentation

Alternative client applications that call the same backend API.

- **Browser**: client · End-user entry point for either frontend.
- [React App](https://github.com/sushanttx/fullstack-filestorage/blob/main/frontend/react/src/main.jsx): frontend · React client with auth context and protected routes. · `frontend/react/src/main.jsx`
- [Angular App](https://github.com/sushanttx/fullstack-filestorage/blob/main/frontend/angular/src/main.ts): frontend · Angular client with route guards, services, and interceptors. · `frontend/angular/src/main.ts`

### Backend

Spring Boot modular monolith exposing authentication and customer APIs.

- [Spring API](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/Main.java): service · Single Spring Boot application entry point. · `backend/src/main/java/com/sushant/Main.java`
- [Auth API](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/auth/AuthenticationController.java): controller · Login and token issuance endpoints. · `backend/src/main/java/com/sushant/auth/AuthenticationController.java`
- [Customer API](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerController.java): controller · Customer CRUD and profile-image endpoints. · `backend/src/main/java/com/sushant/customer/CustomerController.java`
- [Security](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/security/SecurityConfig.java): jwt security · Request filtering and access rules for protected endpoints. · `backend/src/main/java/com/sushant/security/SecurityConfig.java`
- [JWT Layer](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/jwt/JWTUtil.java): token auth · Token creation, parsing, and authentication filter. · `backend/src/main/java/com/sushant/jwt/JWTUtil.java`
- [Auth Service](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/auth/AuthenticationService.java): auth service · Validates credentials and issues auth responses. · `backend/src/main/java/com/sushant/auth/AuthenticationService.java`
- [Customer Service](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerService.java): domain service · Coordinates customer registration, update, and lookup workflows. · `backend/src/main/java/com/sushant/customer/CustomerService.java`
- [Customer DAO](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerDao.java): persistence · Persistence boundary with JDBC, JPA, and in-memory implementations. · `backend/src/main/java/com/sushant/customer/CustomerDao.java`
- [JPA Repo](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerRepository.java): repository · Spring Data repository backing the JPA path. · `backend/src/main/java/com/sushant/customer/CustomerRepository.java`
- [DTO Mapper](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/customer/CustomerDTOMapper.java): mapping · Maps customer entities to API DTOs. · `backend/src/main/java/com/sushant/customer/CustomerDTOMapper.java`
- [S3 Storage](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/s3/S3Service.java): object storage · Encapsulates profile image and file-object storage. · `backend/src/main/java/com/sushant/s3/S3Service.java`
- [Errors](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/java/com/sushant/exception/DefaultExceptionHandler.java): api errors · Global exception handling and API error responses. · `backend/src/main/java/com/sushant/exception/DefaultExceptionHandler.java`

### Infrastructure

Database, storage, schema migration, and deployment concerns.

- **PostgreSQL**: relational db · Primary relational store for customers and auth-related data.
- [Migrations](https://github.com/sushanttx/fullstack-filestorage/blob/main/backend/src/main/resources/db/migration/V1__Initial_Setup.sql): schema evolution · Database schema setup and profile-image migration scripts. · `backend/src/main/resources/db/migration/V1__Initial_Setup.sql`
- [Deploy Stack](https://github.com/sushanttx/fullstack-filestorage/blob/main/docker-compose.yml): containers/cicd · Docker, compose, nginx, and AWS deployment wiring. · `docker-compose.yml`

## Connections

- Browser → React App: uses · Browser loads the React client.
- Browser → Angular App: uses · Browser loads the Angular client.
- React App → Spring API: REST · React calls the shared backend API.
- Angular App → Spring API: REST · Angular calls the shared backend API.
- Spring API → Security: protects · Backend request handling is gated by Spring Security.
- Security → JWT Layer: uses · Security configuration relies on JWT filtering and token utilities.
- Spring API → Auth API: routes · Authentication endpoints are exposed by the backend.
- Auth API → Auth Service: delegates · Controller delegates login/token work to the service layer.
- Spring API → Customer API: routes · Customer endpoints are exposed by the backend.
- Customer API → Customer Service: delegates · Controller delegates customer workflows to the service layer.
- Customer Service → Customer DAO: persists via · Customer service uses the DAO abstraction.
- Customer DAO → JPA Repo: jpa path · One persistence path goes through Spring Data JPA.
- Customer Service → DTO Mapper: maps · Service/API boundary uses DTO mapping for responses.
- Customer Service → S3 Storage: stores images · Customer profile images are managed through object storage.
- Customer DAO → PostgreSQL: reads/writes · Customer data is stored in PostgreSQL.
- Migrations → PostgreSQL: migrates · Flyway evolves the database schema.
- Spring API → Migrations: loads schema · Backend startup expects migrated relational schema.
- Spring API → Errors: formats errors · Exceptions are converted to consistent API responses.
- Deploy Stack → Spring API: runs · Container and deployment layer packages the backend service.
- Deploy Stack → React App: runs · Container and deployment layer packages the React client.
- Deploy Stack → Angular App: runs · Container and deployment layer can package the Angular client.
- Deploy Stack → PostgreSQL: depends on · Local and deployed stacks depend on PostgreSQL.